Class Element
- java.lang.Object
-
- org.jsoup.nodes.Node
-
- org.jsoup.nodes.Element
-
- All Implemented Interfaces:
java.lang.Cloneable
- Direct Known Subclasses:
Document
,FormElement
,PseudoTextElement
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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Element.NodeList
-
Field Summary
Fields Modifier and Type Field Description private Attributes
attributes
private java.lang.String
baseUri
(package private) java.util.List<Node>
childNodes
private static java.util.regex.Pattern
classSplit
private static java.util.List<Node>
EMPTY_NODES
private java.lang.ref.WeakReference<java.util.List<Element>>
shadowChildrenRef
private Tag
tag
-
Fields inherited from class org.jsoup.nodes.Node
EmptyString, parentNode, siblingIndex
-
-
Constructor Summary
Constructors Constructor Description Element(java.lang.String tag)
Create a new, standalone element.Element(Tag tag, java.lang.String baseUri)
Create a new Element from a tag and a base URI.Element(Tag tag, java.lang.String baseUri, Attributes attributes)
Create a new, standalone Element.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private static void
accumulateParents(Element el, Elements parents)
Element
addClass(java.lang.String className)
Add a class name to this element'sclass
attribute.Element
after(java.lang.String html)
Insert the specified HTML into the DOM after this element (as a following sibling).Element
after(Node node)
Insert the specified node into the DOM after this node (as a following sibling).Element
append(java.lang.String html)
Add inner HTML to this element.Element
appendChild(Node child)
Add a node child node to this element.Element
appendElement(java.lang.String tagName)
Create a new element by tag name, and add it as the last child.private static void
appendNormalisedText(java.lang.StringBuilder accum, TextNode textNode)
Element
appendText(java.lang.String text)
Create and append a new TextNode to this element.Element
appendTo(Element parent)
Add this element to the supplied parent element, as its next child.private static void
appendWhitespaceIfBr(Element element, java.lang.StringBuilder accum)
Element
attr(java.lang.String attributeKey, boolean attributeValue)
Set a boolean attribute value on this element.Element
attr(java.lang.String attributeKey, java.lang.String attributeValue)
Set an attribute value on this element.Attributes
attributes()
Get all of the element's attributes.java.lang.String
baseUri()
Get the base URI of this node.Element
before(java.lang.String html)
Insert the specified HTML into the DOM before this element (as a preceding sibling).Element
before(Node node)
Insert the specified node into the DOM before this node (as a preceding sibling).Element
child(int index)
Get a child element of this element, by its 0-based index number.private java.util.List<Element>
childElementsList()
Maintains a shadow copy of this element's child elements.int
childNodeSize()
Get the number of child nodes that this node holds.Elements
children()
Get this element's child elements.java.lang.String
className()
Gets the literal value of this element's "class" attribute, which may include multiple class names, space separated.java.util.Set<java.lang.String>
classNames()
Get all of the element's class names.Element
classNames(java.util.Set<java.lang.String> classNames)
Set the element'sclass
attribute to the supplied class names.Element
clone()
Create a stand-alone, deep copy of this node, and all of its children.java.lang.String
cssSelector()
Get a CSS selector that will uniquely select this element.java.lang.String
data()
Get the combined data of this element.java.util.List<DataNode>
dataNodes()
Get this element's child data nodes.java.util.Map<java.lang.String,java.lang.String>
dataset()
Get this element's HTML5 custom data attributes.protected Element
doClone(Node parent)
protected void
doSetBaseUri(java.lang.String baseUri)
Set the baseUri for just this node (not its descendants), if this Node tracks base URIs.int
elementSiblingIndex()
Get the list index of this element in its element sibling list.Element
empty()
Remove all of the element's child nodes.protected java.util.List<Node>
ensureChildNodes()
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(java.lang.String id)
Find an element by ID, including or under this element.Elements
getElementsByAttribute(java.lang.String key)
Find elements that have a named attribute set.Elements
getElementsByAttributeStarting(java.lang.String keyPrefix)
Find elements that have an attribute name starting with the supplied prefix.Elements
getElementsByAttributeValue(java.lang.String key, java.lang.String value)
Find elements that have an attribute with the specific value.Elements
getElementsByAttributeValueContaining(java.lang.String key, java.lang.String match)
Find elements that have attributes whose value contains the match string.Elements
getElementsByAttributeValueEnding(java.lang.String key, java.lang.String valueSuffix)
Find elements that have attributes that end with the value suffix.Elements
getElementsByAttributeValueMatching(java.lang.String key, java.lang.String regex)
Find elements that have attributes whose values match the supplied regular expression.Elements
getElementsByAttributeValueMatching(java.lang.String key, java.util.regex.Pattern pattern)
Find elements that have attributes whose values match the supplied regular expression.Elements
getElementsByAttributeValueNot(java.lang.String key, java.lang.String value)
Find elements that either do not have this attribute, or have it with a different value.Elements
getElementsByAttributeValueStarting(java.lang.String key, java.lang.String valuePrefix)
Find elements that have attributes that start with the value prefix.Elements
getElementsByClass(java.lang.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(java.lang.String tagName)
Finds elements, including and recursively under this element, with the specified tag name.Elements
getElementsContainingOwnText(java.lang.String searchText)
Find elements that directly contain the specified string.Elements
getElementsContainingText(java.lang.String searchText)
Find elements that contain the specified string.Elements
getElementsMatchingOwnText(java.lang.String regex)
Find elements whose text matches the supplied regular expression.Elements
getElementsMatchingOwnText(java.util.regex.Pattern pattern)
Find elements whose own text matches the supplied regular expression.Elements
getElementsMatchingText(java.lang.String regex)
Find elements whose text matches the supplied regular expression.Elements
getElementsMatchingText(java.util.regex.Pattern pattern)
Find elements whose text matches the supplied regular expression.protected boolean
hasAttributes()
Check if this Node has an actual Attributes object.boolean
hasClass(java.lang.String className)
Tests if this element has a class.boolean
hasText()
Test if this element has any text content (that is not just whitespace).java.lang.String
html()
Retrieves the element's inner HTML.Element
html(java.lang.String html)
Set this element's inner HTML.<T extends java.lang.Appendable>
Thtml(T appendable)
Write this node and its children to the givenAppendable
.java.lang.String
id()
Get theid
attribute of this element.private static <E extends Element>
intindexInList(Element search, java.util.List<E> elements)
Element
insertChildren(int index, java.util.Collection<? extends Node> children)
Inserts the given child nodes into this element at the specified index.Element
insertChildren(int index, Node... children)
Inserts the given child nodes into this element at the specified index.boolean
is(java.lang.String cssQuery)
Check if this element matches the givenSelector
CSS query.boolean
is(Evaluator evaluator)
Check if this element matches the given evaluator.boolean
isBlock()
Test if this element is a block-level element.Element
lastElementSibling()
Gets the last element sibling of this elementElement
nextElementSibling()
Gets the next sibling element of this element.Elements
nextElementSiblings()
Get each of the sibling elements that come after this element.private Elements
nextElementSiblings(boolean next)
(package private) void
nodelistChanged()
Clears the cached shadow child elements.java.lang.String
nodeName()
Get the node name of this node.java.lang.String
normalName()
Get the normalized name of this Element's tag.(package private) void
outerHtmlHead(java.lang.Appendable accum, int depth, Document.OutputSettings out)
Get the outer HTML of this node.(package private) void
outerHtmlTail(java.lang.Appendable accum, int depth, Document.OutputSettings out)
java.lang.String
ownText()
Gets the text owned by this element only; does not get the combined text of all children.private void
ownText(java.lang.StringBuilder accum)
Element
parent()
Gets this node's parent node.Elements
parents()
Get this element's parent and ancestors, up to the document root.Element
prepend(java.lang.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(java.lang.String tagName)
Create a new element by tag name, and add it as the first child.Element
prependText(java.lang.String text)
Create and prepend a new TextNode to this element.(package private) static boolean
preserveWhitespace(Node node)
Element
previousElementSibling()
Gets the previous element sibling of this element.Elements
previousElementSiblings()
Get each of the element siblings before this element.Element
removeClass(java.lang.String className)
Remove a class name from this element'sclass
attribute.Elements
select(java.lang.String cssQuery)
Find elements that match theSelector
CSS query, with this element as the starting context.Element
selectFirst(java.lang.String cssQuery)
Find the first Element that matches theSelector
CSS query, with this element as the starting context.Element
shallowClone()
Create a stand-alone, shallow copy of this node.Elements
siblingElements()
Get sibling elements.Tag
tag()
Get the Tag for this element.java.lang.String
tagName()
Get the name of the tag for this element.Element
tagName(java.lang.String tagName)
Change the tag of this element.java.lang.String
text()
Gets the combined text of this element and all its children.Element
text(java.lang.String text)
Set the text of this element.java.util.List<TextNode>
textNodes()
Get this element's child text nodes.Element
toggleClass(java.lang.String className)
Toggle a class name on this element'sclass
attribute: if present, remove it; otherwise add it.java.lang.String
val()
Get the value of a form element (input, textarea, etc).Element
val(java.lang.String value)
Set the value of a form element (input, textarea, etc).java.lang.String
wholeText()
Get the (unencoded) text of all children of this element, including any newlines and spaces present in the original.Element
wrap(java.lang.String html)
Wrap the supplied HTML around this element.-
Methods inherited from class org.jsoup.nodes.Node
absUrl, addChildren, addChildren, attr, childNode, childNodes, childNodesAsArray, childNodesCopy, clearAttributes, equals, filter, hasAttr, hasParent, hasSameValue, indent, nextSibling, outerHtml, outerHtml, ownerDocument, parentNode, previousSibling, remove, removeAttr, removeChild, reparentChild, replaceChild, replaceWith, root, setBaseUri, setParentNode, setSiblingIndex, siblingIndex, siblingNodes, toString, traverse, unwrap
-
-
-
-
Field Detail
-
EMPTY_NODES
private static final java.util.List<Node> EMPTY_NODES
-
classSplit
private static final java.util.regex.Pattern classSplit
-
tag
private Tag tag
-
shadowChildrenRef
private java.lang.ref.WeakReference<java.util.List<Element>> shadowChildrenRef
-
childNodes
java.util.List<Node> childNodes
-
attributes
private Attributes attributes
-
baseUri
private java.lang.String baseUri
-
-
Constructor Detail
-
Element
public Element(java.lang.String tag)
Create a new, standalone element.- Parameters:
tag
- tag name
-
Element
public Element(Tag tag, java.lang.String baseUri, Attributes attributes)
Create a new, standalone Element. (Standalone in that is has no parent.)- Parameters:
tag
- tag of this elementbaseUri
- the base URIattributes
- initial attributes- See Also:
appendChild(Node)
,appendElement(String)
-
Element
public Element(Tag tag, java.lang.String baseUri)
Create a new Element from a tag and a base URI.- Parameters:
tag
- element tagbaseUri
- 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, ParseSettings)
-
-
Method Detail
-
ensureChildNodes
protected java.util.List<Node> ensureChildNodes()
- Specified by:
ensureChildNodes
in classNode
-
hasAttributes
protected boolean hasAttributes()
Description copied from class:Node
Check if this Node has an actual Attributes object.- Specified by:
hasAttributes
in classNode
-
attributes
public Attributes attributes()
Description copied from class:Node
Get all of the element's attributes.- Specified by:
attributes
in classNode
- Returns:
- attributes (which implements iterable, in same order as presented in original HTML).
-
baseUri
public java.lang.String baseUri()
Description copied from class:Node
Get the base URI of this node.
-
doSetBaseUri
protected void doSetBaseUri(java.lang.String baseUri)
Description copied from class:Node
Set the baseUri for just this node (not its descendants), if this Node tracks base URIs.- Specified by:
doSetBaseUri
in classNode
- Parameters:
baseUri
- new URI
-
childNodeSize
public int childNodeSize()
Description copied from class:Node
Get the number of child nodes that this node holds.- Specified by:
childNodeSize
in classNode
- Returns:
- the number of child nodes that this node holds.
-
nodeName
public java.lang.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).
-
tagName
public java.lang.String tagName()
Get the name of the tag for this element. E.g.div
. If you are usingcase preserving parsing
, this will return the source's original case.- Returns:
- the tag name
-
normalName
public java.lang.String normalName()
Get the normalized name of this Element's tag. This will always be the lowercased version of the tag, regardless of the tag case preserving setting of the parser.- Returns:
-
tagName
public Element tagName(java.lang.String tagName)
Change the tag of this element. For example, convert a<span>
to a<div>
withel.tagName("div");
.- Parameters:
tagName
- new tag name for this element- Returns:
- this element, for chaining
-
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 java.lang.String id()
Get theid
attribute of this element.- Returns:
- The id attribute, if present, or an empty string if not.
-
attr
public Element attr(java.lang.String attributeKey, java.lang.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.
-
attr
public Element attr(java.lang.String attributeKey, boolean attributeValue)
Set a boolean attribute value on this element. Setting totrue
sets the attribute value to "" and marks the attribute as boolean so no value is written out. Setting tofalse
removes the attribute with the same key if it exists.- Parameters:
attributeKey
- the attribute keyattributeValue
- the attribute value- Returns:
- this element
-
dataset
public java.util.Map<java.lang.String,java.lang.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 datasetpackage=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.
-
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, otherwise throws an
IndexOutOfBoundsException
- 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()
-
childElementsList
private java.util.List<Element> childElementsList()
Maintains a shadow copy of this element's child elements. If the nodelist is changed, this cache is invalidated. TODO - think about pulling this out as a helper as there are other shadow lists (like in Attributes) kept around.- Returns:
- a list of child elements
-
nodelistChanged
void nodelistChanged()
Clears the cached shadow child elements.- Overrides:
nodelistChanged
in classNode
-
textNodes
public java.util.List<TextNode> textNodes()
Get this element's child text nodes. The list is unmodifiable but the text nodes may be manipulated.This is effectively a filter on
Node.childNodes()
to get Text nodes.- Returns:
- child text nodes. If this element has no text nodes, returns an
empty list.
For example, with the input HTML:
<p>One <span>Two</span> Three <br> Four</p>
with thep
element selected:p.text()
="One Two Three Four"
p.ownText()
="One Three Four"
p.children()
=Elements[<span>, <br>]
p.childNodes()
=List<Node>["One ", <span>, " Three ", <br>, " Four"]
p.textNodes()
=List<TextNode>["One ", " Three ", " Four"]
-
dataNodes
public java.util.List<DataNode> dataNodes()
Get this element's child data nodes. The list is unmodifiable but the data nodes may be manipulated.This is effectively a filter on
Node.childNodes()
to get Data nodes.- Returns:
- child data nodes. If this element has no data nodes, returns an empty list.
- See Also:
data()
-
select
public Elements select(java.lang.String cssQuery)
Find elements that match theSelector
CSS 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 withhref
attributes)el.select("a[href*=example.com]")
- finds links pointing to example.com (loosely)
See the query syntax documentation in
Selector
.- Parameters:
cssQuery
- aSelector
CSS-like query- Returns:
- elements that match the query (empty if none match)
- Throws:
Selector.SelectorParseException
- (unchecked) on an invalid CSS query.- See Also:
Selector
-
selectFirst
public Element selectFirst(java.lang.String cssQuery)
Find the first Element that matches theSelector
CSS query, with this element as the starting context.This is effectively the same as calling
element.select(query).first()
, but is more efficient as query execution stops on the first hit.- Parameters:
cssQuery
- cssQuery aSelector
CSS-like query- Returns:
- the first matching element, or
null
if there is no match.
-
is
public boolean is(java.lang.String cssQuery)
Check if this element matches the givenSelector
CSS query.- Parameters:
cssQuery
- aSelector
CSS query- Returns:
- if this element matches the query
-
is
public boolean is(Evaluator evaluator)
Check if this element matches the given evaluator.- Parameters:
evaluator
- an element evaluator- Returns:
- if this element matches
-
appendChild
public Element appendChild(Node child)
Add a node child node to this element.- Parameters:
child
- node to add.- Returns:
- this element, so that you can add more child nodes or elements.
-
appendTo
public Element appendTo(Element parent)
Add this element to the supplied parent element, as its next child.- Parameters:
parent
- element to which this element will be appended- Returns:
- this element, so that you can continue modifying the element
-
prependChild
public Element prependChild(Node child)
Add a node to the start of this element's children.- Parameters:
child
- node to add.- Returns:
- this element, so that you can add more child nodes or elements.
-
insertChildren
public Element insertChildren(int index, java.util.Collection<? extends Node> children)
Inserts the given child nodes into this element at the specified index. Current nodes will be shifted to the right. The inserted nodes will be moved from their current parent. To prevent moving, copy the nodes first.- Parameters:
index
- 0-based index to insert children at. Specify0
to insert at the start,-1
at the endchildren
- child nodes to insert- Returns:
- this element, for chaining.
-
insertChildren
public Element insertChildren(int index, Node... children)
Inserts the given child nodes into this element at the specified index. Current nodes will be shifted to the right. The inserted nodes will be moved from their current parent. To prevent moving, copy the nodes first.- Parameters:
index
- 0-based index to insert children at. Specify0
to insert at the start,-1
at the endchildren
- child nodes to insert- Returns:
- this element, for chaining.
-
appendElement
public Element appendElement(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String html)
Insert the specified HTML into the DOM before this element (as a preceding sibling).- Overrides:
before
in classNode
- Parameters:
html
- HTML to add before this element- Returns:
- this element, for chaining
- See Also:
after(String)
-
before
public Element before(Node node)
Insert the specified node into the DOM before this node (as a preceding sibling).- Overrides:
before
in classNode
- Parameters:
node
- to add before this element- Returns:
- this Element, for chaining
- See Also:
after(Node)
-
after
public Element after(java.lang.String html)
Insert the specified HTML into the DOM after this element (as a following sibling).- Overrides:
after
in classNode
- Parameters:
html
- HTML to add after this element- Returns:
- this element, for chaining
- See Also:
before(String)
-
after
public Element after(Node node)
Insert the specified node into the DOM after this node (as a following sibling).- Overrides:
after
in classNode
- Parameters:
node
- to add after this element- Returns:
- this element, for chaining
- See Also:
before(Node)
-
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(java.lang.String html)
Wrap the supplied HTML around this element.
-
cssSelector
public java.lang.String cssSelector()
Get a CSS selector that will uniquely select this element.If the element has an ID, returns #id; otherwise returns the parent (if any) CSS selector, followed by '>', followed by a unique selector for the element (tag.class.class:nth-child(n)).
- Returns:
- the CSS Path that can be used to retrieve the element in a selector.
-
siblingElements
public Elements siblingElements()
Get sibling elements. If the element has no sibling elements, returns an empty list. An element is not a sibling of itself, so will not be included in the returned list.- Returns:
- sibling elements
-
nextElementSibling
public Element nextElementSibling()
Gets the next sibling element of this element. E.g., if adiv
contains twop
s, thenextElementSibling
of the firstp
is the secondp
.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()
-
nextElementSiblings
public Elements nextElementSiblings()
Get each of the sibling elements that come after this element.- Returns:
- each of the element siblings after this element, or an empty list if there are no next sibling elements
-
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()
-
previousElementSiblings
public Elements previousElementSiblings()
Get each of the element siblings before this element.- Returns:
- the previous element siblings, or an empty list if there are none.
-
nextElementSiblings
private Elements nextElementSiblings(boolean next)
-
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 int 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)
-
indexInList
private static <E extends Element> int indexInList(Element search, java.util.List<E> elements)
-
getElementsByTag
public Elements getElementsByTag(java.lang.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(java.lang.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(java.lang.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 withel.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(java.lang.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(java.lang.String keyPrefix)
Find elements that have an attribute name starting with the supplied prefix. Usedata-
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(java.lang.String key, java.lang.String value)
Find elements that have an attribute with the specific value. Case insensitive.- Parameters:
key
- name of the attributevalue
- value of the attribute- Returns:
- elements that have this attribute with this value, empty if none
-
getElementsByAttributeValueNot
public Elements getElementsByAttributeValueNot(java.lang.String key, java.lang.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 attributevalue
- value of the attribute- Returns:
- elements that do not have a matching attribute
-
getElementsByAttributeValueStarting
public Elements getElementsByAttributeValueStarting(java.lang.String key, java.lang.String valuePrefix)
Find elements that have attributes that start with the value prefix. Case insensitive.- Parameters:
key
- name of the attributevaluePrefix
- start of attribute value- Returns:
- elements that have attributes that start with the value prefix
-
getElementsByAttributeValueEnding
public Elements getElementsByAttributeValueEnding(java.lang.String key, java.lang.String valueSuffix)
Find elements that have attributes that end with the value suffix. Case insensitive.- Parameters:
key
- name of the attributevalueSuffix
- end of the attribute value- Returns:
- elements that have attributes that end with the value suffix
-
getElementsByAttributeValueContaining
public Elements getElementsByAttributeValueContaining(java.lang.String key, java.lang.String match)
Find elements that have attributes whose value contains the match string. Case insensitive.- Parameters:
key
- name of the attributematch
- substring of value to search for- Returns:
- elements that have attributes containing this text
-
getElementsByAttributeValueMatching
public Elements getElementsByAttributeValueMatching(java.lang.String key, java.util.regex.Pattern pattern)
Find elements that have attributes whose values match the supplied regular expression.- Parameters:
key
- name of the attributepattern
- compiled regular expression to match against attribute values- Returns:
- elements that have attributes matching this regular expression
-
getElementsByAttributeValueMatching
public Elements getElementsByAttributeValueMatching(java.lang.String key, java.lang.String regex)
Find elements that have attributes whose values match the supplied regular expression.- Parameters:
key
- name of the attributeregex
- regular expression to match against 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(java.lang.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(java.lang.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(java.util.regex.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(java.lang.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(java.util.regex.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(java.lang.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 java.lang.String text()
Gets the combined text of this element and all its children. Whitespace is normalized and trimmed.For example, given HTML
<p>Hello <b>there</b> now! </p>
,p.text()
returns"Hello there now!"
- Returns:
- unencoded, normalized text, or empty string if none.
- See Also:
if you don't want the text to be normalized.
,ownText()
,textNodes()
-
wholeText
public java.lang.String wholeText()
Get the (unencoded) text of all children of this element, including any newlines and spaces present in the original.- Returns:
- unencoded, un-normalized text
- See Also:
text()
-
ownText
public java.lang.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!"
, whereasp.text()
returns"Hello there now!"
. Note that the text within theb
element is not returned, as it is not a direct child of thep
element.- Returns:
- unencoded text, or empty string if none.
- See Also:
text()
,textNodes()
-
ownText
private void ownText(java.lang.StringBuilder accum)
-
appendNormalisedText
private static void appendNormalisedText(java.lang.StringBuilder accum, TextNode textNode)
-
appendWhitespaceIfBr
private static void appendWhitespaceIfBr(Element element, java.lang.StringBuilder accum)
-
preserveWhitespace
static boolean preserveWhitespace(Node node)
-
text
public Element text(java.lang.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 java.lang.String data()
Get the combined data of this element. Data is e.g. the inside of ascript
tag. Note that data is NOT the text of the element. Usetext()
to get the text that would be visible to a user, anddata()
for the contents of scripts, comments, CSS styles, etc.- Returns:
- the data, or empty string if none
- See Also:
dataNodes()
-
className
public java.lang.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 java.util.Set<java.lang.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 backingclass
attribute; use theclassNames(java.util.Set)
method to persist them.- Returns:
- set of classnames, empty if no class attribute
-
classNames
public Element classNames(java.util.Set<java.lang.String> classNames)
Set the element'sclass
attribute to the supplied class names.- Parameters:
classNames
- set of classes- Returns:
- this element, for chaining
-
hasClass
public boolean hasClass(java.lang.String className)
Tests if this element has a class. Case insensitive.- Parameters:
className
- name of class to check for- Returns:
- true if it does, false if not
-
addClass
public Element addClass(java.lang.String className)
Add a class name to this element'sclass
attribute.- Parameters:
className
- class name to add- Returns:
- this element
-
removeClass
public Element removeClass(java.lang.String className)
Remove a class name from this element'sclass
attribute.- Parameters:
className
- class name to remove- Returns:
- this element
-
toggleClass
public Element toggleClass(java.lang.String className)
Toggle a class name on this element'sclass
attribute: if present, remove it; otherwise add it.- Parameters:
className
- class name to toggle- Returns:
- this element
-
val
public java.lang.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(java.lang.String value)
Set the value of a form element (input, textarea, etc).- Parameters:
value
- value to set- Returns:
- this element (for chaining)
-
outerHtmlHead
void outerHtmlHead(java.lang.Appendable accum, int depth, Document.OutputSettings out) throws java.io.IOException
Description copied from class:Node
Get the outer HTML of this node.- Specified by:
outerHtmlHead
in classNode
- Parameters:
accum
- accumulator to place HTML into- Throws:
java.io.IOException
- if appending to the given accumulator fails.
-
outerHtmlTail
void outerHtmlTail(java.lang.Appendable accum, int depth, Document.OutputSettings out) throws java.io.IOException
- Specified by:
outerHtmlTail
in classNode
- Throws:
java.io.IOException
-
html
public java.lang.String html()
Retrieves the element's inner HTML. E.g. on a<div>
with one empty<p>
, would return<p></p>
. (WhereasNode.outerHtml()
would return<div><p></p></div>
.)- Returns:
- String of HTML.
- See Also:
Node.outerHtml()
-
html
public <T extends java.lang.Appendable> T html(T appendable)
Description copied from class:Node
Write this node and its children to the givenAppendable
.
-
html
public Element html(java.lang.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)
-
clone
public Element clone()
Description copied from class:Node
Create a stand-alone, deep copy of this node, and all of its children. The cloned node will have no siblings or parent node. As a stand-alone object, any changes made to the clone or any of its children will not impact the original node.The cloned node may be adopted into another Document or node structure using
appendChild(Node)
.- Overrides:
clone
in classNode
- Returns:
- a stand-alone cloned node, including clones of any children
- See Also:
Node.shallowClone()
-
shallowClone
public Element shallowClone()
Description copied from class:Node
Create a stand-alone, shallow copy of this node. None of its children (if any) will be cloned, and it will have no parent or sibling nodes.- Overrides:
shallowClone
in classNode
- Returns:
- a single independent copy of this node
- See Also:
Node.clone()
-
-