Menu
pushmode.dom

Class DomElement

PushMode » API Reference » pushmode.dom

  • All Implemented Interfaces:
    Cloneable
    Direct Known Subclasses:
    AnyHtmlElement, AnySvgElement


    public abstract class DomElement
    extends DomContainer
    Element in PushMode DOM tree. Every element inherits from DomContainer, which means it has a list of DomContent children. In addition, element has attributes, attached listeners, and some special properties like and id() and key().
    DomElement cannot be directly instantiated. PushMode instead provides a library of standard elements that inherit from DomElement. Application code can instantiate elements more intuitively using Html class. Attributes can be set by calling specialized fluent setters provided by derived classes for every applicable attribute.
    Every element can have an id(). Element ID is serialized as an id attribute in HTML. Element ID has a special meaning in PushMode. Listeners require the element to have an ID. Listeners on ID-less elements are ignored. ID is also the default value of key().
    Every element can have a key(). It is the same as id() by default, but it can be set separately via key(Object). Any object implementing Object.equals(Object) and Object.hashCode() can be used as a key(). While id() is sent to the browser, is a String, and it should be unique in the document, key() is used only server-side, can be of any type, and it only needs to be unique among sibling elements. It is used in hierarchical DOM diff to pair corresponding elements in cases where some DOM nodes have been inserted or removed from parent's child list. If neither key() nor id() is specified, DOM diff uses element position to pair elements in compared DOM trees, which might result in unnecessarily big diffs if an element is inserted at the beginning of a long list. Absence of key() thus doesn't impact functionality, only performance. And even then it matters only if siblings are inserted or removed.
    In order to provide interactivity for elements, application can call onX() methods to add event handlers or call binding overrides for two-way attributes like e.g. value attribute on <input> element.
    Thread-safety:
    Element can be only accessed by single thread at a time unless it is frozen. Frozen element can be safely shared by multiple threads. Parallel access to mutable element will result in corruption of its internal state. Parallel read-only operations are permitted though.
    • Constructor Detail

      • DomElement

        @InternalPushModeApi
        protected DomElement()
        Creates new empty element. Applications never call this method directly. PushMode provides derived classes for all standard elements.
      • DomElement

        @InternalPushModeApi
        protected DomElement(DomElement other)
        Creates deep mutable copy of another element. Applications never call this method directly. Method clone() should be used to create deep mutable clones.
        Parameters:
        other - Element to clone. This method throws NullPointerException if the parameter is null.
        Throws:
        NullPointerException - The parameter is null.
    • Method Detail

      • tagname

        public abstract String tagname()
        Element's tag name. This is lowercase tag name of the element, e.g. div. Tag name cannot be changed. It is determined by derived class, which overrides this method.
        Returns:
        Element's tag name.
      • clone

        public abstract DomElement clone()
        Creates mutable deep clone of this element. All child nodes are cloned recursively. The clone is completely independent of this element.
        Specified by:
        clone in class DomContainer
        Returns:
        Deep mutable clone.
        Thread-safety:
        This method can be executed concurrently with other read-only operations on the same element. If this element is modified while being cloned, some descendants, attributes, and listeners in the clone might be missing or duplicated, but this method will never throw, this element is never damaged, and the cloned element will be always internally consistent.
      • freeze

        public DomElement freeze()
        Creates frozen deep clone of this element. Mutating methods throw IllegalStateException when executed on frozen element. Frozen elements can be safely shared by all threads. Freezing is recursive. Frozen elements therefore cannot contain mutable nodes.
        Freezing applies several transformations to the cloned element, so that these transformations don't have to be performed repeatedly during rendering. All DomFragment descendants are recursively inlined into their respective parents, so that the frozen element contains no DomFragment descendants. Freezing the element causes all consecutive text nodes to be concatenated into single node. If the resulting text node is empty, it is removed. Listeners are discarded on this and descendant elements with null id(). All internal arrays are compacted, so that the frozen DOM tree takes up minimum amount of memory. None of these transformations modifies the original element in any way.
        Overrides:
        freeze in class DomContainer
        Returns:
        Deep frozen clone. Returns this if this element is already frozen.
        Thread-safety:
        This method can be executed concurrently with other read-only operations on the same element. If this element is modified while being cloned, some children, attributes, and listeners in the clone or its descendants might be missing or duplicated, but this method will never throw, this element is never damaged, and the cloned element will be always internally consistent aside from possible duplicates of attributes and listeners, which are harmless.
      • experimental_isVoid

        @ExperimentalPushModeApi
        public boolean experimental_isVoid()
        Experimental API. It WILL be removed in future release.
      • key

        public Object key()
        Element's pairing key. This method returns element key set via key(Object). Key is identical to id() by default or if key(Object) was called with null parameter.
        Returns:
        Element's key.
      • key

        public DomElement key(Object key)
        Sets element's pairing key. Any object implementing Object.equals(Object) and Object.hashCode() can be used as a key. Key, if set, must be unique among siblings in the DOM tree. Once set, the key is available from key(). If the key is set to null, key() will return id().
        While id() is sent to the browser, is a String, and it should be unique in the document, key() is used only server-side, can be of any type, and it only needs to be unique among sibling elements.
        Key is used in hierarchical DOM diff to pair corresponding elements in cases where some DOM nodes have been inserted or removed from parent's child list. If key() is null, DOM diff uses element position to pair elements in compared DOM trees, which might result in unnecessarily big diffs if an element is inserted at the beginning of a long list. Absence of key thus doesn't impact functionality, only performance. And even then it matters only if siblings are inserted or removed.
        Parameters:
        key - New element key. Any object implementing Object.equals(Object) and Object.hashCode() can be used as a key. Key, if set, must be unique among siblings in the DOM tree. If this parameter is null, key() will return id().
        Returns:
        this
        Throws:
        IllegalStateException - Thrown if this element is frozen.
      • id

        public DomElement id(String id)
        Sets element's ID. Element ID is serialized as an id attribute in HTML. It must therefore fulfill criteria for proper element ID in HTML, which most importantly means the ID should be unique in the document. Element ID has a special meaning in PushMode. Listeners require the element to have an ID. Listeners on ID-less elements are ignored. Once set, the ID is available from id() method. ID is the default value of key().
        Parameters:
        id - New element ID.
        Returns:
        this
        Throws:
        IllegalStateException - This element is frozen.
      • experimental_posterOnly

        @ExperimentalPushModeApi
        public boolean experimental_posterOnly()
        Experimental API. It WILL be removed in future release.
      • equals

        public boolean equals(Object object)
        Compares two elements. If the supplied object is not an instance of the same class as this element, this method returns false. This method compares id(), key(), attributes, listeners, and element's children. Children are compared recursively by calling their DomContent.equals(Object) methods. If one of the elements is frozen and the other is not, this method returns false. Order of attributes and listeners is significant. Listeners must have identical callback pointers to compare equal.
        Overrides:
        equals in class DomContainer
        Parameters:
        object - Object to compare this element with.
        Returns:
        True if the two elements are equal.
      • hashCode

        public int hashCode()
        Computes deep hash code of the element.
        Overrides:
        hashCode in class DomContainer
        Returns:
        Hash code of the element.
      • experimental_attribute

        @ExperimentalPushModeApi
        public DomElement experimental_attribute(pushmode.dom.experimental.DomAttribute attribute)
        Experimental API. It WILL be removed in future release.
      • experimental_subscribe

        @ExperimentalPushModeApi
        public DomElement experimental_subscribe(pushmode.dom.experimental.DomListener listener)
        Experimental API. It WILL be removed in future release.
      • add

        public <C extends DomContentDomElement add(C... children)
        Adds all nodes in an array to this element.
        Overrides:
        add in class DomContainer
        Parameters:
        children - Array of child nodes to add. This method has no effect if the parameter is null. Array items that are null are skipped.
        Returns:
        this
        Throws:
        IllegalStateException - This element is frozen.
        See Also:
        add(DomContent)
      • text

        public DomElement text(String text)
        Adds literal text to this element The text is first wrapped in DomText. If the text is null or empty, this method has no effect.
        Overrides:
        text in class DomContainer
        Parameters:
        text - Text to add. This method has no effect if the text is null or empty.
        Returns:
        this
        Throws:
        IllegalStateException - This element is frozen.
        See Also:
        add(DomContent)
      • clazz

        public DomElement clazz(String value)
        Sets class attribute. If the attribute is already set, this method appends new value to the old value separated by space.
        Parameters:
        value - Text to set/append to the class attribute. This method has no effect if the parameter is null.
        Returns:
        this
        Throws:
        IllegalStateException - This element is frozen.
      • data

        public DomElement data(String key,
                               String value)
        Sets data-* attribute.
        Parameters:
        key - Name of the attribute if formed from its key and 'data-' prefix, e.g. key hello will set attribute data-hello. This method has no effect if the parameter is null.
        value - Text to write to the data-[key] attribute. This method has no effect if the parameter is null.
        Returns:
        this
        Throws:
        IllegalStateException - This element is frozen.
      • style

        public DomElement style(String value)
        Sets style attribute. If the attribute is already set, this method appends new value to the old value separated by semicolon.
        Parameters:
        value - Text to set/append to the style attribute. This method has no effect if the parameter is null.
        Returns:
        this
        Throws:
        IllegalStateException - This element is frozen.
      • experimental_attributes

        @ExperimentalPushModeApi
        public List<pushmode.dom.experimental.DomAttribute> experimental_attributes()
        Experimental API. It WILL be removed in future release.
      • experimental_listeners

        @ExperimentalPushModeApi
        public List<pushmode.dom.experimental.DomListener> experimental_listeners()
        Experimental API. It WILL be removed in future release.
      • id

        public String id()
        Element ID. This method returns element ID set via id(String). ID is null by default.
        Returns:
        Element ID.