org.jsoup.nodes
Class Element

java.lang.Object
  org.jsoup.nodes.Node
      org.jsoup.nodes.Element

Direct Known Subclasses:

Document

public class Element
extends Node

A HTML element consists of a tag name, attributes, and child nodes (including text nodes and other elements). From an Element, you can extract data, traverse the node graph, and manipulate the HTML.

Author:

Jonathan Hedley, jonathan@hedley.net

Constructor Summary

Element(Tag tag, String baseUri)
Create a new Element from a tag and a base URI.

Element(Tag tag, String baseUri, Attributes attributes)
Create a new, standalone Element.

Method Summary

Element	addClass(String className) Add a class name to this element's class attribute.
Element	after(String html) Insert the specified HTML into the DOM after this element (i.e.
Element	append(String html) Add inner HTML to this element.
Element	appendChild(Node child) Add a node to the last child of this element.
Element	appendElement(String tagName) Create a new element by tag name, and add it as the last child.
Element	appendText(String text) Create and append a new TextNode to this element.
Element	attr(String attributeKey, String attributeValue) Set an attribute value on this element.
Element	before(String html) Insert the specified HTML into the DOM before this element (i.e.
Element	child(int index) Get a child element of this element, by its 0-based index number.
Elements	children() Get this element's child elements.
String	className() Gets the literal value of this element's "class" attribute, which may include multiple class names, space separated.
Set<String>	classNames() Get all of the element's class names.
Element	classNames(Set<String> classNames) Set the element's class attribute to the supplied class names.
String	data() Get the combined data of this element.
Map<String,String>	dataset() Get this element's HTML5 custom data attributes.
Integer	elementSiblingIndex() Get the list index of this element in its element sibling list.
Element	empty() Remove all of the element's child nodes.
boolean	equals(Object o)
Element	firstElementSibling() Gets the first element sibling of this element.
Elements	getAllElements() Find all elements under this element (including self, and children of children).
Element	getElementById(String id) Find an element by ID, including or under this element.
Elements	getElementsByAttribute(String key) Find elements that have a named attribute set.
Elements	getElementsByAttributeStarting(String keyPrefix) Find elements that have an attribute name starting with the supplied prefix.
Elements	getElementsByAttributeValue(String key, String value) Find elements that have an attribute with the specific value.
Elements	getElementsByAttributeValueContaining(String key, String match) Find elements that have attributes whose value contains the match string.
Elements	getElementsByAttributeValueEnding(String key, String valueSuffix) Find elements that have attributes that end with the value suffix.
Elements	getElementsByAttributeValueMatching(String key, Pattern pattern) Find elements that have attributes whose values match the supplied regular expression.
Elements	getElementsByAttributeValueMatching(String key, String regex) Find elements that have attributes whose values match the supplied regular expression.
Elements	getElementsByAttributeValueNot(String key, String value) Find elements that either do not have this attribute, or have it with a different value.
Elements	getElementsByAttributeValueStarting(String key, String valuePrefix) Find elements that have attributes that start with the value prefix.
Elements	getElementsByClass(String className) Find elements that have this class, including or under this element.
Elements	getElementsByIndexEquals(int index) Find elements whose sibling index is equal to the supplied index.
Elements	getElementsByIndexGreaterThan(int index) Find elements whose sibling index is greater than the supplied index.
Elements	getElementsByIndexLessThan(int index) Find elements whose sibling index is less than the supplied index.
Elements	getElementsByTag(String tagName) Finds elements, including and recursively under this element, with the specified tag name.
Elements	getElementsContainingOwnText(String searchText) Find elements that directly contain the specified string.
Elements	getElementsContainingText(String searchText) Find elements that contain the specified string.
Elements	getElementsMatchingOwnText(Pattern pattern) Find elements whose own text matches the supplied regular expression.
Elements	getElementsMatchingOwnText(String regex) Find elements whose text matches the supplied regular expression.
Elements	getElementsMatchingText(Pattern pattern) Find elements whose text matches the supplied regular expression.
Elements	getElementsMatchingText(String regex) Find elements whose text matches the supplied regular expression.
boolean	hasClass(String className) Tests if this element has a class.
int	hashCode()
boolean	hasText() Test if this element has any text content (that is not just whitespace).
String	html() Retrieves the element's inner HTML.
Element	html(String html) Set this element's inner HTML.
String	id() Get the id attribute of this element.
boolean	isBlock() Test if this element is a block-level element.
Element	lastElementSibling() Gets the last element sibling of this element
Element	nextElementSibling() Gets the next sibling element of this element.
String	nodeName() Get the node name of this node.
String	ownText() Gets the text owned by this element only; does not get the combined text of all children.
Element	parent() Gets this node's parent node.
Elements	parents() Get this element's parent and ancestors, up to the document root.
Element	prepend(String html) Add inner HTML into this element.
Element	prependChild(Node child) Add a node to the start of this element's children.
Element	prependElement(String tagName) Create a new element by tag name, and add it as the first child.
Element	prependText(String text) Create and prepend a new TextNode to this element.
Element	previousElementSibling() Gets the previous element sibling of this element.
Element	removeClass(String className) Remove a class name from this element's class attribute.
Elements	select(String query) Find elements that match the selector query, with this element as the starting context.
Elements	siblingElements() Get sibling elements.
Tag	tag() Get the Tag for this element.
String	tagName() Get the name of the tag for this element.
String	text() Gets the combined text of this element and all its children.
Element	text(String text) Set the text of this element.
Element	toggleClass(String className) Toggle a class name on this element's class attribute: if present, remove it; otherwise add it.
String	toString()
String	val() Get the value of a form element (input, textarea, etc).
Element	val(String value) Set the value of a form element (input, textarea, etc).
Element	wrap(String html) Wrap the supplied HTML around this element.

Methods inherited from class org.jsoup.nodes.Node

absUrl, addChildren, addChildren, attr, attributes, baseUri, childNode, childNodes, childNodesAsArray, hasAttr, indent, nextSibling, outerHtml, outerHtml, ownerDocument, previousSibling, remove, removeAttr, removeChild, replaceChild, replaceWith, setBaseUri, setParentNode, setSiblingIndex, siblingIndex, siblingNodes

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Element

public Element(Tag tag,
               String baseUri,
               Attributes attributes)

Create a new, standalone Element. (Standalone in that is has no parent.)

Parameters:

tag - tag of this element

baseUri - the base URI

attributes - initial attributes

See Also:

appendChild(Node), appendElement(String)

Element

public Element(Tag tag,
               String baseUri)

Create a new Element from a tag and a base URI.

Parameters:

tag - element tag

baseUri - the base URI of this element. It is acceptable for the base URI to be an empty string, but not null.

See Also:

Tag.valueOf(String)

Method Detail

nodeName

public String nodeName()

Description copied from class: Node

Get the node name of this node. Use for debugging purposes and not logic switching (for that, use instanceof).

Specified by:

nodeName in class Node

Returns:

node name

tagName

public String tagName()

Get the name of the tag for this element. E.g. div

Returns:

the tag name

tag

public Tag tag()

Get the Tag for this element.

Returns:

the tag object

isBlock

public boolean isBlock()

Test if this element is a block-level element. (E.g. <div> == true or an inline element <p> == false).

Returns:

true if block, false if not (and thus inline)

id

public String id()

Get the id attribute of this element.

Returns:

The id attribute, if present, or an empty string if not.

attr

public Element attr(String attributeKey,
                    String attributeValue)

Set an attribute value on this element. If this element already has an attribute with the key, its value is updated; otherwise, a new attribute is added.

Overrides:

attr in class Node

Parameters:

attributeKey - The attribute key.

attributeValue - The attribute value.

Returns:

this element

dataset

public Map<String,String> dataset()

Get this element's HTML5 custom data attributes. Each attribute in the element that has a key starting with "data-" is included the dataset.

E.g., the element <div data-package="jsoup" data-language="Java" class="group">... has the dataset package=jsoup, language=java.

This map is a filtered view of the element's attribute map. Changes to one map (add, remove, update) are reflected in the other map.

You can find elements that have data attributes using the [^data-] attribute key prefix selector.

Returns:

a map of key=value custom data attributes.

parent

public final Element parent()

Description copied from class: Node

Gets this node's parent node.

Overrides:

parent in class Node

Returns:

parent node; or null if no parent.

parents

public Elements parents()

Get this element's parent and ancestors, up to the document root.

Returns:

this element's stack of parents, closest first.

child

public Element child(int index)

Get a child element of this element, by its 0-based index number.

Note that an element can have both mixed Nodes and Elements as children. This method inspects a filtered list of children that are elements, and the index is based on that filtered list.

Parameters:

index - the index number of the element to retrieve

Returns:

the child element, if it exists, or null if absent.

See Also:

Node.childNode(int)

children

public Elements children()

Get this element's child elements.

This is effectively a filter on Node.childNodes() to get Element nodes.

Returns:

child elements. If this element has no children, returns an empty list.

See Also:

Node.childNodes()

select

public Elements select(String query)

Find elements that match the selector query, with this element as the starting context. Matched elements may include this element, or any of its children.

This method is generally more powerful to use than the DOM-type getElementBy* methods, because multiple filters can be combined, e.g.:

• el.select("a[href]") - finds links (a tags with href attributes)
• el.select("a[href*=example.com]") - finds links pointing to example.com (loosely)

See the query syntax documentation in Selector.

Parameters:

query - a Selector query

Returns:

elements that match the query (empty if none match)

See Also:

Selector

appendChild

public Element appendChild(Node child)

Add a node to the last child of this element.

Parameters:

child - node to add. Must not already have a parent.

Returns:

this element, so that you can add more child nodes or elements.

prependChild

public Element prependChild(Node child)

Add a node to the start of this element's children.

Parameters:

child - node to add. Must not already have a parent.

Returns:

this element, so that you can add more child nodes or elements.

appendElement

public Element appendElement(String tagName)

Create a new element by tag name, and add it as the last child.

Parameters:

tagName - the name of the tag (e.g. div).

Returns:

the new element, to allow you to add content to it, e.g.: parent.appendElement("h1").attr("id", "header").text("Welcome");

prependElement

public Element prependElement(String tagName)

Create a new element by tag name, and add it as the first child.

Parameters:

tagName - the name of the tag (e.g. div).

Returns:

the new element, to allow you to add content to it, e.g.: parent.prependElement("h1").attr("id", "header").text("Welcome");

appendText

public Element appendText(String text)

Create and append a new TextNode to this element.

Parameters:

text - the unencoded text to add

Returns:

this element

prependText

public Element prependText(String text)

Create and prepend a new TextNode to this element.

Parameters:

text - the unencoded text to add

Returns:

this element

append

public Element append(String html)

Add inner HTML to this element. The supplied HTML will be parsed, and each node appended to the end of the children.

Parameters:

html - HTML to add inside this element, after the existing HTML

Returns:

this element

See Also:

html(String)

prepend

public Element prepend(String html)

Add inner HTML into this element. The supplied HTML will be parsed, and each node prepended to the start of the element's children.

Parameters:

html - HTML to add inside this element, before the existing HTML

Returns:

this element

See Also:

html(String)

before

public Element before(String html)

Insert the specified HTML into the DOM before this element (i.e. as a preceeding sibling).

Parameters:

html - HTML to add before this element

Returns:

this element, for chaining

See Also:

after(String)

after

public Element after(String html)

Insert the specified HTML into the DOM after this element (i.e. as a following sibling).

Parameters:

html - HTML to add after this element

Returns:

this element, for chaining

See Also:

before(String)

empty

public Element empty()

Remove all of the element's child nodes. Any attributes are left as-is.

Returns:

this element

wrap

public Element wrap(String html)

Wrap the supplied HTML around this element.

Parameters:

html - HTML to wrap around this element, e.g. <div class="head"></div>. Can be arbitralily deep.

Returns:

this element, for chaining.

siblingElements

public Elements siblingElements()

Get sibling elements.

Returns:

sibling elements

nextElementSibling

public Element nextElementSibling()

Gets the next sibling element of this element. E.g., if a div contains two ps, the nextElementSibling of the first p is the second p.

This is similar to Node.nextSibling(), but specifically finds only Elements

Returns:

the next element, or null if there is no next element

See Also:

previousElementSibling()

previousElementSibling

public Element previousElementSibling()

Gets the previous element sibling of this element.

Returns:

the previous element, or null if there is no previous element

See Also:

nextElementSibling()

firstElementSibling

public Element firstElementSibling()

Gets the first element sibling of this element.

Returns:

the first sibling that is an element (aka the parent's first element child)

elementSiblingIndex

public Integer elementSiblingIndex()

Get the list index of this element in its element sibling list. I.e. if this is the first element sibling, returns 0.

Returns:

position in element sibling list

lastElementSibling

public Element lastElementSibling()

Gets the last element sibling of this element

Returns:

the last sibling that is an element (aka the parent's last element child)

getElementsByTag

public Elements getElementsByTag(String tagName)

Finds elements, including and recursively under this element, with the specified tag name.

Parameters:

tagName - The tag name to search for (case insensitively).

Returns:

a matching unmodifiable list of elements. Will be empty if this element and none of its children match.

getElementById

public Element getElementById(String id)

Find an element by ID, including or under this element.

Note that this finds the first matching ID, starting with this element. If you search down from a different starting point, it is possible to find a different element by ID. For unique element by ID within a Document, use getElementById(String)

Parameters:

id - The ID to search for.

Returns:

The first matching element by ID, starting with this element, or null if none found.

getElementsByClass

public Elements getElementsByClass(String className)

Find elements that have this class, including or under this element. Case insensitive.

Elements can have multiple classes (e.g. <div class="header round first">. This method checks each class, so you can find the above with el.getElementsByClass("header");.

Parameters:

className - the name of the class to search for.

Returns:

elements with the supplied class name, empty if none

See Also:

hasClass(String), classNames()

getElementsByAttribute

public Elements getElementsByAttribute(String key)

Find elements that have a named attribute set. Case insensitive.

Parameters:

key - name of the attribute, e.g. href

Returns:

elements that have this attribute, empty if none

getElementsByAttributeStarting

public Elements getElementsByAttributeStarting(String keyPrefix)

Find elements that have an attribute name starting with the supplied prefix. Use data- to find elements that have HTML5 datasets.

Parameters:

keyPrefix - name prefix of the attribute e.g. data-

Returns:

elements that have attribute names that start with with the prefix, empty if none.

getElementsByAttributeValue

public Elements getElementsByAttributeValue(String key,
                                            String value)

Find elements that have an attribute with the specific value. Case insensitive.

Parameters:

key - name of the attribute

value - value of the attribute

Returns:

elements that have this attribute with this value, empty if none

getElementsByAttributeValueNot

public Elements getElementsByAttributeValueNot(String key,
                                               String value)

Find elements that either do not have this attribute, or have it with a different value. Case insensitive.

Parameters:

key - name of the attribute

value - value of the attribute

Returns:

elements that do not have a matching attribute

getElementsByAttributeValueStarting

public Elements getElementsByAttributeValueStarting(String key,
                                                    String valuePrefix)

Find elements that have attributes that start with the value prefix. Case insensitive.

Parameters:

key - name of the attribute

valuePrefix - start of attribute value

Returns:

elements that have attributes that start with the value prefix

getElementsByAttributeValueEnding

public Elements getElementsByAttributeValueEnding(String key,
                                                  String valueSuffix)

Find elements that have attributes that end with the value suffix. Case insensitive.

Parameters:

key - name of the attribute

valueSuffix - end of the attribute value

Returns:

elements that have attributes that end with the value suffix

getElementsByAttributeValueContaining

public Elements getElementsByAttributeValueContaining(String key,
                                                      String match)

Find elements that have attributes whose value contains the match string. Case insensitive.

Parameters:

key - name of the attribute

match - substring of value to search for

Returns:

elements that have attributes containing this text

getElementsByAttributeValueMatching

public Elements getElementsByAttributeValueMatching(String key,
                                                    Pattern pattern)

Find elements that have attributes whose values match the supplied regular expression.

Parameters:

key - name of the attribute

pattern - compiled regular expression to match against attribute values

Returns:

elements that have attributes matching this regular expression

getElementsByAttributeValueMatching

public Elements getElementsByAttributeValueMatching(String key,
                                                    String regex)

Find elements that have attributes whose values match the supplied regular expression.

Parameters:

key - name of the attribute

regex - regular expression to match agaisnt attribute values. You can use embedded flags (such as (?i) and (?m) to control regex options.

Returns:

elements that have attributes matching this regular expression

getElementsByIndexLessThan

public Elements getElementsByIndexLessThan(int index)

Find elements whose sibling index is less than the supplied index.

Parameters:

index - 0-based index

Returns:

elements less than index

getElementsByIndexGreaterThan

public Elements getElementsByIndexGreaterThan(int index)

Find elements whose sibling index is greater than the supplied index.

Parameters:

index - 0-based index

Returns:

elements greater than index

getElementsByIndexEquals

public Elements getElementsByIndexEquals(int index)

Find elements whose sibling index is equal to the supplied index.

Parameters:

index - 0-based index

Returns:

elements equal to index

getElementsContainingText

public Elements getElementsContainingText(String searchText)

Find elements that contain the specified string. The search is case insensitive. The text may appear directly in the element, or in any of its descendants.

Parameters:

searchText - to look for in the element's text

Returns:

elements that contain the string, case insensitive.

See Also:

text()

getElementsContainingOwnText

public Elements getElementsContainingOwnText(String searchText)

Find elements that directly contain the specified string. The search is case insensitive. The text must appear directly in the element, not in any of its descendants.

Parameters:

searchText - to look for in the element's own text

Returns:

elements that contain the string, case insensitive.

See Also:

ownText()

getElementsMatchingText

public Elements getElementsMatchingText(Pattern pattern)

Find elements whose text matches the supplied regular expression.

Parameters:

pattern - regular expression to match text against

Returns:

elements matching the supplied regular expression.

See Also:

text()

getElementsMatchingText

public Elements getElementsMatchingText(String regex)

Find elements whose text matches the supplied regular expression.

Parameters:

regex - regular expression to match text against. You can use embedded flags (such as (?i) and (?m) to control regex options.

Returns:

elements matching the supplied regular expression.

See Also:

text()

getElementsMatchingOwnText

public Elements getElementsMatchingOwnText(Pattern pattern)

Find elements whose own text matches the supplied regular expression.

Parameters:

pattern - regular expression to match text against

Returns:

elements matching the supplied regular expression.

See Also:

ownText()

getElementsMatchingOwnText

public Elements getElementsMatchingOwnText(String regex)

Find elements whose text matches the supplied regular expression.

Parameters:

regex - regular expression to match text against. You can use embedded flags (such as (?i) and (?m) to control regex options.

Returns:

elements matching the supplied regular expression.

See Also:

ownText()

getAllElements

public Elements getAllElements()

Find all elements under this element (including self, and children of children).

Returns:

all elements

text

public String text()

Gets the combined text of this element and all its children.

For example, given HTML <p>Hello <b>there</b> now!</p>, p.text() returns "Hello there now!"

Returns:

unencoded text, or empty string if none.

See Also:

ownText()

ownText

public String ownText()

Gets the text owned by this element only; does not get the combined text of all children.

For example, given HTML <p>Hello <b>there</b> now!</p>, p.ownText() returns "Hello now!", whereas p.text() returns "Hello there now!". Note that the text within the b element is not returned, as it is not a direct child of the p element.

Returns:

unencoded text, or empty string if none.

See Also:

text()

text

public Element text(String text)

Set the text of this element. Any existing contents (text or elements) will be cleared

Parameters:

text - unencoded text

Returns:

this element

hasText

public boolean hasText()

Test if this element has any text content (that is not just whitespace).

Returns:

true if element has non-blank text content.

data

public String data()

Get the combined data of this element. Data is e.g. the inside of a script tag.

Returns:

the data, or empty string if none

className

public String className()

Gets the literal value of this element's "class" attribute, which may include multiple class names, space separated. (E.g. on <div class="header gray"> returns, "header gray")

Returns:

The literal class attribute, or empty string if no class attribute set.

classNames

public Set<String> classNames()

Get all of the element's class names. E.g. on element <div class="header gray">}, returns a set of two elements "header", "gray". Note that modifications to this set are not pushed to the backing class attribute; use the classNames(java.util.Set) method to persist them.

Returns:

set of classnames, empty if no class attribute

classNames

public Element classNames(Set<String> classNames)

Set the element's class attribute to the supplied class names.

Parameters:

classNames - set of classes

Returns:

this element, for chaining

hasClass

public boolean hasClass(String className)

Tests if this element has a class.

Parameters:

className - name of class to check for

Returns:

true if it does, false if not

addClass

public Element addClass(String className)

Add a class name to this element's class attribute.

Parameters:

className - class name to add

Returns:

this element

removeClass

public Element removeClass(String className)

Remove a class name from this element's class attribute.

Parameters:

className - class name to remove

Returns:

this element

toggleClass

public Element toggleClass(String className)

Toggle a class name on this element's class attribute: if present, remove it; otherwise add it.

Parameters:

className - class name to toggle

Returns:

this element

val

public String val()

Get the value of a form element (input, textarea, etc).

Returns:

the value of the form element, or empty string if not set.

val

public Element val(String value)

Set the value of a form element (input, textarea, etc).

Parameters:

value - value to set

Returns:

this element (for chaining)

html

public String html()

Retrieves the element's inner HTML. E.g. on a <div> with one empty <p>, would return <p></p>. (Whereas Node.outerHtml() would return <div><p></p></div>.)

Returns:

String of HTML.

See Also:

Node.outerHtml()

html

public Element html(String html)

Set this element's inner HTML. Clears the existing HTML first.

Parameters:

html - HTML to parse and set into this element

Returns:

this element

See Also:

append(String)

toString

public String toString()

Overrides:

toString in class Node

equals

public boolean equals(Object o)

Overrides:

equals in class Node

hashCode

public int hashCode()

Overrides:

hashCode in class Node