require(["deliteful/Combobox"], function (Combobox) {
new Combobox();
});
A form-aware and store-aware multichannel widget leveraging the deliteful/list/List
widget for rendering the options.
The corresponding custom tag is <d-combobox>
.
The property list
allows to specify the List instance used by the widget.
The customization of the mapping of data item attributes into render item
attributes can be done on the List
instance using the mapping API of List
inherited from its superclass delite/StoreMap
.
The property selectionMode
allows to choose between single and multiple
choice modes.
In single selection mode, if the property autoFilter
is set to true
(default is false
) the widget allows to type one or more characters which
are used for filtering the shown list items. By default, the filtering is
case-insensitive, and an item is shown if its label contains the entered
string. The default filtering policy can be customized thanks to the
filterMode
and ignoreCase
properties.
The widget provides multichannel rendering. Depending on the required channel, which
is determined by the value of the channel flags of deliteful/features
, the
widget displays the popup containing the options in a different manner:
- if
has("desktop-like-channel")
istrue
: in a popup below or above the root node. - otherwise (that is for
"phone-like-channel"
and"tablet-like-channel"
): in an overlay centered on the screen, filled with an instance ofdeliteful/Combobox/ComboPopup
.
The channel flags are set by deliteful/features
using CSS media queries depending on
the screen size. See the deliteful/features
documentation for information about the
channel flags and about how to configure them statically and how to customize the values
of the screen size breakpoints used by the media queries.
The value
property of the widget contains:
- Single selection mode: the value of the selected list items. By default, the value of the first item is selected.
- Multiple selection mode: an array containing the values of the selected items.
Defaults to
[]
.
If the widget is used in an HTML form, the submitted value contains:
- Single selection mode: the same as widget's
value
property. - Multiple selection mode: a string containing a comma-separated list of the values
of the selected items. Defaults to
""
.
- Single selection mode: the same as widget's
By default, the label
field of the list render item is used as item value.
A different field can be specified by using attribute mapping for value
on the
List instance.
Remark: the option items must be added, removed or updated exclusively using List's store API. Direct operations using the DOM API are not supported.
- Source:
Examples
JS:
require(["deliteful/Combobox", "requirejs-domready/domReady!"],
function () {
});
HTML:
<d-combobox id="combobox1">
<d-list>
{ "label": "France", "sales": 500, "profit": 50, "region": "EU" },
{ "label": "Germany", "sales": 450, "profit": 48, "region": "EU" },
{ "label": "UK", "sales": 700, "profit": 60, "region": "EU" },
{ "label": "USA", "sales": 2000, "profit": 250, "region": "America" },
{ "label": "Canada", "sales": 600, "profit": 30, "region": "America" },
{ "label": "Brazil", "sales": 450, "profit": 30, "region": "America" },
{ "label": "China", "sales": 500, "profit": 40, "region": "Asia" },
{ "label": "Japan", "sales": 900, "profit": 100, "region": "Asia" }
</d-list>
</d-combobox>
JS:
require(["deliteful/List",
"deliteful/Combobox", ..., "requirejs-domready/domReady!"],
function (List, Combobox, ...) {
var dataStore = ...; // Create data store
var list = new List({source: dataStore});
var combobox = new Combobox({list: list, selectionMode: "multiple"}).
placeAt(...);
});
Extends
Show inheritedMembers
-
alt :string
-
Corresponds to the native HTML
<input>
element's attribute.Type:
- string
- Inherited From:
- Source:
-
<protected> aroundNode :Element
-
The node to display the popup around. Can be set in a template via a
attach-point
assignment. If missing, thenthis.domNode
will be used.Type:
- Element
- Inherited From:
- Source:
-
<protected> attached :boolean
-
Set to true when
attachedCallback()
has completed, and false whendetachedCallback()
called.Type:
- boolean
- Inherited From:
- Source:
-
autoFilter :boolean
-
If
true
, the filtering of list items ignores case when matching possible items. Only used ifautoFilter
istrue
andselectionMode
is"single"
.Type:
- boolean
- Default Value:
- true
- Source:
-
autoWidth :boolean
-
If true, make the drop down at least as wide as this widget. If false, leave the drop down at its default width. Has no effect when
dropDownPosition = ["center"]
.Type:
- boolean
- Inherited From:
- Default Value:
- true
- Source:
-
<protected> baseClass :string
-
Root CSS class of the widget (ex: "d-text-box")
Type:
- string
- Inherited From:
- Source:
-
<protected> buttonNode :Element
-
The button/icon/node to click to display the drop down. Can be set in a template via a
attach-point
assignment. If missing, then eitherthis.focusNode
orthis.domNode
(iffocusNode
is also missing) will be used.Type:
- Element
- Inherited From:
- Source:
-
cancelMsg :string
-
The text displayed in the Cancel button when the combobox popup contains such a button. The default value is provided by the "cancel-button-label" key of the message bundle.
Type:
- string
- Default Value:
- "Cancel"
- Source:
-
<protected> created :boolean
-
Set to true when
createdCallback()
has completed.Type:
- boolean
- Inherited From:
- Source:
-
dir :string
-
Controls the layout direction of the widget, for example whether the arrow of a Combobox appears to the right or the left of the input field.
Values are "ltr" and "rtl", or "" which means that the value is inherited from the setting on the document root (either
<html>
or<body>
).Type:
- string
- Inherited From:
- Source:
-
disabled :boolean
-
If set to true, the widget will not respond to user input and will not be included in form submission. FormWidget automatically updates
valueNode
's andfocusNode
'sdisabled
property to match the widget'sdisabled
property.Type:
- boolean
- Inherited From:
- Default Value:
- false
- Source:
-
dropDown :Element
-
The widget to display as a popup. Applications/subwidgets should either:
- define this property
- override
loadDropDown()
to return a dropdown widget or Promise for one - listen for a
delite-display-load
event, and then call event.setChild() with an Object like{child: dropDown}
or a Promise for such an Object
Type:
- Element
- Inherited From:
- Source:
-
dropDownPosition :Array.<string>
-
Controls the position of the drop down. It's an array of strings with the following values:
- before: places drop down to the left of the target node/widget, or to the right in the case of RTL scripts like Hebrew and Arabic
- after: places drop down to the right of the target node/widget, or to the left in the case of RTL scripts like Hebrew and Arabic
- above: drop down goes above target node
- below: drop down goes below target node
- center: drop down is centered on the screen, like a dialog; when used, this should be the only choice in the array
The positions are tried, in order, until a position is found where the drop down fits within the viewport.
Type:
- Array.<string>
- Inherited From:
- Default Value:
- ["below", "above"]
- Source:
-
<readonly> effectiveDir :string
-
Actual direction of the widget, which can be set explicitly via
dir
property or inherited from the setting on the document root (either<html>
or<body>
). Value is either "ltr" or "rtl".Type:
- string
- Inherited From:
- Source:
-
filterMode :string
-
The chosen filter mode. Only used if
autoFilter
istrue
andselectionMode
is"single"
.Valid values are:
- "startsWith": the item matches if its label starts with the filter text.
- "contains": the item matches if its label contains the filter text.
- "is": the item matches if its label is the filter text.
Type:
- string
- Default Value:
- "startsWith"
- Source:
-
<protected> focused :boolean
-
This widget or a widget it contains has focus, or is "active" because it was recently clicked.
Type:
- boolean
- Inherited From:
- Default Value:
- false
- Source:
-
<protected> focusNode :HTMLElement
-
For widgets with a single tab stop, the Element within the widget, often an
<input>
, that gets the focus. Widgets with multiple tab stops, such as a range slider, should settabStops
rather than settingfocusNode
.Type:
- HTMLElement
- Inherited From:
- Source:
-
focusOnKeyboardOpen :boolean
-
Focus the popup when opened by the keyboard. This flag should be left as
true
except for widgets like Combobox where the focus is meant to always remain on the HasDropDown widget itself.Type:
- boolean
- Inherited From:
- Default Value:
- true
- Source:
-
focusOnPointerOpen :boolean
-
Focus the popup when opened by mouse or touch. This flag should generally be left as
true
unless the popup is a menu. Usually drop down menus don't get focus unless opened by the keyboard.Type:
- boolean
- Inherited From:
- Default Value:
- true
- Source:
-
forceWidth :boolean
-
If true, make the drop down exactly as wide as this widget. Overrides
autoWidth
. Has no effect whendropDownPosition = ["center"]
.Type:
- boolean
- Inherited From:
- Default Value:
- false
- Source:
-
list :module:deliteful/list/List
-
The
deliteful/list/List
element which provides and renders the options shown by the popup of the Combobox. Note that this property is set by default to a newly created instance ofdeliteful/list/List
.Type:
- Default Value:
- instance of deliteful/list/List
- Source:
-
maxHeight :number
-
The maximum height for our dropdown. Any dropdown taller than this will have a scroll bar. Set to 0 for no max height, or -1 to limit height to available space in viewport.
Type:
- number
- Inherited From:
- Default Value:
- -1
- Source:
-
multipleChoiceMsg :string
-
The text displayed in the input element when more than one option is selected. The default value is provided by the "search-placeholder" key of the message bundle.
Type:
- string
- Default Value:
- "Search"
- Source:
-
multipleChoiceNoSelectionMsg :string
-
The text displayed in the input element when no option is selected. The default value is provided by the "multiple-choice-no-selection" key of the message bundle.
Type:
- string
- Default Value:
- "Select option(s)"
- Source:
-
name :string
-
Name used when submitting form; same as "name" attribute or plain HTML elements.
Type:
- string
- Inherited From:
- Source:
-
okMsg :string
-
The text displayed in the OK button when the combobox popup contains such a button. The default value is provided by the "ok-button-label" key of the message bundle.
Type:
- string
- Default Value:
- "OK"
- Source:
-
<readonly> opened :boolean
-
Whether or not the drop down is open.
Type:
- boolean
- Inherited From:
- Source:
-
<protected> popupStateNode :Element
-
The node to set the
aria-expanded
class on. Can be set in a template via aattach-point
assignment. If missing, thenthis.focusNode
orthis.buttonNode
(iffocusNode
is missing) will be used.Type:
- Element
- Inherited From:
- Source:
-
readOnly :boolean
-
If true, this widget won't respond to user input. Similar to
disabled
exceptreadOnly
form values are submitted. FormValueWidget automatically updatesfocusNode
'sreadOnly
property to match the widget'sreadOnly
property.Type:
- boolean
- Inherited From:
- Default Value:
- false
- Source:
-
searchPlaceHolder :string
-
The value of the placeholder attribute of the input element used for filtering the list of options. The default value is provided by the "search-placeholder" key of the message bundle.
Type:
- string
- Default Value:
- "Search"
- Source:
-
selectionMode :string
-
The chosen selection mode.
Valid values are:
- "single": Only one option can be selected at a time.
- "multiple": Several options can be selected.
The value of this property determines the value of the
selectionMode
property of the List instance used by this widget for displaying the options:- The value "single" is mapped to "radio".
- The value "multiple" is mapped to "multiple".
Note that, regardless of the selection mode, it is always possible to set several selected items using the
selectedItem
orselectedItems
properties of the List instance. The mode will be enforced only when usingsetSelected()
and/orselectFromEvent()
APIs of the List.Type:
- string
- Default Value:
- "single"
- Source:
-
tabIndex :number
-
The order in which fields are traversed when user presses the tab key.
Type:
- number
- Inherited From:
- Default Value:
- 0
- Source:
-
tabStops :string
-
Comma separated list of tabbable nodes, i.e. comma separated list of widget properties that reference the widget DOM nodes that receive focus during tab operations.
Aria roles are applied to these nodes rather than the widget root node.
Note that FormWidget requires that all of the tabbable nodes be sub-nodes of the widget, rather than the root node. This is because of its processing of
tabIndex
.Type:
- string
- Inherited From:
- Default Value:
- "focusNode"
- Source:
-
<protected> template :function
-
Value returned by delite/handlebars! or compatible template engine. Specifies how to build the widget DOM initially and also how to update the DOM when widget properties change.
Type:
- function
- Inherited From:
- Source:
-
value :string
-
Corresponds to the native HTML
<input>
element's attribute.For widgets that directly extend FormWidget (ex: checkboxes), the value is set programatically when the widget is created, and the end user merely changes the widget's state, i.e. the
checked
property.For widgets that extend FormValueWidget, the end user can interactively change the
value
property via mouse, keyboard, touch, etc.Type:
- string
- Inherited From:
- Source:
-
<protected> valueNode :HTMLElement
-
A form element, typically an
<input>
, embedded within the widget, and likely hidden. It is used to represent the widget's state/value during form submission.Subclasses of FormWidget like checkboxes and radios should update
valueNode
'schecked
property.Type:
- HTMLElement
- Inherited From:
- Default Value:
- undefined
- Source:
-
<protected, constant> widgetId :number
-
Unique id for this widget, separate from id attribute (which may or may not be set). Useful when widget creates subnodes that need unique id's.
Type:
- number
- Inherited From:
- Source:
Methods
-
<protected> _get(name) → {*}
-
Internal helper for directly accessing an attribute value.
Directly gets the value of an attribute on an object, bypassing any accessor getter. It is designed to be used by descendant class if they want to access the value in their custom getter before returning it.
Parameters:
Name Type Description name
string Name of property.
- Inherited From:
- Source:
Returns:
Value of property.
- Type
- *
-
<protected> _set(name, value)
-
Internal helper for directly setting a property value without calling the custom setter.
Directly changes the value of an attribute on an object, bypassing any accessor setter. Also notifies callbacks registered via observe(). Custom setters should call
_set
to actually record the new value.Parameters:
Name Type Description name
string The property to set.
value
* Value to set the property to.
- Inherited From:
- Source:
-
<protected> afterFormResetCallback()
-
Callback after
<form>
containing this widget is reset. By the time this callback executes,this.valueNode.value
will have already been reset according to the form's original value.- Inherited From:
- Source:
-
attachedCallback()
-
Called automatically when the element is added to the document, after
createdCallback()
completes. This method is automatically chained, so subclasses generally do not need to usedcl.superCall()
,dcl.advise()
, etc.- Inherited From:
- Source:
Fires:
-
<protected> closeDropDown(focus)
-
Closes the drop down on this widget.
Parameters:
Name Type Argument Description focus
boolean <optional>
If true, refocus this widget.
- Inherited From:
- Source:
Fires:
-
<protected> compare(val1, val2) → {number}
-
Compare two values (of this widget).
Parameters:
Name Type Description val1
* val2
* - Inherited From:
- Source:
Returns:
- Type
- number
-
computeProperties(oldValues, isAfterCreation)
-
Callback function to calculate computed properties upon property changes.
Parameters:
Name Type Description oldValues
Object The hash table of old property values, keyed by property names.
isAfterCreation
boolean True if this call is right after instantiation.
- Inherited From:
- Source:
-
<protected> createAboveBelowDropDown()
-
Factory method which creates the widget used inside above/below drop-down. The default implementation simply returns
this.list
.- Source:
-
<protected> createCenteredDropDown()
-
Factory method which creates the widget used inside centered drop-down. The default implementation returns a new instance of deliteful/Combobox/ComboPopup (the present widget is set for its
combobox
property). The method can be overridden in order to create a subclass of ComboPopup (for specifying a custom template, for instance).- Source:
-
<protected> createdCallback()
-
Called when the custom element is created, or when
register.parse()
parses a custom tag.This method is automatically chained, so subclasses generally do not need to use
dcl.superCall()
,dcl.advise()
, etc.- Inherited From:
- Source:
-
<protected> defer(fcn, delay) → {Object}
-
Wrapper to setTimeout to avoid deferred functions executing after the originating widget has been destroyed.
Parameters:
Name Type Description fcn
function Function to be executed after specified delay (or 0ms if no delay specified).
delay
number Delay in ms, defaults to 0.
- Inherited From:
- Source:
Returns:
Handle with a remove method that deschedules the callback from being called.
- Type
- Object
-
deliver()
-
Synchronously deliver change records to all listeners registered via
observe()
.- Inherited From:
- Source:
-
deliverComputing()
-
Synchronously deliver change records for computed properties so that
computeProperties()
is called if there are pending change records.- Inherited From:
- Source:
-
destroy()
-
Release resources used by this custom element and its descendants. After calling this method, the element can no longer be used, and should be removed from the document.
- Inherited From:
- Source:
-
detachedCallback()
-
Called when the element is removed the document. This method is automatically chained, so subclasses generally do not need to use
dcl.superCall()
,dcl.advise()
, etc.- Inherited From:
- Source:
-
discardChanges()
-
Discard change records for all listeners registered via
observe()
.- Inherited From:
- Source:
-
discardComputing()
-
Discard change records for computed properties.
- Inherited From:
- Source:
-
<protected> emit(type, eventObj) → {boolean}
-
Emits a synthetic event of specified type, based on eventObj.
Parameters:
Name Type Argument Description type
string Name of event.
eventObj
Object <optional>
Properties to mix in to emitted event. Can also contain
bubbles
andcancelable
properties to control how the event is emitted.- Inherited From:
- Source:
Returns:
True if the event was not canceled, false if it was canceled.
- Type
- boolean
Example
myWidget.emit("query-success", {});
-
<protected> filter()
-
Filters the embedded List to only show the items matching
filterTxt
. IfautoFilter
istrue
andselectionMode
is"single"
, the method is called automatically while the user types into the editable input element, withfilterTxt
being the currently entered text. The default implementation usesdstore/Filter.match()
. The matching is performed against thelist.labelAttr
attribute of the data store items. The method can be overridden for implementing other filtering strategies.- Source:
-
findCustomElements(root)
-
Search subtree under root returning custom elements found.
Parameters:
Name Type Argument Description root
Element <optional>
Node to search under.
- Inherited From:
- Source:
-
<protected> firstFocusNode()
-
Helper method to get the first focusable node, usually
this.focusNode
.- Inherited From:
- Source:
-
focus()
-
Put focus on this widget.
- Inherited From:
- Source:
-
<protected> forEachFocusNode(callback)
-
Helper method to execute callback for each focusable node in the widget. Typically the callback is just called once, for
this.focusNode
.Parameters:
Name Type Description callback
function The callback function.
- Inherited From:
- Source:
-
getEnclosingWidget(node)
-
Returns the widget whose DOM tree contains the specified DOMNode, or null if the node is not contained within the DOM tree of any widget
Parameters:
Name Type Description node
Element - Inherited From:
- Source:
-
<protected> getInheritedDir() → {string}
-
Get the direction setting for the page itself.
- Inherited From:
- Source:
Returns:
"ltr" or "rtl"
- Type
- string
-
getParent()
-
Returns the parent widget of this widget, or null if there is no parent widget.
- Inherited From:
- Source:
-
<protected> getProps() → {Object}
-
Returns a hash of properties that should be observed.
- Inherited From:
- Source:
Returns:
Hash of properties.
- Type
- Object
-
<protected> getPropsToObserve() → {Array.<string>}
-
Get list of properties that Stateful#observe() should observe.
- Inherited From:
- Source:
Returns:
list of properties
- Type
- Array.<string>
-
<protected> handleOnChange(newValue)
-
Sets value and fires a "change" event if the value changed since the last call.
This method should be called when the value is committed, if that makes sense for the control, or else when the control loses focus. For example, it should be called when the user releases a slider's handle after dragging it, or when the user blurs a textbox. See https://html.spec.whatwg.org/multipage/forms.html#common-input-element-events for details.
Parameters:
Name Type Description newValue
* The new value.
- Inherited From:
- Source:
-
<protected> handleOnInput(newValue)
-
Sets value and fires an "input" event if the value changed since the last call.
This method should be called whenever the value is changed interactively by the end user. For example, it should be called repeatedly as the user drags the handle of a slider, or on every keystroke for a textbox. See https://html.spec.whatwg.org/multipage/forms.html#common-input-element-events for details.
Parameters:
Name Type Description newValue
* The new value.
- Inherited From:
- Source:
-
<protected> initializeInvalidating()
-
Make initial calls to
computeProperties()
,initializeRendering()
, andrefreshRendering()
, and setup observers so those methods are called whenever properties are modified in the future. Normally this method is called automatically by the constructor, and should not be called manually, but the method is exposed for custom elements since they do not call theconstructor()
method.- Inherited From:
- Source:
-
initializeRendering(oldValues)
-
Callback function to initialize rendering.
Parameters:
Name Type Description oldValues
Object The hash table of old property values, keyed by property names.
- Inherited From:
- Source:
-
<protected> introspect(props)
-
Sets up ES5 getters/setters for each class property. Inside introspect(), "this" is a reference to the prototype rather than any individual instance.
Parameters:
Name Type Description props
Object Hash of properties.
- Inherited From:
- Source:
-
<protected> loadDropDown() → {Element|Promise}
-
Creates/loads the drop down. Returns a Promise for the dropdown, or if loaded synchronously, the dropdown itself.
Applications must either:
- set the
dropDown
property to point to the dropdown (as an initialisation parameter) - override this method to create custom drop downs on the fly, returning a reference or promise for the dropdown
- listen for a
delite-display-load
event, and then call event.setChild() with an Object like{child: dropDown}
or a Promise for such an Object
With option (2) or (3) the application is responsible for destroying the dropdown.
- Inherited From:
- Source:
Fires:
Returns:
Element or Promise for the dropdown
- Type
- Element | Promise
- set the
-
mix(hash)
-
Set a hash of properties on a Stateful instance.
Parameters:
Name Type Description hash
Object Hash of properties.
- Inherited From:
- Source:
Example
myObj.mix({ foo: "Howdy", bar: 3 });
-
notifyCurrentValue(name)
-
Notifies current values to observers for specified property name(s). Handy to manually schedule invocation of observer callbacks when there is no change in value.
Parameters:
Name Type Argument Description name
string <repeatable>
The property name.
- Inherited From:
- Source:
-
observe(callback) → {module:decor/Stateful.PropertyListObserver}
-
Observes for change in properties. Callback is called at the end of micro-task of changes with a hash table of old values keyed by changed property. Multiple changes to a property in a micro-task are squashed.
Parameters:
Name Type Description callback
function The callback.
- Inherited From:
- Source:
Returns:
The observer that can be used to stop observation or synchronously deliver/discard pending change records.
Example
var stateful = new (dcl(Stateful, { foo: undefined, bar: undefined, baz: undefined }))({ foo: 3, bar: 5, baz: 7 }); stateful.observe(function (oldValues) { // oldValues is {foo: 3, bar: 5, baz: 7} }); stateful.foo = 4; stateful.bar = 6; stateful.baz = 8; stateful.foo = 6; stateful.bar = 8; stateful.baz = 10;
-
on(type, func, node) → {Object}
-
Call specified function when event occurs.
Note that the function is not run in any particular scope, so if (for example) you want it to run in the element's scope you must do
myCustomElement.on("click", myCustomElement.func.bind(myCustomElement))
.Note that
delite/Widget
overrideson()
so thaton("focus", ...)
and `on("blur", ...) will trigger the listener when focus moves into or out of the widget, rather than just when the widget's root node is focused/blurred. In other words, the listener is called when the widget is conceptually focused or blurred.Parameters:
Name Type Argument Description type
string Name of event (ex: "click").
func
function Callback function.
node
Element <optional>
Element to attach handler to, defaults to
this
.- Inherited From:
- Source:
Returns:
Handle with
remove()
method to cancel the event.- Type
- Object
-
<protected> openDropDown() → {Promise}
-
Creates the drop down if it doesn't exist, loads the data if there's an href and it hasn't been loaded yet, and then opens the drop down. This is basically a callback when the user presses the down arrow button to open the drop down.
- Inherited From:
- Source:
Fires:
- module:delite/HasDropDown#event:delite-before-show
- module:delite/HasDropDown#event:delite-after-show
Returns:
Promise for the drop down widget that fires when drop down is created and loaded.
- Type
- Promise
-
<protected> own() → {Array.<Object>}
-
Track specified handles and remove/destroy them when this instance is destroyed, unless they were already removed/destroyed manually.
- Inherited From:
- Source:
Returns:
The array of specified handles, so you can do for example:
var handle = this.own(on(...))[0];
- Type
- Array.<Object>
-
<protected> parseAttribute(name, value)
-
Helper for parsing declarative widgets. Interpret a given attribute specified in markup, returning either:
undefined
: ignore{prop: prop, value: value}
: setthis[prop] = value
{event: event, callback: callback}
: callthis.on(event, callback)
Parameters:
Name Type Description name
string Attribute name.
value
string Attribute value.
- Inherited From:
- Source:
-
<protected> parseFunctionAttribute(value, params)
-
Helper to parse function attribute in markup. Unlike
_parsePrototypeAttr()
, does not require a corresponding widget property. Functions can be specified as global variables or as inline javascript:Parameters:
Name Type Description value
string Value of the attribute.
params
Array.<string> When generating a function from inline javascript, give it these parameter names.
- Inherited From:
- Source:
-
<protected> placeAt(reference, position) → {module:delite/Widget}
-
Place this widget somewhere in the dom, and allow chaining.
Parameters:
Name Type Argument Description reference
string | Element | DocumentFragment Element, DocumentFragment, or id of Element to place this widget relative to.
position
string | number <optional>
Numeric index or a string with the values:
- number - place this widget as n'th child of
reference
node - "first" - place this widget as first child of
reference
node - "last" - place this widget as last child of
reference
node - "before" - place this widget as previous sibling of
reference
node - "after" - place this widget as next sibling of
reference
node - "replace" - replace specified reference node with this widget
- "only" - replace all children of
reference
node with this widget
- Inherited From:
- Source:
Returns:
This widget, for chaining.
- Type
- module:delite/Widget
Examples
// create a Button with no srcNodeRef, and place it in the body: var button = new Button({ label:"click" }).placeAt(document.body);
// place a new button as the first element of some div var button = new Button({ label:"click" }).placeAt("wrapper","first");
// create a contentpane and add it to a TabContainer var tc = document.getElementById("myTabs"); new ContentPane({ href:"foo.html", title:"Wow!" }).placeAt(tc)
- number - place this widget as n'th child of
-
<protected> postRender()
-
Processing after the DOM fragment is created.
Called after the DOM fragment has been created, but not necessarily added to the document. Do not include any operations which rely on node dimensions or placement.
This method is automatically chained, so subclasses generally do not need to use
dcl.superCall()
,dcl.advise()
, etc.- Inherited From:
- Source:
-
<protected> preRender()
-
Processing before
render()
.This method is automatically chained, so subclasses generally do not need to use
dcl.superCall()
,dcl.advise()
, etc.- Inherited From:
- Source:
-
<protected> processConstructorParameters()
-
Called after Object is created to process parameters passed to constructor.
- Inherited From:
- Source:
-
refreshRendering(oldValues, isAfterInitialRendering)
-
Callback function to render UI upon property changes.
Parameters:
Name Type Description oldValues
Object The hash table of old property values, keyed by property names.
isAfterInitialRendering
boolean True if this call is right after
initializeRendering()
.- Inherited From:
- Source:
-
<protected> render()
-
Construct the UI for this widget, filling in subnodes and/or text inside of this. Most widgets will leverage delite/handlebars! to set
template
, rather than defining this method.- Inherited From:
- Source:
-
<protected> setClassComponent(component, value, node)
-
Helper method to set a class (or classes) on a given node, removing the class (or classes) set by the previous call to
setClassComponent()
for the specified component and node. Used mainly by template.js to set classes without overwriting classes set by the user or other code (ex: CssState).Parameters:
Name Type Argument Description component
string Specifies the category.
value
string Class (or classes) to set.
node
HTMLElement <optional>
The node to set the property on; defaults to widget root node.
- Inherited From:
- Source:
-
<protected> setOrRemoveAttribute(node, name, value)
-
Helper method to set/remove an attribute based on the given value:
- If value is undefined, the attribute is removed. Useful for attributes like aria-valuenow.
- If value is boolean, the attribute is set to "true" or "false". Useful for attributes like aria-selected.
- If value is a number, it's converted to a string.
Parameters:
Name Type Description node
Element The node to set the property on.
name
string Name of the property.
value
string Value of the property.
- Inherited From:
- Source:
-
shouldInitializeRendering(oldValues, isAfterCreation) → {boolean}
-
Function to return if rendering should be initialized. (Instead of making partial changes for post-initialization)
Parameters:
Name Type Description oldValues
Object The hash table of old property values, keyed by property names.
isAfterCreation
boolean True if this call is right after instantiation.
- Inherited From:
- Source:
Returns:
True if rendering should be initialized.
- Type
- boolean
-
<protected> toggleDropDown()
-
Toggle the drop-down widget; if it is open, close it, if not, open it. Called when the user presses the down arrow button or presses the down arrow key to open/close the drop down.
- Inherited From:
- Source:
Events
-
customelement-attached
-
Dispatched after the CustomElement has been attached. This is useful to be notified when an HTMLElement has been upgraded to a CustomElement and attached to the DOM, in particular on browsers supporting native Custom Element.
- Inherited From:
- Source:
Example
element.addEventListener("customelement-attached", function (evt) { console.log("custom element: "+evt.target.id+" has been attached"); });
-
delite-after-hide
-
Dispatched after popup widget is hidden.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to popup
Example
document.addEventListener("delite-after-hide", function (evt) { console.log("just hid popup", evt.child); });
-
delite-after-show
-
Dispatched after popup widget is shown.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to popup
Example
document.addEventListener("delite-after-show", function (evt) { console.log("just displayed popup", evt.child); });
-
delite-before-hide
-
Dispatched before popup widget is hidden.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to popup
Example
document.addEventListener("delite-before-hide", function (evt) { console.log("about to hide popup", evt.child); });
-
delite-before-show
-
Dispatched before popup widget is shown.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to popup
Example
document.addEventListener("delite-before-show", function (evt) { console.log("about to show popup", evt.child); });