org.apache.tapestry5.dom
Class Element

java.lang.Object
  extended by org.apache.tapestry5.dom.Node
      extended by 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
 Element addClassName(String... className)
          Adds one or more CSS class names to 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 Attributes.
 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.

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.

Parameters:
namespace - the namespace to contain the attribute, or null
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. 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... className)
Adds one or more CSS class names to the "class" attribute. No check for duplicates is made. Note that CSS class names are case insensitive on the client.

Parameters:
className - 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 Elements will have children. Also, note that unlike W3C DOM, attributes are not represented as Nodes.

Returns:
unmodifiable list of children nodes

getAttributes

public 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


Copyright © 2003-2012 The Apache Software Foundation.