Mixin: module:delite/HasDropDown

module:delite/HasDropDown

Base class for widgets that need drop down ability.

Source:

Extends

Show inherited

Members

<protected> _aroundNode :Element

The node to display the popup around. Can be set in a template via a attach-point assignment. If missing, then this.domNode will be used.

Type:
  • Element
Source:

<protected> _arrowWrapperNode :Element

Will set CSS class d-up-arrow-button, d-down-arrow-button, d-right-arrow-button etc. on this node depending on where the drop down is set to be positioned. Can be set in a template via a attach-point assignment. If missing, then this._buttonNode will be used.

Type:
  • Element
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 either this.focusNode or this.domNode (if focusNode is also missing) will be used.

Type:
  • Element
Source:

<protected> _popupStateNode :Element

The node to set the aria-expanded class on. Can be set in a template via a attach-point assignment. If missing, then this.focusNode or this._buttonNode (if focusNode is missing) will be used.

Type:
  • Element
Source:

<protected> _started :boolean

Set to true when startup() has completed.

Type:
  • boolean
Inherited From:
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.

Type:
  • boolean
Default Value:
  • true
Source:

<protected> baseClass :string

Root CSS class of the widget (ex: d-text-box)

Type:
  • string
Inherited From:
Source:

The widget to display as a popup. Applications/subwidgets should either define this property or override loadDropDown() to return a dropdown widget or Promise for one.

Type:
  • Element
Source:

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

The positions are tried, in order, until a position is found where the drop down fits within the viewport.

Type:
  • Array.<string>
Default Value:
  • ["below", "above"]
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:

forceWidth :boolean

If true, make the drop down exactly as wide as this widget. Overrides autoWidth.

Type:
  • boolean
Default Value:
  • false
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
Default Value:
  • -1
Source:

<readonly> opened :boolean

Whether or not the drop down is open.

Type:
  • boolean
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 get 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> _onBlur()

This is where widgets do processing for when they stop being active, such as changing CSS classes. See onBlur() for more details.

Inherited From:
Source:

<protected> _onFocus()

This is where widgets do processing for when they are active, such as changing CSS classes. See onFocus() for more details.

Inherited From:
Source:

<protected> _parseAttr(name, value)

Helper for _mapAttributes(). 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> _parseFunctionAttr(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> _set(name, value)

Internal helper for directly setting a property value without calling the custom setter.

Directly change 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> attachedCallback()

Called when the widget is first inserted into the document. If widget is created programatically then app must call startup() to trigger this method.

Inherited From:
Source:

<protected> buildRendering()

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> closeDropDown(focus)

Closes the drop down on this widget.

Parameters:
Name Type Description
focus boolean

If true, refocus this widget.
Source:

computeProperties(newValues, oldValues)

Callback function to calculate computed properties upon property changes.

Parameters:
Name Type Description
newValues Object

The hash table of new property values, keyed by property names.
oldValues Object

The hash table of old property values, keyed by property names.
Inherited From:
Source:

<protected> createdCallback()

Kick off the life-cycle of a widget.

Calls a number of widget methods (preCreate(), buildRendering(), and postCreate()), some of which of you'll want to override.

Of course, adventurous developers could override createdCallback entirely, but this should only be done as a last resort.

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 for computed properties and then UI rendering so that refreshingRendering() is called if there are pending change records.

Inherited From:
Source:

deliverComputing()

Synchronously deliver change records for computed properties so that refreshingComputing() is called if there are pending change records.

Inherited From:
Source:

destroy()

Destroy this widget and its descendants.

Inherited From:
Source:

discardChanges()

Discard change records.

Inherited From:
Source:

discardComputing()

Discard change records for computed properties.

Inherited From:
Source:

<protected> emit(type, eventObj) → {boolean}

Signal that a synthetic event occurred.

Emits an event of specified type, based on eventObj. Also calls onType() method, if present, and returns value from that method. Modifies eventObj by adding missing parameters (bubbles, cancelable, widget).

Parameters:
Name Type Argument Description
type string

Name of event.
eventObj Object <optional>

Properties to mix in to emitted event.
Inherited From:
Source:
Returns:

True if the event was not canceled, false if it was canceled.

Type
boolean
Example
myWidget.emit("query-success", {});

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:

focusDropDownOnOpen(keyboard)

Helper function to focus the dropdown when it finishes loading and opening. Exception: doesn't focus the dropdown when dropDown.focusOnOpen === false a menu, unless it was opened via the keyboard. dropDown.focusOnOpen is meant to be set for menus.

Parameters:
Name Type Description
keyboard boolean

True if the user opened the dropdown via the keyboard
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:

getParent()

Returns the parent widget of this widget.

Inherited From:
Source:

<protected> isLeftToRight() → {boolean}

Return this widget's explicit or implicit orientation (true for LTR, false for RTL).

Inherited From:
Source:
Returns:
Type
boolean

<protected> loadDropDown() → {Element|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. Returns a Promise for the dropdown, or if loaded synchronously, the dropdown itself.

Subclasses should override this method to create custom drop downs on the fly. However, they are then responsible for destroying the dropdown when this widget is destroyed.

Source:
Returns:

Element or Promise for the dropdown

Type
Element | Promise

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)

Notify current value to observers. Handy to manually schedule invocation of observer callbacks when there is no change in value.

Parameters:
Name Type Description
name string

The property name.
Inherited From:
Source:

observe(callback) → {module:decor/Stateful.PropertyListObserver}

Observe 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 is 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 widget's scope you must do myWidget.on("click", myWidget.func.bind(myWidget)).

Parameters:
Name Type Argument Description
type string | function

Name of event (ex: "click") or extension event like touch.press.
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

onBlur()

Called when the widget stops being "active" because focus moved to something outside of it, or the user clicked somewhere outside of it, or the widget was hidden.

Inherited From:
Source:

onFocus(evt)

Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.

Parameters:
Name Type Description
evt Event

A focus event.
Inherited From:
Source:

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

Source:
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> 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> postCreate()

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.

Inherited From:
Source:

<protected> preCreate()

Processing before buildRendering().

Inherited From:
Source:

<protected> processConstructorParameters()

Called after Object is created to process parameters passed to constructor.

Inherited From:
Source:

refreshRendering(newValues, oldValues)

Callback function to render UI upon property changes.

Parameters:
Name Type Description
newValues Object

The hash table of new property values, keyed by property names.
oldValues Object

The hash table of old property values, keyed by property names.
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:

startup()

Processing after the DOM fragment is added to the document.

Called after a widget and its children have been created and added to the page, and all related widgets have finished their create() cycle, up through postCreate().

Note that startup() may be called while the widget is still hidden, for example if the widget is inside a hidden deliteful/Dialog or an unselected tab of a deliteful/TabContainer. For widgets that need to do layout, it's best to put that layout code inside resize(), and then extend delite/LayoutWidget so that resize() is called when the widget is visible.

Inherited From:
Source:

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

Source: