======== DOM Mode ======== DOM mode provides an output mode which generates DOM Elements from :js:func:`DOMBuilder.createElement` calls and DOM DocumentFragments from :js:func:`DOMBuilder.fragment` calls. The DOM mode API is exposed through ``DOMBuilder.modes.dom.api``. Mode-specific element functions are exposed through :js:attr:`DOMBuilder.dom`. .. js:attribute:: DOMBuilder.dom Element functions which will always create DOM Element output. .. versionadded:: 2.0 Attributes ========== Some attributes are given special treatment based on their name. .. _event-handlers: Event Handlers -------------- Event handlers can be specified by supplying an event name as one of the element's attributes and an event handling function as the corresponding value. Any of the following events can be registered in this manner: +----------------------------------------------------------------------+ | Event Names | +===========+===========+==========+============+============+=========+ | blur | focus | focusin | focusout | load | resize | +-----------+-----------+----------+------------+------------+---------+ | scroll | unload | click | dblclick | mousedown | mouseup | +-----------+-----------+----------+------------+------------+---------+ | mousemove | mouseover | mouseout | mouseenter | mouseleave | change | +-----------+-----------+----------+------------+------------+---------+ | select | submit | keydown | keypress | keyup | error | +-----------+-----------+----------+------------+------------+---------+ These correspond to `events which have jQuery shortcut methods`_, which will be used for event handler registration if jQuery is available, otherwise legacy event registration will be used. For example, the following will create a text input which displays a default value, clearing it when the input is focused and restoring the default if the input is left blank:: var defaultInput = el.INPUT({ type: 'text', name: 'email' , value: 'email@host.com', defaultValue: 'email@host.com' , focus: function() { if (this.value == this.defaultValue) { this.value = '' } } , blur: function() { if (this.value == '') { this.value = this.defaultValue } } } ) .. _`events which have jQuery shortcut methods`: http://api.jquery.com/category/events/ Other 'Special' Attributes -------------------------- Other attributes which trigger special handling or explicit compatibility handling between DOM and HTML modes. ``innerHTML`` If you specify an ``innerHTML`` attribute, the given String will be the sole source used to provide the element's contents, even if you pass more contents in as arguments. * In DOM mode, the element's ``innerHTML`` property will be set and no further children will be appended, even if given. * In HTML mode, the given HTML will be used, unescaped, as the element's contents. .. _document-fragments: Document Fragments ================== A `DOM DocumentFragment`_ is a lightweight container for elements which allows you to append its entire contents with a single call to the destination element's ``appendChild()`` method. If you're thinking of adding a wrapper ``