DOM (Document Object Model) Factory, Adapter Module for Base Library
This module provides the base implementation of a factory to create DOM elements, listeners and events. It is intended to be replaced with a custom factory creating widgets on top of regular DOM elements for the support of Rich Internet Applications.
A custom factory is an object with the same methods defined in this module. All the methods defined in the base factory must be supported by your custom factory.
The custom factory can be configured by calling setOptions on the application core:
lb.core.application.setOptions({ lbFactory: your.customFactory })To develop your own custom factory, you can start by creating a new module as a closure assigned to your own namespace. You can then add all required methods, just calling the same method in the base factory to use the default implementation. You may find it handy to declare an alias for the base factory at the start of your module:
var baseFactory = lb.base.dom.factory;
In addition to the mandatory methods defined by the base factory, you may optionally support the initElement method, which is an extra extension point intended for use in custom factories:
Eric Bréchemier © 2011, Some Rights Reserved Legal-Box SAS © 2010-2011, All Rights Reserved
BSD License http://creativecommons.org/licenses/BSD/
2011-08-14
| lb. | DOM (Document Object Model) Factory, Adapter Module for Base Library |
| Functions | |
| initElement(element) | (optional) Customize a newly inserted element. |
| createElement(name[,attributes[,childNodes]]): DOM Element | Create a new element with given name, attributes and child nodes. |
| destroyElement(element) | Terminate usage of a DOM element by removing it from its parent. |
| createListener(element, type, callback[, useCapture]) | Create a new listener for a type of event on a DOM element. |
| destroyListener(listener) | Terminate a listener by removing it from the target DOM element. |
| createEvent(element, type[, properties[, useCapture]]) | Create a new DOM event and fire it on given target element. |
| destroyEvent(event) | Terminate a DOM event: prevent default action and stop propagation. |
(optional) Customize a newly inserted element. Not implemented in the base factory.
The method differs from createElement which is responsible for the actual creation of the element node and is called before the node is inserted in the DOM. On the contrary, this method will be called on elements already part of the DOM.
When available on the configured factory, this method is currently called before a module starts, with the box element at the root of the module. It is also intended to get called in a template engine, to be added in a future version of the library, after inserting new contents in the box.
A custom factory may, for example, iterate recursively on the children of the given element, creating Rich Internet Application widgets when expected CSS classes are found on an element.
| element | DOM Element, an element part of the document. |
Create a new element with given name, attributes and child nodes.
| name | string, the name of the element, e.g. ‘div’ |
| attributes | object, the set of attributes, e.g. {id:’myDiv’, ‘class’:’big box’} |
| childNodes | array or list, the list of child nodes. The child nodes may be provided as an array, or as a list of arguments (after name and attributes). |
DOM Element, the newly created element
Create a new listener for a type of event on a DOM element.
| element | DOM Element, an element |
| type | string, the name of an event (without ‘on’) e.g. ‘click’ |
| callback | function, a function to call when the event is dispatched. |
| useCapture | boolean, whether the callback is set for capture phase. Optional: defaults to false. See [1] for details. |
object, a new instance of lb.base.dom.Listener
[1] DOM Level 2 Events: addEventListener http://bit.ly/9SQoL4
Terminate a listener by removing it from the target DOM element.
| listener | object, the listener returned by createListener, instance of lb.base.dom.Listener |
Create a new DOM event and fire it on given target element.
| element | DOM element, the target element for the event dispatch |
| type | string, the name of an event (without ‘on’) e.g. ‘click’ |
| properties | object, optional properties to set to the new event. |
| useCapture | boolean, whether the callback is set for capture phase. Optional: defaults to false. See [1] for details. |
object, the new DOM Event [2] created
[1] DOM Level 2 Events: addEventListener http://bit.ly/9SQoL4
[2] DOM Level 2 Events: Event interface http://bit.ly/b7KwF5
Terminate a DOM event: prevent default action and stop propagation.
Nothing happens in case the event is undefined, or lacks both of the expected stopPropagation() and preventDefault() methods. In case only one of the methods is missing, the other will get called.
| event | object, the DOM Event [1] |
[1] DOM Level 2 Events: Event interface http://bit.ly/b7KwF5