Package org.apache.tapestry5.dom

Class Element

  • public final class Element
extends Node
    An element that will render with a begin tag and attributes, a body, and an end tag. Also acts as a factory for enclosed Element, Text and Comment nodes. TODO: Support for CDATA nodes. Do we need Entity nodes?

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      Element addClassName​(java.lang.String... classNames)
      Deprecated.
      Deprecated in 5.4, as this is now special behavior for the "class" attribute.
      Element attribute​(java.lang.String name, java.lang.String value)
      Adds an attribute to the element, but only if the attribute name does not already exist.
      Element attribute​(java.lang.String namespace, java.lang.String name, java.lang.String value)
      Adds a namespaced attribute to the element, but only if the attribute name does not already exist.
      Element attributes​(java.lang.String... namesAndValues)
      Convenience for invoking attribute(String, String) multiple times.
      CData cdata​(java.lang.String content)
      Adds and returns a new CDATA node.
      Element comment​(java.lang.String text)
      Adds the comment and returns this element for further construction.
      Element defineNamespace​(java.lang.String namespace, java.lang.String namespacePrefix)
      Defines a namespace for this element, mapping a URI to a prefix.
      Element element​(java.lang.String name, java.lang.String... namesAndValues)
      Creates and returns a new Element node as a child of this node.
      Element elementAt​(int index, java.lang.String name, java.lang.String... namesAndValues)
      Creates a new element, as a child of the current index, at the indicated index.
      Element elementBefore​(java.lang.String name, java.lang.String... namesAndValues)
      Inserts a new element before this element.
      Element elementNS​(java.lang.String namespace, java.lang.String name)
      Creates and returns a new Element within a namespace as a child of this node.
      Element find​(java.lang.String path)
      Searchs for a child element with a particular name below this element.
      Element forceAttributes​(java.lang.String... namesAndValues)
      Forces changes to a number of attributes.
      Element forceAttributesNS​(java.lang.String namespace, java.lang.String... namesAndValues)
      Forces changes to a number of attributes in the global namespace.
      java.lang.String getAttribute​(java.lang.String attributeName)  
      java.util.Collection<Attribute> getAttributes()
      Returns the attributes for this Element as a (often empty) collection of Attributes.
      java.lang.String getChildMarkup()  
      java.util.List<Node> getChildren()
      Returns an unmodifiable list of children for this element.
      Document getDocument()  
      Element getElement​(Predicate<Element> predicate)
      Tries to find an element under this element (including itself) accepted by the given predicate.
      Element getElementByAttributeValue​(java.lang.String attributeName, java.lang.String attributeValue)
      Tries to find an element under this element (including itself) whose given attribute has a given value.
      Element getElementById​(java.lang.String id)
      Tries to find an element under this element (including itself) whose id is specified.
      java.lang.String getName()  
      java.lang.String getNamespace()
      Returns the namespace for this element (which is typically a URL).
      protected java.util.Map<java.lang.String,​java.lang.String> getNamespaceURIToPrefix()  
      boolean isEmpty()
      Returns true if the element has no children, or has only text children that contain only whitespace.
      void pop()
      Removes an element; the element's children take the place of the node within its container.
      Element raw​(java.lang.String text)
      Adds the raw text and returns this element for further construction.
      Element removeChildren()
      Removes all children from this element.
      Text text​(java.lang.String text)
      Adds and returns a new text node (the text node is returned so that Text.write(String) or [@link Text.writef(String, Object[]) may be invoked .
      void visit​(Visitor visitor)
      Depth-first visitor traversal of this Element and its Element children.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Method Detail

      • attribute

        public Element attribute​(java.lang.String name,
                         java.lang.String value)
        Adds an attribute to the element, but only if the attribute name does not already exist. The "class" attribute is treated specially: the new value is appended, after a space, to the existing value.
        Parameters:
        name - the name of the attribute to add
        value - the value for the attribute. A value of null is allowed, and no attribute will be added to the element.

      • attribute

        public Element attribute​(java.lang.String namespace,
                         java.lang.String name,
                         java.lang.String value)
        Adds a namespaced attribute to the element, but only if the attribute name does not already exist. The "class" attribute of the default namespace is treated specially: the new value is appended, after a space, to the existing value.
        Parameters:
        namespace - the namespace to contain the attribute, or null for the default namespace
        name - the name of the attribute to add
        value - the value for the attribute. A value of null is allowed, and no attribute will be added to the element.

      • attributes

        public Element attributes​(java.lang.String... namesAndValues)
        Convenience for invoking attribute(String, String) multiple times.
        Parameters:
        namesAndValues - alternating attribute names and attribute values

      • forceAttributes

        public Element forceAttributes​(java.lang.String... namesAndValues)
        Forces changes to a number of attributes. The new attributes overwrite previous values. Overriding an attribute's value to null will remove the attribute entirely.
        Parameters:
        namesAndValues - alternating attribute names and attribute values
        Returns:
        this element

      • forceAttributesNS

        public Element forceAttributesNS​(java.lang.String namespace,
                                 java.lang.String... namesAndValues)
        Forces changes to a number of attributes in the global namespace. The new attributes overwrite previous values (event for the "class" attribute). Overriding attribute's value to null will remove the attribute entirely. TAP5-708: don't use element namespace for attributes
        Parameters:
        namespace - the namespace or null
        namesAndValues - alternating attribute name and value
        Returns:
        this element

      • element

        public Element element​(java.lang.String name,
                       java.lang.String... namesAndValues)
        Creates and returns a new Element node as a child of this node.
        Parameters:
        name - the name of the element to create
        namesAndValues - alternating attribute names and attribute values

      • elementBefore

        public Element elementBefore​(java.lang.String name,
                             java.lang.String... namesAndValues)
        Inserts a new element before this element.
        Parameters:
        name - element name
        namesAndValues - attribute names and values
        Returns:
        the new element
        Since:
        5.3

      • elementNS

        public Element elementNS​(java.lang.String namespace,
                         java.lang.String name)
        Creates and returns a new Element within a namespace as a child of this node.
        Parameters:
        namespace - namespace to contain the element, or null
        name - element name to create within the namespace
        Returns:
        the newly created element

      • elementAt

        public Element elementAt​(int index,
                         java.lang.String name,
                         java.lang.String... namesAndValues)
        Creates a new element, as a child of the current index, at the indicated index.
        Parameters:
        index - to insert at
        name - element name
        namesAndValues - attribute name / attribute value pairs
        Returns:
        the new element

      • comment

        public Element comment​(java.lang.String text)
        Adds the comment and returns this element for further construction.

      • raw

        public Element raw​(java.lang.String text)
        Adds the raw text and returns this element for further construction.

      • cdata

        public CData cdata​(java.lang.String content)
        Adds and returns a new CDATA node.
        Parameters:
        content - the content to be rendered by the node
        Returns:
        the newly created node

      • getElementById

        public Element getElementById​(java.lang.String id)
        Tries to find an element under this element (including itself) whose id is specified. Performs a width-first search of the document tree.
        Parameters:
        id - the value of the id attribute of the element being looked for
        Returns:
        the element if found. null if not found.

      • getElementByAttributeValue

        public Element getElementByAttributeValue​(java.lang.String attributeName,
                                          java.lang.String attributeValue)
        Tries to find an element under this element (including itself) whose given attribute has a given value.
        Parameters:
        attributeName - the name of the attribute of the element being looked for
        attributeValue - the value of the attribute of the element being looked for
        Returns:
        the element if found. null if not found.
        Since:
        5.2.3

      • getElement

        public Element getElement​(Predicate<Element> predicate)
        Tries to find an element under this element (including itself) accepted by the given predicate.
        Parameters:
        predicate - Predicate to accept the element
        Returns:
        the element if found. null if not found.
        Since:
        5.2.3

      • find

        public Element find​(java.lang.String path)
        Searchs for a child element with a particular name below this element. The path parameter is a slash separated series of element names.

      • getAttribute

        public java.lang.String getAttribute​(java.lang.String attributeName)

      • getName

        public java.lang.String getName()

      • addClassName

        public Element addClassName​(java.lang.String... classNames)
        Deprecated.
        Deprecated in 5.4, as this is now special behavior for the "class" attribute.
        Adds one or more CSS class names to the "class" attribute.
        Parameters:
        classNames - one or more CSS class names
        Returns:
        the element for further configuration

      • defineNamespace

        public Element defineNamespace​(java.lang.String namespace,
                               java.lang.String namespacePrefix)
        Defines a namespace for this element, mapping a URI to a prefix. This will affect how namespaced elements and attributes nested within the element are rendered, and will also cause xmlns: attributes (to define the namespace and prefix) to be rendered.
        Parameters:
        namespace - URI of the namespace
        namespacePrefix - prefix
        Returns:
        this element

      • getNamespace

        public java.lang.String getNamespace()
        Returns the namespace for this element (which is typically a URL). The namespace may be null.

      • pop

        public void pop()
        Removes an element; the element's children take the place of the node within its container.

      • removeChildren

        public Element removeChildren()
        Removes all children from this element.
        Returns:
        the element, for method chaining

      • isEmpty

        public boolean isEmpty()
        Returns true if the element has no children, or has only text children that contain only whitespace.
        Since:
        5.1.0.0

      • visit

        public void visit​(Visitor visitor)
        Depth-first visitor traversal of this Element and its Element children. The traversal order is the same as render order.
        Parameters:
        visitor - callback
        Since:
        5.1.0.0

      • getChildMarkup

        public final java.lang.String getChildMarkup()
        Returns:
        the concatenation of the String representations Node.toString() of its children.

      • getChildren

        public java.util.List<Node> getChildren()
        Returns an unmodifiable list of children for this element. Only Elements will have children. Also, note that unlike W3C DOM, attributes are not represented as Nodes.
        Returns:
        unmodifiable list of children nodes

      • getAttributes

        public java.util.Collection<Attribute> getAttributes()
        Returns the attributes for this Element as a (often empty) collection of Attributes. The order of the attributes within the collection is not specified. Modifying the collection will not affect the attributes (use forceAttributes(String[]) to change existing attribute values, and attribute(String, String, String) to add new attribute values.
        Returns:
        attribute collection