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

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