org.thymeleaf.dom
Class DOMSelector

Object
  org.thymeleaf.dom.DOMSelector

All Implemented Interfaces:

Serializable

public final class DOMSelector
extends Object
implements Serializable

DOM Selectors model selections of subtrees from Thymeleaf DOM trees.

A common use of these selectors is for including fragments of other templates without the need of these other templates having any Thymeleaf code.

Note this class exists since 2.0.0, but its syntax has been greatly enhanced in 2.1.0.

Selection features

DOM Selector selection operations are based on:

• The type of node: both tags (elements) and text nodes can be selected.
• The name of the element (element = tag).
• The path and depth of the node in the DOM tree.
• The attributes of the element (if it is an element).
• The index of the node: its position among its siblings (brother nodes of the same kind).
• The references applied to the node. These references are resolved by means of the specification of an object implementing DOMSelector.INodeReferenceChecker at selector execution time, and allow the selection of nodes by features other than the standard ones (name, attributes, etc.).

Syntax

DOM Selector syntax is similar to that of XPath or jQuery selectors:

• Paths:
  • /x means direct children of the current node which either have name x or match reference x. For example: /html/body/ul/li.
  • //x means children of the current node which either have name x or match reference x, at any depth. For example: //li.
  • x is exactly equivalent to //x.
  • text() means Text nodes (at the specified level). For example: //li/text().
• Attribute/index modifiers:
  • x[@z='v'] means elements with name x and an attribute called z with value v.
  • [@z='v'] means elements with any name and an attribute called z with value v.
  • Other operators are also valid, besides = (equal): != (not equal), ^= (starts with) and $= (ends with). For example: x[@class^='section'] means elements with name x and a value for attribute class that starts with section.
  • Attributes can be specified both starting with @ (XPath-style) and without (jQuery-style). So x[@z='v'] is actually equivalent to x[z='v'].
  • x[@z1='v1' and @z2='v2'] means elements with name x and attributes z1 and z2 with values v1 and v2, respectively.
  • Multiple-attribute modifiers can be joined with and (XPath-style) and also by chaining multiple modifiers (jQuery-style). So x[@z1='v1' and @z2='v2'] is actually equivalent to x[@z1='v1'][@z2='v2'] (and also to x[z1='v1'][z2='v2'])
  • x[i] means element with name x positioned in number i among its siblings. Note index modifiers must always come after all attribute modifiers.
  • x[@z='v'][i] means elements with name x, attribute z with value v and positioned in number i among its siblings that also match this condition.
• Direct selectors:
  • x.oneclass is equivalent to x[class='oneclass'].
  • .oneclass is equivalent to [class='oneclass'].
  • x#oneid is equivalent to x[id='oneid'].
  • #oneid is equivalent to [id='oneid'].
  • x%oneref means nodes -not just elements- with name x that match reference oneref according to the specified DOMSelector.INodeReferenceChecker implementation..
  • %oneref means nodes -not just elements- with any name that match reference oneref according to the specified DOMSelector.INodeReferenceChecker implementation.. Note this is actually equivalent to simply oneref because references can be used instead of element names, as explained above.
  • Direct selectors and attribute selectors can be mixed: a.external[@href^='https'].
• Specific features:
  • DOM Selectors understand the class attribute to be multivalued, and therefore allow the application of modifiers on this attribute even if the element has several class values. For example, x[class='two'] will match <x class="one two three"/>.

Objects of this class are thread-safe.

Since:

2.0.0

Author:

Daniel Fernández

See Also:

Serialized Form

Nested Class Summary

static class	DOMSelector.AbstractNodeReferenceChecker Common abstract implementation of DOMSelector.INodeReferenceChecker.
static class	DOMSelector.AggregatingNodeReferenceChecker Implementation of DOMSelector.INodeReferenceChecker that aggregates two other reference checker objects.
static interface	DOMSelector.INodeReferenceChecker Common interface for objects in charge of resolving references in DOM Selector expressions.

Constructor Summary

DOMSelector(String selectorExpression)
Creates a new DOM selector specified by the argument selector expression.

Method Summary

String	getSelectorExpression() Returns the expression that specifies this DOM selector.
List<Node>	select(List<Node> nodes) Executes the DOM selector against the specified list of nodes, returning the result of applying the selector expression.
List<Node>	select(List<Node> nodes, DOMSelector.INodeReferenceChecker referenceChecker) Executes the DOM selector against the specified list of nodes and using the specified reference checker (if references are used in the DOM selector expression).
List<Node>	select(Node node) Executes the DOM selector against the specified node, returning the result of applying the selector expression.
List<Node>	select(Node node, DOMSelector.INodeReferenceChecker referenceChecker) Executes the DOM selector against the specified node and using the specified reference checker (if references are used in the DOM selector expression).
String	toString()

Methods inherited from class Object

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

Constructor Detail

DOMSelector

public DOMSelector(String selectorExpression)

Creates a new DOM selector specified by the argument selector expression.

Parameters:

selectorExpression - the expression specifying the selector to be used.

Method Detail

getSelectorExpression

public String getSelectorExpression()

Returns the expression that specifies this DOM selector.

Returns:

the selector expression.

Since:

2.0.12

select

public List<Node> select(Node node)

Executes the DOM selector against the specified node, returning the result of applying the selector expression.

Parameters:

node - the node on which the selector will be executed.

Returns:

the result of executing the selector.

select

public List<Node> select(Node node,
                         DOMSelector.INodeReferenceChecker referenceChecker)

Executes the DOM selector against the specified node and using the specified reference checker (if references are used in the DOM selector expression).

Parameters:

node - the node on which the selector will be executed.

referenceChecker - the checker that will be used to compute whether a Node matches or not a specified reference. Can be null.

Returns:

the result of executing the selector.

Since:

2.1.0

select

public List<Node> select(List<Node> nodes)

Executes the DOM selector against the specified list of nodes, returning the result of applying the selector expression.

Parameters:

nodes - the nodes on which the selector will be executed.

Returns:

the result of executing the selector.

select

public List<Node> select(List<Node> nodes,
                         DOMSelector.INodeReferenceChecker referenceChecker)

Executes the DOM selector against the specified list of nodes and using the specified reference checker (if references are used in the DOM selector expression).

Parameters:

nodes - the nodes on which the selector will be executed.

referenceChecker - the checker that will be used to compute whether a Node matches or not a specified reference. Can be null.

Returns:

the result of executing the selector.

Since:

2.1.0

toString

public String toString()

Overrides:

toString in class Object