require(["deliteful/Select"], function (Select) {
new Select();
});
A form-aware and store-aware widget leveraging the native HTML5 <select>
element.
It has the following characteristics:
- The corresponding custom tag is
<d-select>
. - Allows to select one or more items among a number of options (in single
or multiple selection mode; see
selectionMode
). - Store support (limitation: to avoid graphic glitches, the updates to the
store should not be done while the native dropdown of the select is open).
The attributes of data items used for the
label
,value
, anddisabled
attributes of option elements can be customized using respectively thelabelAttr
,valueAttr
, anddisabledAttr
properties, or usinglabelFunc
,valueFunc
, anddisabledFunc
properties (for details, see the documentation of thedelite/StoreMap
superclass). - Form support (inherits from
delite/FormWidget
). - The item rendering has the limitations of the
<option>
elements of the native<select>
, in particular it is text-only.
Remarks:
- The option items must be added, removed or updated exclusively using the store API. Direct operations using the DOM API are not supported.
- The handling of the selected options of the underlying native
<select>
must be done using the API inherited by deliteful/Select from delite/Selection.
- Source:
Examples
JS:
require(["deliteful/Select", "requirejs-domready/domReady!"],
function () {
});
HTML:
<d-select id="select">
{text: "Option 1", value: "1"}
...
</d-select>
JS:
require(["dstore/Memory", "dstore/Trackable",
"deliteful/Select", "requirejs-domready/domReady!"],
function (Memory, Trackable) {
var store = new (Memory.createSubclass(Trackable))({});
select1.source = store;
store.add({text: "Option 1", value: "1"});
...
});
HTML:
<d-select selectionMode="multiple" id="select"></d-select>
Extends
Show inheritedMembers
-
allowRemap :boolean
-
Whether the created render items will be updated when call the remap() function on the component allowing the consuming component to re-perform the mapping on demand. This property must not be changed after the initialization cycle.
Type:
- boolean
- Inherited From:
- Default Value:
- false
- Source:
-
alt :string
-
Corresponds to the native HTML
<input>
element's attribute.Type:
- string
- Inherited From:
- Source:
-
<protected> attached :boolean
-
Set to true when
attachedCallback()
has completed, and false whendetachedCallback()
called.Type:
- boolean
- Inherited From:
- Source:
-
<protected> baseClass :string
-
Root CSS class of the widget (ex: "d-text-box")
Type:
- string
- Inherited From:
- Source:
-
copyAllItemProps :boolean
-
If true, in addition to the mapped properties copy all the other properties of the store item into the render item with direct mapping. This property must not be changed after the initialization cycle.
Type:
- boolean
- Inherited From:
- Default Value:
- false
- 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:
-
disabledAttr :string
-
The name of the property of store items which contains the disabled value of Select's options. To disable a given option, the
disabled
property of the corresponding data item must be set to a truthy value. Otherwise, the option is enabled if data item property is absent, or its value is falsy or the string "false".Type:
- string
- Default Value:
- "disabled"
- 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:
-
<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:
-
name :string
-
Name used when submitting form; same as "name" attribute or plain HTML elements.
Type:
- string
- Inherited From:
- Source:
-
query :Object
-
A query filter to apply to the store.
Type:
- Object
- Inherited From:
- Default Value:
- {}
- Source:
-
renderItems :Array.<Object>
-
The render items corresponding to the store items for this widget. This is filled from the store and is not supposed to be modified directly. Initially null.
Type:
- Array.<Object>
- Inherited From:
- Default Value:
- null
- Source:
-
selectedItem :Object
-
In single selection mode, the selected item or in multiple selection mode the last selected item.
Type:
- Object
- Inherited From:
- Default Value:
- null
- Source:
-
selectedItems :Array.<Object>
-
The list of selected items.
Type:
- Array.<Object>
- Inherited From:
- Default Value:
- null
- 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 (by taping or using the control key modifier).
Changing this value impacts the currently selected items to adapt the selection to the new mode. However, regardless of the selection mode, it is always possible to set several selected items using the
selectedItem
orselectedItems
properties. The mode will be enforced only when usingsetSelected
and/orselectFromEvent
APIs.Type:
- string
- Default Value:
- "single"
- Source:
-
size :number
-
The number of rows that should be visible at one time when the widget is presented as a scrollable list box. Corresponds to the
size
attribute of the underlying native HTML<select>
.Type:
- number
- Default Value:
- 0
- Source:
-
source :dstore/Store|decor/ObservableArray|Array
-
The source that contains the items to display.
Type:
- dstore/Store | decor/ObservableArray | Array
- Inherited From:
- Default Value:
- null
- 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:
-
textAttr :string
-
The name of the property of store items which contains the text of Select's options.
Type:
- string
- Default Value:
- "text"
- 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:
-
valueAttr :string
-
The name of the property of store items which contains the value of Select's options.
Type:
- string
- Default Value:
- "value"
- 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:
-
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> 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> dispatchSelectionChange(oldSelectedItem, newSelectedItem, renderer, triggerEvent)
-
Dispatch a selection change event.
Parameters:
Name Type Description oldSelectedItem
Object The previously selected item.
newSelectedItem
Object The new selected item.
renderer
Object The visual renderer of the selected/deselected item.
triggerEvent
Event The event that lead to the selection of the item.
- Inherited From:
- Source:
Fires:
-
<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> fetch(collection)
-
Called to perform the fetch operation on the collection.
Parameters:
Name Type Description collection
dstore/Collection Items to be displayed.
- Inherited From:
- 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:
-
getIdentity(object) → {string}
-
This function must be implemented to return the id of a item.
Parameters:
Name Type Description object
item The item the identity of must be returned.
- Inherited From:
- Source:
Returns:
The identity of the item.
- Type
- string
-
<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> hasSelectionModifier(event) → {boolean}
-
Tests if an event has a selection modifier.
If it has a selection modifier, that means that:
- if selectionMode is "single", the event will be able to deselect a selected item
- if selectionMode is "multiple", the event will trigger the selection state of the item
The default implementation of this method returns true if the event.ctrlKey attribute is true, which means that:
- if selectionMode is "single", the Ctrl (or Command on MacOS) key must be pressed for the
- event to deselect the currently selected item
- if selectionMode is "multiple", the Ctrl (or Command on MacOS) key must be pressed for the event to toggle the selection status of the item.
Parameters:
Name Type Description event
Event The event that led to the selection .
- Inherited From:
- Source:
Returns:
Whether the event has selection modifier.
- Type
- boolean
-
<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> initItems(renderItems) → {Array.<Object>}
-
This method is called once the query has been executed to initialize the renderItems array with the list of initial render items.
This method sets the renderItems property to the render items array passed as parameter. Once done, it fires a 'query-success' event.
Parameters:
Name Type Description renderItems
Array.<Object> The array of initial render items to be set in the renderItems property.
- Inherited From:
- Source:
Fires:
Returns:
the renderItems array.
- Type
- Array.<Object>
-
<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:
-
isSelected(object) → {Object}
-
Returns whether an item is selected or not.
Parameters:
Name Type Description object
item The item to test.
- Inherited From:
- Source:
Returns:
The item to test the selection for.
- Type
- Object
-
<protected> itemAdded(index, renderItem, renderItems)
-
This method is called when an item is added in an observable store. The default implementation actually adds the renderItem to the renderItems array. This can be redefined but must not be called directly.
Parameters:
Name Type Description index
number The index where to add the render item.
renderItem
Object The render item to be added.
renderItems
Array.<Object> The array of render items to add the render item to.
- Inherited From:
- Source:
-
<protected> itemMoved(previousIndex, newIndex, renderItem, renderItems)
-
This method is called when an item is moved in an observable store. The default implementation actually moves the renderItem in the renderItems array. This can be redefined but must not be called directly.
Parameters:
Name Type Description previousIndex
number The previous index of the render item.
newIndex
number The new index of the render item.
renderItem
Object The render item to be moved.
renderItems
Array.<Object> The array of render items to render item to be moved is part of.
- Inherited From:
- Source:
-
<protected> itemRemoved(index, renderItems)
-
This method is called when an item is removed from an observable store. The default implementation actually removes a renderItem from the renderItems array. This can be redefined but must not be called directly.
Parameters:
Name Type Description index
number The index of the render item to remove.
renderItems
Array.<Object> The array of render items to remove the render item from.
- Inherited From:
- Source:
-
<protected> itemToRenderItem(item) → {Object}
-
Returns the widget internal item for a given store item based on the various mapped properties.
Parameters:
Name Type Description item
Object The store item.
- Inherited From:
- Source:
Returns:
- Type
- Object
-
<protected> itemUpdated(index, renderItem, renderItems)
-
This method is called when an item is updated in an observable store. The default implementation actually updates the renderItem in the renderItems array. This can be redefined but must not be called directly.
Parameters:
Name Type Description index
number The index of the render item to update.
renderItem
Object The render item data the render item must be updated with.
renderItems
Array.<Object> The array of render items to render item to be updated is part of.
- Inherited From:
- Source:
-
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> 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> processCollection(collection)
-
Called to process the items returned after querying the store.
Parameters:
Name Type Description collection
dstore/Collection Items to be displayed.
- Inherited From:
- Source:
-
<protected> processConstructorParameters()
-
Called after Object is created to process parameters passed to constructor.
- Inherited From:
- Source:
-
processQueryResult()
-
A function that processes the collection or the array returned by the source query and returns a new collection or a new array (to sort it, etc...). This processing is applied before potentially tracking the source for modifications (if Trackable or Observable). Be careful you can not use the same function for both arrays and collections. Changing this function on the instance will not automatically refresh the class.
- Inherited From:
- Default Value:
- identity function
- Source:
-
<protected> queryStoreAndInitItems(processQueryResult) → {Promise}
-
Queries the store, creates the render items and calls initItems() when ready. If an error occurs a 'query-error' event will be fired.
This method is not supposed to be called by application developer. It will be called automatically when modifying the store related properties or by the subclass if needed.
Parameters:
Name Type Description processQueryResult
A function that processes the collection returned by the store query and returns a new collection (to sort it, etc...)., applied before tracking.
- Inherited From:
- Source:
Returns:
If store to be processed is not null a promise that will be resolved when the loading process will be finished.
- Type
- Promise
-
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:
-
remap()
-
If allowRemap is true, the method allows to perform again the mapping between the data item and the render items. This might be useful is mapping by function is used and the execution context of the mapping function as changed so that the results would need to be updated. It should not be called if allowRemap is false.
- 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:
-
renderItemToItem(renderItem) → {Promise}
-
Creates a store item based from the widget internal item based on the various mapped properties. Works asynchronously.
Parameters:
Name Type Description renderItem
Object The render item.
- Inherited From:
- Source:
Returns:
- Type
- Promise
-
<protected> selectFromEvent(event, item, renderer, dispatch) → {boolean}
-
Applies selection triggered by an user interaction.
Parameters:
Name Type Description event
Event The source event of the user interaction.
item
Object The item that has been selected/deselected.
renderer
Object The visual renderer of the selected/deselected item.
dispatch
boolean Whether an event must be dispatched or not.
- Inherited From:
- Source:
Returns:
True if the selection has changed and false otherwise.
- Type
- boolean
-
<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:
-
setSelected(item, value)
-
Change the selection state of an item.
Parameters:
Name Type Description item
Object The item to change the selection state for.
value
boolean True to select the item, false to deselect it.
- 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> updateRenderers(items)
-
This function must be implemented to update the rendering of the items based on whether they are selected or not. The implementation must check for their new selection state and update accordingly.
Parameters:
Name Type Description items
Array.<Object> The array of items changing their selection state.
- 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"); });
-
query-success
-
Dispatched once the query has been executed and the
renderItems
array has been initialized with the list of initial render items.- Inherited From:
- Source:
Properties:
Name Type Description renderItems
Array.<Object> The array of initial render items.
cancelable
boolean Indicates whether the event is cancelable or not.
bubbles
boolean Indicates whether the given event bubbles up through the DOM or not.
Example
widget.on("query-success", function (evt) { console.log("query done, initial renderItems: " + evt.renderItems); });
-
selection-change
-
Selection change event. Dispatched after the selection has been modified through user interaction.
- Inherited From:
- Source:
Properties:
Name Type Description oldValue
number The previously selected item.
newValue-
number The new selected item.
renderer
Object The visual renderer of the selected/deselected item.
triggerEvent
Event The event that lead to the selection of the item.
Example
widget.on("selection-change", function (evt) { console.log("old value: " + evt.oldValue); console.log("new value: " + evt.newValue); }