Mixin: module:delite/FormValueWidget

module:delite/FormValueWidget

Base class intended for form widgets that have end user changeable values, i.e. widgets where the user can interactively change the value property by using the mouse, keyboard, touch, etc.

FormValueWidget extends FormWidget to:

  1. Provide helper functions to emit change and input events when the widget's value is interactively changed by the end user. Subclasses of FormValueWidget should call handleOnChange() and handleOnInput() to fire change and input events as the value changes. See https://html.spec.whatwg.org/multipage/forms.html#common-input-element-events for details.
  2. Provide handling for the readOnly property.
Source:

Extends

Show inherited

Members

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 when detachedCallback() called.

Type:
  • boolean
Inherited From:
Source:

<protected> baseClass :string

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

Type:
  • string
Inherited From:
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 and focusNode's disabled property to match the widget's disabled property.

Type:
  • boolean
Inherited From:
Default Value:
  • false
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 set tabStops rather than setting focusNode.

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:

readOnly :boolean

If true, this widget won't respond to user input. Similar to disabled except readOnly form values are submitted. FormValueWidget automatically updates focusNode's readOnly property to match the widget's readOnly property.

Type:
  • boolean
Default Value:
  • false
Source:

tabIndex :number

The order in which fields are traversed when user presses the tab key.

Type:
  • number
Inherited From:
Default Value:
  • 0
Source:

tabStops :string

Comma separated list of tabbable nodes, i.e. comma separated list of widget properties that reference the widget DOM nodes that receive focus during tab operations.

Aria roles are applied to these nodes rather than the widget root node.

Note that FormWidget requires that all of the tabbable nodes be sub-nodes of the widget, rather than the root node. This is because of its processing of tabIndex.

Type:
  • string
Inherited From:
Default Value:
  • "focusNode"
Source:

<protected> template :function

Value returned by delite/handlebars! or compatible template engine. Specifies how to build the widget DOM initially and also how to update the DOM when widget properties change.

Type:
  • function
Inherited From:
Source:

value :string

Corresponds to the native HTML <input> element's attribute.

For widgets that directly extend FormWidget (ex: checkboxes), the value is set programatically when the widget is created, and the end user merely changes the widget's state, i.e. the checked property.

For widgets that extend FormValueWidget, the end user can interactively change the value property via mouse, keyboard, touch, etc.

Type:
  • string
Inherited From:
Source:

<protected> valueNode :HTMLElement

A form element, typically an <input>, embedded within the widget, and likely hidden. It is used to represent the widget's state/value during form submission.

Subclasses of FormWidget like checkboxes and radios should update valueNode's checked 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 use dcl.superCall(), dcl.advise(), etc.

Inherited From:
Source:
Fires:

<protected> compare(val1, val2) → {number}

Compare two values (of this widget).

Parameters:
Name Type Description
val1 *
val2 *
Source:
Returns:
Type
number

computeProperties(oldValues, isAfterCreation)

Callback function to calculate computed properties upon property changes.

Parameters:
Name Type Description
oldValues Object

The hash table of old property values, keyed by property names.

isAfterCreation boolean

True if this call is right after instantiation.

Inherited From:
Source:

<protected> createdCallback()

Called when the custom element is created, or when register.parse() parses a custom tag.

This method is automatically chained, so subclasses generally do not need to use dcl.superCall(), dcl.advise(), etc.

Inherited From:
Source:

<protected> defer(fcn, delay) → {Object}

Wrapper to setTimeout to avoid deferred functions executing after the originating widget has been destroyed.

Parameters:
Name Type Description
fcn function

Function to be executed after specified delay (or 0ms if no delay specified).

delay number

Delay in ms, defaults to 0.

Inherited From:
Source:
Returns:

Handle with a remove method that deschedules the callback from being called.

Type
Object

deliver()

Synchronously deliver change records to all listeners registered via observe().

Inherited From:
Source:

deliverComputing()

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

Inherited From:
Source:

destroy()

Release resources used by this custom element and its descendants. After calling this method, the element can no longer be used, and should be removed from the document.

Inherited From:
Source:

detachedCallback()

Called when the element is removed the document. This method is automatically chained, so subclasses generally do not need to use dcl.superCall(), dcl.advise(), etc.

Inherited From:
Source:

discardChanges()

Discard change records for all listeners registered via observe().

Inherited From:
Source:

discardComputing()

Discard change records for computed properties.

Inherited From:
Source:

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

Emits a synthetic event of specified type, based on eventObj.

Parameters:
Name Type Argument Description
type string

Name of event.

eventObj Object <optional>

Properties to mix in to emitted event. Can also contain bubbles 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", {});

findCustomElements(root)

Search subtree under root returning custom elements found.

Parameters:
Name Type Argument Description
root Element <optional>

Node to search under.

Inherited From:
Source:

<protected> firstFocusNode()

Helper method to get the first focusable node, usually this.focusNode.

Inherited From:
Source:

focus()

Put focus on this widget.

Inherited From:
Source:

<protected> forEachFocusNode(callback)

Helper method to execute callback for each focusable node in the widget. Typically the callback is just called once, for this.focusNode.

Parameters:
Name Type Description
callback function

The callback function.

Inherited From:
Source:

getEnclosingWidget(node)

Returns the widget whose DOM tree contains the specified DOMNode, or null if the node is not contained within the DOM tree of any widget

Parameters:
Name Type Description
node Element
Inherited From:
Source:

<protected> getInheritedDir() → {string}

Get the direction setting for the page itself.

Inherited From:
Source:
Returns:

"ltr" or "rtl"

Type
string

getParent()

Returns the parent widget of this widget, or null if there is no parent widget.

Inherited From:
Source:

<protected> getProps() → {Object}

Returns a hash of properties that should be observed.

Inherited From:
Source:
Returns:

Hash of properties.

Type
Object

<protected> getPropsToObserve() → {Array.<string>}

Get list of properties that Stateful#observe() should observe.

Inherited From:
Source:
Returns:

list of properties

Type
Array.<string>

<protected> handleOnChange(newValue)

Sets value and fires a "change" event if the value changed since the last call.

This method should be called when the value is committed, if that makes sense for the control, or else when the control loses focus. For example, it should be called when the user releases a slider's handle after dragging it, or when the user blurs a textbox. See https://html.spec.whatwg.org/multipage/forms.html#common-input-element-events for details.

Parameters:
Name Type Description
newValue *

The new value.

Source:

<protected> handleOnInput(newValue)

Sets value and fires an "input" event if the value changed since the last call.

This method should be called whenever the value is changed interactively by the end user. For example, it should be called repeatedly as the user drags the handle of a slider, or on every keystroke for a textbox. See https://html.spec.whatwg.org/multipage/forms.html#common-input-element-events for details.

Parameters:
Name Type Description
newValue *

The new value.

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

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.

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

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

Inherited From:
Source:

refreshRendering(oldValues, isAfterInitialRendering)

Callback function to render UI upon property changes.

Parameters:
Name Type Description
oldValues Object

The hash table of old property values, keyed by property names.

isAfterInitialRendering boolean

True if this call is right after initializeRendering().

Inherited From:
Source:

<protected> render()

Construct the UI for this widget, filling in subnodes and/or text inside of this. Most widgets will leverage delite/handlebars! to set template, rather than defining this method.

Inherited From:
Source:

<protected> setClassComponent(component, value, node)

Helper method to set a class (or classes) on a given node, removing the class (or classes) set by the previous call to setClassComponent() for the specified component and node. Used mainly by template.js to set classes without overwriting classes set by the user or other code (ex: CssState).

Parameters:
Name Type Argument Description
component string

Specifies the category.

value string

Class (or classes) to set.

node HTMLElement <optional>

The node to set the property on; defaults to widget root node.

Inherited From:
Source:

<protected> setOrRemoveAttribute(node, name, value)

Helper method to set/remove an attribute based on the given value:

  • If value is undefined, the attribute is removed. Useful for attributes like aria-valuenow.
  • If value is boolean, the attribute is set to "true" or "false". Useful for attributes like aria-selected.
  • If value is a number, it's converted to a string.
Parameters:
Name Type Description
node Element

The node to set the property on.

name string

Name of the property.

value string

Value of the property.

Inherited From:
Source:

shouldInitializeRendering(oldValues, isAfterCreation) → {boolean}

Function to return if rendering should be initialized. (Instead of making partial changes for post-initialization)

Parameters:
Name Type Description
oldValues Object

The hash table of old property values, keyed by property names.

isAfterCreation boolean

True if this call is right after instantiation.

Inherited From:
Source:
Returns:

True if rendering should be initialized.

Type
boolean

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");
});