Package org.apache.tapestry5.dom

## Class Element

- java.lang.Object
- - org.apache.tapestry5.dom.Node
  - - org.apache.tapestry5.dom.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​(String... classNames)` | Deprecated. Deprecated in 5.4, as this is now special behavior for the "class" attribute.
    `Element` | `attribute​(String name, String value)` | Adds an attribute to the element, but only if the attribute name does not already exist.
    `Element` | `attribute​(String namespace, String name, String value)` | Adds a namespaced attribute to the element, but only if the attribute name does not already exist.
    `Element` | `attributes​(String... namesAndValues)` | Convenience for invoking `attribute(String, String)` multiple times.
    `CData` | `cdata​(String content)` | Adds and returns a new CDATA node.
    `Element` | `comment​(String text)` | Adds the comment and returns this element for further construction.
    `Element` | `defineNamespace​(String namespace, String namespacePrefix)` | Defines a namespace for this element, mapping a URI to a prefix.
    `Element` | `element​(String name, String... namesAndValues)` | Creates and returns a new Element node as a child of this node.
    `Element` | `elementAt​(int index, String name, String... namesAndValues)` | Creates a new element, as a child of the current index, at the indicated index.
    `Element` | `elementBefore​(String name, String... namesAndValues)` | Inserts a new element before this element.
    `Element` | `elementNS​(String namespace, String name)` | Creates and returns a new Element within a namespace as a child of this node.
    `Element` | `find​(String path)` | Searchs for a child element with a particular name below this element.
    `Element` | `forceAttributes​(String... namesAndValues)` | Forces changes to a number of attributes.
    `Element` | `forceAttributesNS​(String namespace, String... namesAndValues)` | Forces changes to a number of attributes in the global namespace.
    `String` | `getAttribute​(String attributeName)` |
    `Collection<Attribute>` | `getAttributes()` | Returns the attributes for this Element as a (often empty) collection of `Attribute`s.
    `String` | `getChildMarkup()` |
    `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​(String attributeName, String attributeValue)` | Tries to find an element under this element (including itself) whose given attribute has a given value.
    `Element` | `getElementById​(String id)` | Tries to find an element under this element (including itself) whose id is specified.
    `String` | `getName()` |
    `String` | `getNamespace()` | Returns the namespace for this element (which is typically a URL).
    `protected Map<String,​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​(String text)` | Adds the raw text and returns this element for further construction.
    `Element` | `removeChildren()` | Removes all children from this element.
    `Text` | `text​(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 org.apache.tapestry5.dom.Node

      `getContainer, moveAfter, moveBefore, moveToBottom, moveToTop, remove, toMarkup, toString, wrap`

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### getDocument

          public Document getDocument()

      Overrides:
        `getDocument` in class `Node`

    - #### attribute

          public Element attribute​(String name,
                                   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​(String namespace,
                                   String name,
                                   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​(String... namesAndValues)

      Convenience for invoking `attribute(String, String)` multiple times.
      Parameters:
        `namesAndValues` - alternating attribute names and attribute values

    - #### forceAttributes

          public Element forceAttributes​(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​(String namespace,
                                           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​(String name,
                                 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​(String name,
                                       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​(String namespace,
                                   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,
                                   String name,
                                   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​(String text)

      Adds the comment and returns this element for further construction.

    - #### raw

          public Element raw​(String text)

      Adds the raw text and returns this element for further construction.

    - #### text

          public Text text​(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 .
      Parameters:
        `text` - initial text for the node
      Returns:
        the new Text node

    - #### cdata

          public CData cdata​(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​(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​(String attributeName,
                                                    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​(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 String getAttribute​(String attributeName)

    - #### getName

          public String getName()

    - #### addClassName

          public Element addClassName​(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​(String namespace,
                                         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 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

    - #### getNamespaceURIToPrefix

          protected Map<String,​String> getNamespaceURIToPrefix()

      Overrides:
        `getNamespaceURIToPrefix` in class `Node`

    - #### 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 String getChildMarkup()

      Returns:
        the concatenation of the String representations `Node.toString()` of its children.

    - #### getChildren

          public List<Node> getChildren()

      Returns an unmodifiable list of children for this element. Only `Element`s will have children. Also, note that unlike W3C DOM, attributes are not represented as `Node`s.
      Returns:
        unmodifiable list of children nodes

    - #### getAttributes

          public Collection<Attribute> getAttributes()

      Returns the attributes for this Element as a (often empty) collection of `Attribute`s. 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