require(["deliteful/SidePane"], function (SidePane) {
new SidePane();
});
A widget displayed on the side of the screen.
It can be displayed on top of the page (mode=overlay) or can push the content of the page (mode=push or mode=reveal). SidePane is a widget hidden by default. This widget must be a sibling of html's body element. If mode is set to "push" or "reveal", the width of the SidePane can't be changed in the markup (15em by default). However it can be changed in SidePane.less (@PANE_WIDTH variable). In "push" and "reveal" mode, the pushed element is the first sibling of the SidePane which has of type element (nodeType == 1) and not a SidePane.
- Source:
Example
<body>
<d-side-pane>
SidePane content
</d-side-pane>
<div>
Main application
</div>
</body>
Extends
Show inheritedMembers
-
animate :boolean
-
Enable/Disable animations.
Type:
- boolean
- Default Value:
- true
- Source:
-
<protected> attached :boolean
-
Set to true when
attachedCallback()
has completed, and false whendetachedCallback()
called.Type:
- boolean
- Inherited From:
- Source:
-
baseClass :string
-
The name of the CSS class of this widget.
Type:
- string
- Default Value:
- "d-side-pane"
- Source:
-
<protected> containerNode :Element
-
Designates where children of the source DOM node will be placed, and also the target for nodes inserted via
.appendChild()
,.insertBefore()
, etc. "Children" in this case refers to both DOM nodes and widgets.Type:
- Element
- Inherited From:
- Default Value:
- Widget root node itself.
- 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> 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:
-
mode :string
-
Can be "overlay", "reveal" or "push". In overlay mode, the pane is shown on top of the page. In reveal and push modes, The page is moved to make the pane visible. The difference between these two modes is the animated transition: in reveal mode, the pane does not move, it is already under the page. In push mode, the pane slide with the page.
Type:
- string
- Default Value:
- "push"
- Source:
-
position :string
-
Can be "start" or "end". If set to "start", the panel is displayed on the left side in LTR mode.
Type:
- string
- Default Value:
- "push"
- Source:
-
swipeClosing :boolean
-
Enables the swipe closing of the pane.
Type:
- boolean
- Default Value:
- true
- 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:
-
addChild(node, insertIndex)
-
Inserts the specified Element at the specified index. For example,
.addChild(node, 3)
sets this widget's fourth child to node.Parameters:
Name Type Argument Description node
Element Element to add as a child.
insertIndex
number <optional>
Position the child as at the specified position relative to other children.
- 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.- Inherited From:
- Source:
Fires:
-
changeDisplay(widget, params) → {Promise}
-
This method must perform the display and possible transition effect. It is meant to be specialized by subclasses.
Parameters:
Name Type Argument Description widget
Element | string Element or Element id that points to the child this container must show or hide.
params
Object <optional>
Optional params that might be taken into account when displaying the child. This can be the type of visual transitions involved. This might vary from one DisplayContainer to another. By default on the "hide" param is supporting meaning that the transition should hide the widget not display it.
- Inherited From:
- Source:
Returns:
Optionally a promise that will be resolved when the display & transition effect will have been performed.
- Type
- Promise
-
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
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:
-
getChildren() → {Array.<Element>}
-
Returns all direct children of this widget, i.e. all widgets or DOM nodes underneath
this.containerNode
. Note that it does not return all descendants, but rather just direct children.The result intentionally excludes element outside off
this.containerNode
. So, it is different than accessing thechildren
orchildNode
properties.- Inherited From:
- Source:
Returns:
- Type
- Array.<Element>
-
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:
-
getIndexOfChild(child) → {number}
-
Returns the index of the child in this container or -1 if not found.
Parameters:
Name Type Description child
Element - Inherited From:
- Source:
Returns:
- Type
- number
-
<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>
-
hasChildren() → {boolean}
-
Returns true if widget has child nodes, i.e. if
this.containerNode
contains widgets.- Inherited From:
- Source:
Returns:
- Type
- boolean
-
hide(dest, params) → {Promise}
-
This method must be called to hide a particular destination child on this container.
Parameters:
Name Type Argument Description dest
Element | string Element or Element id that points to the child this container must hide.
params
Object <optional>
Optional params that might be taken into account when hiding the child. This can be the type of visual transitions involved. This might vary from one DisplayContainer to another.
- Inherited From:
- Source:
Fires:
- module:delite/DisplayContainer#event:delite-display-load
- module:delite/DisplayContainer#event:delite-before-hide
- module:delite/DisplayContainer#event:delite-after-hide
Returns:
A promise that will be resolved when the display & transition effect will have been performed.
- Type
- Promise
-
<protected> initializeInvalidating()
-
Make initial calls to
computeProperties()
,initializeRendering()
, andrefreshRendering()
, 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 theconstructor()
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:
-
loadChild(dest, params) → {Promise}
-
This method must be called to load a particular child on this container. A
delite-display-load
event is fired giving the chance to a controller to load/create the child. This method can be redefined to actually load a child of the container. If a controller is not present, it just looks up elements by id.Parameters:
Name Type Argument Description dest
Element | string Element or Element id that points to the child this container must load.
params
Object <optional>
Optional params that might be taken into account when removing the child.
- Inherited From:
- Source:
Fires:
Returns:
A promise that will be resolved when the child will have been loaded with an object of the following form:
{ child: childElement }
or with an optional index{ child: childElement, index: index }
. Other properties might be added to the object if needed.- Type
- 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)
-
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
.- Inherited From:
- Source:
Returns:
Handle with
remove()
method to cancel the event.- Type
- Object
-
onAddChild(node)
-
Callback whenever a child element is added to this widget via
appendChild()
,insertBefore()
, or a method likeaddChild()
that internally callsappendChild()
and/orinsertBefore()
.Parameters:
Name Type Description node
Element - Inherited From:
- Source:
-
<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(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:
-
removeChild(node)
-
Detaches the specified node instance from this widget but does not destroy it. You can also pass in an integer indicating the index within the container to remove (ie, removeChild(5) removes the sixth node).
Parameters:
Name Type Description node
Element | number - 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
-
show(dest, params) → {Promise}
-
This method must be called to display a particular destination child on this container.
Parameters:
Name Type Argument Description dest
Element | string Element or Element id that points to the child this container must display.
params
Object <optional>
Optional params that might be taken into account when displaying the child. This can be the type of visual transitions involved. This might vary from one DisplayContainer to another.
- Inherited From:
- Source:
Fires:
- module:delite/DisplayContainer#event:delite-before-show
- module:delite/DisplayContainer#event:delite-after-show
- module:delite/DisplayContainer#event:delite-display-load
Returns:
A promise that will be resolved when the display & transition effect will have been performed.
- Type
- Promise
-
toggle() → {Promise}
-
This method is called to toggle the visibility of the SidePane.
- Source:
Returns:
A promise that will be resolved when the display & transition effect will have been performed.
- Type
- Promise
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-add-child
-
Dispatched after an Element has been added as child of this widget.
- Inherited From:
- Source:
Example
element.addEventListener("delite-add-child", function (evt) { console.log("container: " + evt.target.id + " has new child " + evt.child.id); });
-
delite-after-hide
-
Dispatched after child is hidden.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to child element
Example
document.addEventListener("delite-after-hide", function (evt) { console.log("just hid child", evt.child); });
-
delite-after-show
-
Dispatched after child is shown.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to child element
Example
document.addEventListener("delite-after-show", function (evt) { console.log("just displayed child", evt.child); });
-
delite-before-hide
-
Dispatched before child is hidden.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to child element
Example
document.addEventListener("delite-before-hide", function (evt) { console.log("about to hide child", evt.child); });
-
delite-before-show
-
Dispatched before child is shown.
- Inherited From:
- Source:
Properties:
Name Type Description child
Element reference to child element
Example
document.addEventListener("delite-before-show", function (evt) { console.log("about to show child", evt.child); });
-
delite-display-load
-
Dispatched to let an application level listener create/load the child node.
- Inherited From:
- Source:
Properties:
Name Type Description setChild
function method to set child element, or Promise for child element
Example
document.addEventListener("delite-display-load", function (evt) { evt.setChild(new Promise(function (resolve, reject) { // fetch the data for the specified id, then create a node with that data fetchData(evt.dest).then(function(data) { var child = document.createElement("div"); child.innerHTML = data; resolve({child: child}); }); ); });
-
delite-remove-child
-
Dispatched after an child Element has been removed from this widget.
- Inherited From:
- Source:
Example
element.addEventListener("delite-remove-child", function (evt) { console.log("container: " + evt.target.id + " removed child " + evt.child.id); });