Creates a new element of type tag with optional attribs. If parent is not null, the new element will be inserted as child at given insert index. If child is missing, the element will be appended to the parent's list of children. Returns new target DOM node.
In the default implementation, if tag is a known SVG element name, the new element will be created with the proper SVG XML namespace.
parent node in target (e.g. DOM element)
element tag name
element attributes
child index
Creates and appends the given content as text child node to parent in the target.
parent node in target (e.g. DOM element)
content
Realizes the given hdom tree in the target below the parent node, e.g. in the case of the browser DOM, creates all required DOM elements encoded by the given hdom tree.
parent node in target (e.g. DOM element)
component tree
child index
true, if ILifecycle.init methods are called
Takes an HDOMOpts options object, a parent element and two normalized hiccup trees, prev and curr. Recursively computes diff between both trees and applies any necessary changes to reflect curr tree, based on the differences to prev, in target (browser DOM when using the DEFAULT_IMPL implementation).
All target modification operations are delegated to the given implementation. diffTree() merely manages which elements or attributes need to be created, updated or removed and this NEVER involves any form of tracking of the actual underlying target data structure (e.g. the real browser DOM). hdom in general and diffTree() specifically are stateless. The only state available is implicitly defined by the two trees given (prev / curr).
Implementations MUST check for the presence of the __impl control attribute on each branch. If present AND different than the current implementation, the latter MUST delegate to the diffTree() method of the specified implementation and not descent into that branch further itself.
Furthermore, if (and only if) an element has the __diff control attribute set to false, then:
release life cycle methods present anywhere in the current prev tree (branch). The recursive release process itself is implemented by the exported releaseDeep() function in diff.ts. Custom implementations are encouraged to reuse this, since that function also takes care of handling the __release attrib: if the attrib is present and set to false, releaseDeep() will not descend into the branch any further.replaceChild() method to replace the old element / branch with the new one.hdom config options
parent node in target (e.g. DOM element)
previous component tree
current component tree
child index
Retrieves child of parent node at index i.
parent node in target (e.g. DOM element)
child index
Attempts to find an element with the given id attribute in the implementation's tree. In the default implementation this is merely delegated to document.getElementById().
element ID
Takes a target root element and normalized hdom tree, then walks tree and initializes any event listeners and components with life cycle init methods. Assumes that an equivalent "DOM" (minus listeners) already exists when this function is called. Any other discrepancies between the pre-existing DOM and the hdom tree might cause undefined behavior.
Implementations MUST check for the presence of the __impl control attribute on each branch. If given, the current implementation MUST delegate to the hydrateTree() method of the specified implementation and not descent into that branch further itself.
hdom config options
parent node in target (e.g. DOM element)
component tree
child index
Normalizes given hdom tree, expands Emmet-style tags, embedded iterables, component functions, component objects with life cycle methods and injects key attributes for diffTree() to later identify changes in nesting order. During normalization any embedded component functions are called with the given (optional) user ctx object as first argument. For further details of the default implementation, please see normalizeTree() in normalize.ts.
Implementations MUST check for the presence of the __impl control attribute on each branch. If given, the current implementation MUST delegate to the normalizeTree() method of the specified implementation and not descent into that branch further itself.
Furthermore, if (and only if) an element has the __normalize control attrib set to false, the normalization of that element's children MUST be skipped.
Calling this function is a prerequisite before passing a component tree to diffTree(). Recursively expands given hiccup component tree into its canonical form:
["tag", { attribs }, ...body]
div#id.foo.bar)key attribs)class attrib values (if given), e.g. ["div.foo", { class: "bar" }] => ["div", {class: "bar foo" }]render life cycle method on component objects and uses resultderef() on elements implementing the IDeref interface and uses returned resultstoHiccup() on elements implementing the IToHiccup interface and uses returned results.toString() on any other non-component value and by default wraps it in ["span", x]. The only exceptions to this are: button, option, textarea and SVG text elements, for which spans are never created.Additionally, unless the keys option is explicitly set to false, an unique key attribute is created for each node in the tree. This attribute is used by diffTree to determine if a changed node can be patched or will need to be moved, replaced or removed.
In terms of life cycle methods: render should ALWAYS return an array or another function, else the component's init or release fns will NOT be able to be called. E.g. If the return value of render evaluates as a string or number, it should be wrapped as ["span", "foo"] or an equivalent wrapper node. If no init or release methods are used, this requirement is relaxed.
See normalizeElement (normalize.ts) for further details about the canonical element form.
hdom config options
component tree
Removes given attribs from target element. The attributes from the previous tree are provided for reference (e.g. to be able to remove DOM event listeners).
target element / DOM node
element attributes
previous attributes
Removes the child of parent at index i in the target.
parent node in target (e.g. DOM element)
child index
A (potentially) optimized version of these 2 operations in sequence:
impl.removeChild(parent, child);
impl.createTree(parent, child, newTree);
parent node in target (e.g. DOM element)
child index
component tree
Sets the given attribute id to new value. Note: value itself can be a function and if so, the default behavior is to call this function with the also provided attribs object to allow it to produce a derived value. See setAttrib() (dom.ts) for details.
target element / DOM node
attribute name
attribute value
object with all attribs
Sets target element's text / body content. Note: In the default browser DOM implementation, this will implicitly remove any existing child elements in the target. In practice this function is only applied to ["span"] elements, since (by default) any body content is automatically wrapped in such by normalizeTree().
target element / DOM node
new content
Generated using TypeDoc
This interface defines the underlying target update operations used by
diffTree()andcreateDOM(). It allows {@link @thi.ng/hdom# | @thi.ng/hdom} to be used as general purpose tree definition & differential update mechanism, rather than being restricted to only work with an HTML DOM. See DEFAULT_IMPL for the default implementations dealing with the latter. Note: Depending on use case and tree configuration, not all of these methods are required.Custom element-local implementations can also be provided via the special
__implhdom element/component attribute. In this case the element itself and all of its children will be processed with those custom operations.