Base class for widgets that need drop down ability.
- Source:
Extends
Show inheritedMembers
-
<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
- 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 aattach-point
assignment. If missing, thenthis.buttonNode
will be used.Type:
- Element
- Source:
-
<protected> attached :boolean
-
Set to true when
attachedCallback()
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. Has no effect when
dropDownPosition = ["center"]
.Type:
- boolean
- 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
- Source:
-
<protected> created :boolean
-
Set to true when
createdCallback()
has completed.Type:
- boolean
- Inherited From:
- 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 - setup a listener for the delite-display-load event that [asynchronously] resolves the event's
loadDeferred
Promise to the dropdown
Type:
- Element
- 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>
- 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
. Has no effect whendropDownPosition = ["center"]
.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> 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
- Source:
-
<protected> started :boolean
-
Set to true when
startup()
has completed.Type:
- boolean
- Inherited From:
- 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> _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:
-
attachedCallback()
-
Called when the element is added to the document, after
createdCallback()
completes. Note though that for programatically created custom elements, the app must manually call this method.This method is automatically chained, so subclasses generally do not need to use
dcl.superCall()
,dcl.advise()
, etc.- Inherited From:
- Source:
Fires:
-
<protected> closeDropDown(focus)
-
Closes the drop down on this widget.
Parameters:
Name Type Description focus
boolean If true, refocus this widget.
- Source:
Fires:
-
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 (
preRender()
,render()
, andpostRender()
), 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}
-
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", {});
-
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:
-
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> initializeInvalidating()
-
Sets up observers, one for computed properties, one for UI rendering. 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:
-
<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/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 [asynchronously] resolve the event's
evt.loadDeferred
Promise property with an Object like{child: dropDown}
With option (2) or (3) the application is responsible for destroying the dropdown.
- 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)
-
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.
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 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.
- 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(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> 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:
-
startup()
-
Called after a widget and its children have been created and added to the page, and all related widgets have finished their creation cycle, up through
postRender()
.Most widgets should add initialization code to
attachedCallback()
rather thanstartup()
. Code instartup()
is only necessary for widgets that can't be initialized until related widgets have been created. For example, hypothetically, ifDisplayContainer#selectedChildId
could not be processed until the specified child DOM node existed, and had been upgraded from a plain DOM node into a widget.startup()
may be removed in the future.Note that
startup()
may be called while the widget is still hidden, for example if the widget is inside a hidden dialog or an unselected tab of a TabContainer, so the widget shouldn't try to do layout in startup().- 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:
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.
- 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.
- 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.
- 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.
- 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); });