Module: deliteful/list/List

deliteful/list/List

require(["deliteful/list/List"], function (List) {
  new List();
});

A widget that renders a scrollable list of items.

The List widget renders a scrollable list of items that are retrieved from a Store. Its custom element tag is d-list.

See the user documentation for more details.

Source:

Extends

Show inherited

Members

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:

<protected> attached :boolean

Set to true when attachedCallback() has completed, and false when detachedCallback() called.

Type:
  • boolean
Inherited From:
Source:

baseClass :string

The base class that defines the style of the list. Available values are:

  • "d-list" (default): render a list with no rounded corners and no left and right margins;
  • "d-round-rect-list": render a list with rounded corners and left and right margins.
Type:
  • string
Default Value:
  • "d-list"
Source:

categoryAttr :string

Name of the list item attribute that define the category of a list item. If falsy and categoryFunc is also falsy, the list is not categorized.

Type:
  • string
Default Value:
  • ""
Source:

categoryFunc

A function (or the name of a function) that extracts the category of a list item from the following input parameters:

  • item: the list item from the store
  • store: the store If falsy and categoryAttr is also falsy, the list is not categorized. see delite/StoreMap
Default Value:
  • null
Source:

categoryRenderer :module:deliteful/list/CategoryRenderer

The widget class to use to render category headers when the list items are categorized. It MUST extend deliteful/list/CategoryRenderer.

Type:
Default Value:
  • module:deliteful/list/CategoryRenderer
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:

<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> focusDescendants :boolean

When true, focus the descendant widgets as the user navigates to them via arrow keys or keyboard letter search. When false, rather than focusing the widgets, it merely sets navigatedDescendant, and sets the d-active-descendant class on the descendant widget the user has navigated to.

False mode is intended for widgets like ComboBox where the focus is somewhere outside this widget (typically on an <input>) and keystrokes are merely being forwarded to the KeyNav widget.

When set to false:

  • All navigable descendants must specify an id.
  • Navigable descendants shouldn't have any tabIndex (as opposed to having tabIndex=-1).
  • The focused element should specify aria-owns to point to this KeyNav Element.
  • The focused Element must be kept synced so that aria-activedescendant points to the currently navigated descendant. Do this responding to the keynav-child-navigated event emitted by this widget, or by calling observe() and monitoring changed to navigatedDescendant.
  • The focused Element must forward keystrokes by calling emit("keydown", ...) and/or emit("keypress", ...) on this widget.
  • You must somehow set the initial navigated descendant, typically by calling navigateToFirst() either when the the dropdown is opened, or on the first call to downKeyHandler().
  • You must have some CSS styling so that the currently navigated node is apparent.

See http://www.w3.org/WAI/GL/wiki/Using_aria-activedescendant_to_allow_changes_in_focus_within_widgets_to_be_communicated_to_Assistive_Technology#Example_1:_Combobox for details.

Type:
  • boolean
Inherited From:
Default Value:
  • true
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:

iconclassAttr :string

Default mapping between the attribute of the item retrieved from the store and the icon attribute expected by the default renderer

Type:
  • string
Default Value:
  • "iconclass"
Source:

itemRenderer :module:deliteful/list/ItemRenderer

The widget class to use to render list items. It MUST extend deliteful/list/ItemRenderer.

Type:
Default Value:
  • module:deliteful/list/ItemRenderer
Source:

labelAttr :string

Default mapping between the attribute of the item retrieved from the store and the label attribute expected by the default renderer

Type:
  • string
Default Value:
  • "label"
Source:

loadingMessage :string

Optional message to display, with a progress indicator, when the list is loading its content.

Type:
  • string
Default Value:
  • ""
Source:

The currently navigated descendant, or null if there isn't one.

Type:
  • Element
Inherited From:
Source:

query :Object

Query to pass to the store to retrieve the items to render in the list.

Type:
  • Object
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:

righticonclassAttr :string

Default mapping between the attribute of the item retrieved from the store and the righticon attribute expected by the default renderer

Type:
  • string
Default Value:
  • "righticonclass"
Source:

righttextAttr :string

Default mapping between the attribute of the item retrieved from the store and the righttext attribute expected by the default renderer

Type:
  • string
Default Value:
  • "righttext"
Source:

scrollableNode :Element

Designates the descendant node of this widget which is made scrollable.

If not set otherwise before the render() method of the mixin is executed, it is set by default to this widget itself (this).

Note that this property can be set only at construction time, at latest in the render() method of the host widget into which this class is mixed. It should not be changed afterwards. Typically, this property can be set by a host widget which needs scrolling capabilities on one its descendant nodes.

Type:
  • Element
Inherited From:
Default Value:
  • null
Source:

scrollDirection :string

Defines the scroll direction: "vertical" for a scrollable List, "none" for a non scrollable List.

Type:
  • string
Default Value:
  • "vertical"
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 selection mode for list items (see delite/Selection).

Type:
  • string
Default Value:
  • "none"
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:

store :module:dstore/Store

Dojo object store that contains the items to render in the list. If no value is provided for this attribute, the List will initialize it with an internal store implementation. Note that this internal store implementation ignores any query options and returns all the items from the store, in the order they were added to the store.

Type:
  • module:dstore/Store
Default Value:
  • null
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:

<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:

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 use dcl.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 and cancelable 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> endKeyHandler(evt, navigatedDescendant)

Called on end key.

Parameters:
Name Type Description
evt Event
navigatedDescendant Element
Inherited From:
Source:

<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:

focus()

/** Default focus() implementation: navigate to the first navigable descendant. Note that if focusDescendants is false, this will merely set the d-active-descendant class rather than actually focusing the descendant.

Inherited From:
Source:

<protected> getBottomDistance(node)

Returns the distance between the bottom of a node and the bottom of the scrolling container.

Parameters:
Name Type Description
node Node

the node
Source:

getCurrentScroll() → {Object}

Returns the current amount of scroll, as an object with x and y properties for the horizontal and vertical scroll amount. This is a convenience method and it is not supposed to be overridden.

Inherited From:
Source:
Returns:
Type
Object

getEnclosingRenderer(node) → {module:deliteful/list/Renderer}

Returns the renderer enclosing a dom node, or null if there is none.

Parameters:
Name Type Description
node Element

The dom node.
Source:
Returns:
Type
module:deliteful/list/Renderer

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> getIdentity(item) → {Object}

Return the identity of an item.

Parameters:
Name Type Description
item Object

The item
Inherited From:
Source:
Returns:
Type
Object

<protected> getInheritedDir() → {string}

Get the direction setting for the page itself.

Inherited From:
Source:
Returns:

"ltr" or "rtl"

Type
string

getItemRendererByIndex(index) → {module:deliteful/list/ItemRenderer}

Returns the item renderer at a specific index in the List, or null if there is no renderer at this index.

Parameters:
Name Type Description
index number

The item renderer at the index (first item renderer index is 0).
Source:
Returns:
Type
module:deliteful/list/ItemRenderer

getItemRendererIndex(renderer) → {number}

Returns the index of an item renderer in the List, or -1 if the item renderer is not found in the list.

Parameters:
Name Type Description
renderer Object

The item renderer.
Source:
Returns:
Type
number

getItemRenderers() → {NodeList}

Returns the item renderers displayed by the list.

Source:
Returns:
Type
NodeList

<protected> getNext(child, dir) → {Element}

Returns the next or previous navigable descendant, relative to "child". If "child" is this, then it returns the first focusable descendant (when dir === 1) or last focusable descendant (when dir === -1).

Parameters:
Name Type Description
child Element

The current child Element.
dir number

1 = after, -1 = before
Inherited From:
Source:
Returns:
Type
Element

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>

getRendererByItemId(id) → {module:deliteful/list/Renderer}

Returns the renderer currently displaying an item with a specific id, or null if there is no renderer displaying an item with this id.

Parameters:
Name Type Description
id Object

The id of the item displayed by the renderer.
Source:
Returns:
Type
module:deliteful/list/Renderer

<protected> getTopDistance(node)

Returns the distance between the top of a node and the top of the scrolling container.

Parameters:
Name Type Description
node Node

the node
Source:

<protected> handleSelection(event) → {boolean}

Event handler that performs items (de)selection.

Parameters:
Name Type Description
event Event

The event the handler was called for.
Source:
Returns:

true if the event has been handled, that is if the event target has an enclosing item renderer. Returns false otherwise.

Type
boolean

<protected> hasSelectionModifier(event) → {boolean}

Always returns true so that no keyboard modifier is needed when selecting / deselecting items.

Parameters:
Name Type Description
event Event
Source:
Returns:
Type
boolean

<protected> homeKeyHandler(evt, navigatedDescendant)

Called on home key.

Parameters:
Name Type Description
evt Event
navigatedDescendant Element
Inherited From:
Source:

<protected> initializeInvalidating()

Make initial calls to computeProperties(), initializeRendering(), and refreshRendering(), 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 the constructor() 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(items)

Populate the list using the items retrieved from the store.

Parameters:
Name Type Description
items Array.<Object>

items retrieved from the store.
Source:
Fires:

<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:

isBottomScroll() → {boolean}

Returns true if container's scroll has reached the maximum limit at the bottom of the contents. Returns false otherwise.

Inherited From:
Source:
Returns:
Type
boolean
Example
var scrollableNode = scrollableWidget.scrollableNode;
scrollableNode.on("scroll", function () {
  if (scrollableWidget.isBottomScroll()) {
    console.log("Scroll reached the maximum limit at the bottom");
  }
}

isCategoryRenderer(renderer) → {boolean}

Returns whether a renderer is a category renderer or not>.

Parameters:
Name Type Description
renderer module:deliteful/list/Renderer

The renderer to test.
Source:
Returns:
Type
boolean

isLeftScroll() → {boolean}

Returns true if container's scroll has reached the maximum limit at the left of the contents. Returns false otherwise.

Inherited From:
Source:
Returns:
Type
boolean
Example
var scrollableNode = scrollableWidget.scrollableNode;
scrollableNode.on("scroll", function () {
  if (scrollableWidget.isLeftScroll()) {
    console.log("Scroll reached the maximum limit at the left");
  }
}

isRightScroll() → {boolean}

Returns true if container's scroll has reached the maximum limit at the right of the contents. Returns false otherwise.

Inherited From:
Source:
Returns:
Type
boolean
Example
var scrollableNode = scrollableWidget.scrollableNode;
scrollableNode.on("scroll", function () {
  if (scrollableWidget.isRightScroll()) {
    console.log("Scroll reached the maximum limit at the right");
  }
}

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

isTopScroll() → {boolean}

Returns true if container's scroll has reached the maximum limit at the top of the contents. Returns false otherwise.

Inherited From:
Source:
Returns:
Type
boolean
Example
var scrollableNode = scrollableWidget.scrollableNode;
scrollableNode.on("scroll", function () {
  if (scrollableWidget.isTopScroll()) {
    console.log("Scroll reached the maximum limit at the top");
  }
}

<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, keepSelection)

Function to call when an item is removed from the store, to update the content of the list widget accordingly.

Parameters:
Name Type Description
index number

The index of the render item to remove.
renderItems Array.<Object>

Ignored by this implementation.
keepSelection boolean

Set to true if the item should not be removed from the list of selected items.
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)

Function to call when an item is updated in the store, to update the content of the list widget accordingly.

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>

Ignored by this implementation.
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
});

Navigate to the specified descendant. Note that if focusDescendants is false, this will merely set the d-active-descendant class rather than actually focusing the descendant.

Parameters:
Name Type Argument Description
child Element

Reference to the descendant.
last boolean <optional>

If true and if descendant has multiple focusable nodes, focus the last one instead of the first one. This assumes that the child's focus() method takes a boolean parameter where true means to focus the last child.
triggerEvent Event <optional>

The event that lead to the navigation, or undefined if the navigation is triggered programmatically.
Inherited From:
Source:

Navigate to the first navigable descendant. Note that if focusDescendants is false, this will merely set the d-active-descendant class rather than actually focusing the descendant.

Parameters:
Name Type Argument Description
triggerEvent Event <optional>

The event that lead to the navigation, or undefined if the navigation is triggered programmatically.
Inherited From:
Source:

Navigate to the last navigable descendant. Note that if focusDescendants is false, this will merely set the d-active-descendant class rather than actually focusing the descendant.

Parameters:
Name Type Argument Description
triggerEvent Event <optional>

The event that lead to the navigation, or undefined if the navigation is triggered programmatically.
Inherited From:
Source:

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.

Type
module:decor/Stateful.PropertyListObserver
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 overrides on() so that on("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}: set this[prop] = value
  • {event: event, callback: callback}: call this.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)

<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

scrollBy(by, duration)

Scrolls by the given amount.

Parameters:
Name Type Description
by Object

The scroll amount. An object with x and/or y properties, for example {x: 0, y: -5} or {y: -29}.
duration number

Duration of scrolling animation in milliseconds. If 0 or unspecified, scrolls without animation.
Inherited From:
Source:

scrollTo(to, duration)

Scrolls to the given position.

Parameters:
Name Type Argument Description
to Object

The scroll destination position. An object with w and/or y properties, for example {x: 0, y: -5} or {y: -29}.
duration number <optional>

Duration of scrolling animation in milliseconds. If 0 or unspecified, scrolls without animation.
Inherited From:
Source:

<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)

Updates renderers when the selection has changed.

Parameters:
Name Type Description
items Array.<Object>

The items which renderers must be updated.
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");
});

keynav-child-navigated

Dispatched after the user has selected a different descendant, by clicking, arrow keys, or keyboard search.

Properties:
Name Type Description
oldValue number

The previously selected item.
newValue number

The new selected item.
Inherited From:
Source:
Example
widget.on("keynav-child-navigated", function (evt) {
	console.log("old value: " + evt.oldValue);
	console.log("new value: " + evt.newValue);
}

query-success

Dispatched once the query has been executed and the renderItems array has been initialized with the list of initial render items.

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.
Inherited From:
Source:
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.

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.
Inherited From:
Source:
Example
widget.on("selection-change", function (evt) {
	console.log("old value: " + evt.oldValue);
	console.log("new value: " + evt.newValue);
}