Base class for all custom elements.
Use this class rather that delite/Widget for non-visual custom elements. Custom elements can provide custom setters/getters for properties, which are called automatically when the value is set. For an attribute XXX, define methods _setXXXAttr() and/or _getXXXAttr().
- Source:
Extends
Show inheritedMembers
-
<protected> attached :boolean
-
Set to true when
attachedCallback()
has completed, and false whendetachedCallback()
called.Type:
- boolean
- Source:
-
<protected> created :boolean
-
Set to true when
createdCallback()
has completed.Type:
- boolean
- 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 usedcl.superCall()
,dcl.advise()
, etc.- Source:
Fires:
-
<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.- 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:
-
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.
- 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.- Source:
-
discardChanges()
-
Discard change records for all listeners registered via
observe()
.- 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.- 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.
- 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> 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.
Example
var stateful = new (dcl(Stateful, { foo: undefined, bar: undefined, baz: undefined }))({ foo: 3, bar: 5, baz: 7 }); stateful.observe(function (oldValues) { // oldValues is {foo: 3, bar: 5, baz: 7} }); stateful.foo = 4; stateful.bar = 6; stateful.baz = 8; stateful.foo = 6; stateful.bar = 8; stateful.baz = 10;
-
on(type, func, node) → {Object}
-
Call specified function when event occurs.
Note that the function is not run in any particular scope, so if (for example) you want it to run in the element's scope you must do
myCustomElement.on("click", myCustomElement.func.bind(myCustomElement))
.Note that
delite/Widget
overrideson()
so thaton("focus", ...)
and `on("blur", ...) will trigger the listener when focus moves into or out of the widget, rather than just when the widget's root node is focused/blurred. In other words, the listener is called when the widget is conceptually focused or blurred.Parameters:
Name Type Argument Description type
string Name of event (ex: "click").
func
function Callback function.
node
Element <optional>
Element to attach handler to, defaults to
this
.- Source:
Returns:
Handle with
remove()
method to cancel the event.- Type
- Object
-
<protected> own() → {Array.<Object>}
-
Track specified handles and remove/destroy them when this instance is destroyed, unless they were already removed/destroyed manually.
- Inherited From:
- Source:
Returns:
The array of specified handles, so you can do for example:
var handle = this.own(on(...))[0];
- Type
- Array.<Object>
-
<protected> parseAttribute(name, value)
-
Helper for parsing declarative widgets. Interpret a given attribute specified in markup, returning either:
undefined
: ignore{prop: prop, value: value}
: setthis[prop] = value
{event: event, callback: callback}
: callthis.on(event, callback)
Parameters:
Name Type Description name
string Attribute name.
value
string Attribute value.
- 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.
- Source:
-
<protected> processConstructorParameters()
-
Called after Object is created to process parameters passed to constructor.
- Inherited From:
- Source:
Events
-
customelement-attached
-
Dispatched after the CustomElement has been attached. This is useful to be notified when an HTMLElement has been upgraded to a CustomElement and attached to the DOM, in particular on browsers supporting native Custom Element.
- Source:
Example
element.addEventListener("customelement-attached", function (evt) { console.log("custom element: "+evt.target.id+" has been attached"); });