Class Element
A HTML element consists of a tag name, attributes, and child nodes (including text nodes and other elements).
Inherited Members
Namespace: Supremes.Nodes
Assembly: Supremes.dll
Syntax
public class Element : Node
Remarks
From an Element, you can extract data, traverse the node graph, and manipulate the HTML.
Properties
Children
Get this element's child elements.
Declaration
public Elements Children { get; }
Property Value
Type | Description |
---|---|
Elements | child elements. If this element has no children, returns an empty list. |
Remarks
This is effectively a filter on ChildNodes to get Element nodes.
See Also
ClassName
Gets the literal value of this element's "class" attribute, which may include multiple class names, space separated.
Declaration
public string ClassName { get; }
Property Value
Type | Description |
---|---|
System.String | The literal class attribute, or empty string if no class attribute set. |
Remarks
(E.g. on <div class="header gray">
returns,
"header gray
")
ClassNames
Get or Set all of the element's class names.
Declaration
public ICollection<string> ClassNames { get; set; }
Property Value
Type | Description |
---|---|
ICollection<System.String> | the new set of classes |
Remarks
E.g. on element
<div class="header gray">
,
this property 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
method to persist them.
if you want to use fluent API, write using Supremes.Fluent;
.
See Also
CssSelector
Get a CSS selector that will uniquely select this element.
Declaration
public string CssSelector { get; }
Property Value
Type | Description |
---|---|
System.String | the CSS Path that can be used to retrieve the element in a selector. |
Remarks
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)).
Data
Get the combined data of this element.
Declaration
public string Data { get; }
Property Value
Type | Description |
---|---|
System.String | the data, or empty string if none |
Remarks
Data is e.g. the inside of a
script
tag.
See Also
DataNodes
Get this element's child data nodes.
Declaration
public IReadOnlyList<DataNode> DataNodes { get; }
Property Value
Type | Description |
---|---|
IReadOnlyList<DataNode> | child data nodes. If this element has no data nodes, returns an empty list. |
Remarks
The list is unmodifiable but the data nodes may be manipulated.
This is effectively a filter on ChildNodes to get Data nodes.
See Also
Dataset
Get this element's HTML5 custom data attributes.
Declaration
public IDictionary<string, string> Dataset { get; }
Property Value
Type | Description |
---|---|
IDictionary<System.String, System.String> | a map of
|
Remarks
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.
ElementSiblingIndex
Get the list index of this element in its element sibling list.
Declaration
public int ElementSiblingIndex { get; }
Property Value
Type | Description |
---|---|
System.Int32 | position in element sibling list |
Remarks
I.e. if this is the first element sibling, returns 0.
FirstElementSibling
Gets the first element sibling of this element.
Declaration
public Element FirstElementSibling { get; }
Property Value
Type | Description |
---|---|
Element | the first sibling that is an element (aka the parent's first element child) |
HasText
Test if this element has any text content (that is not just whitespace).
Declaration
public bool HasText { get; }
Property Value
Type | Description |
---|---|
System.Boolean | true if element has non-blank text content. |
Html
Get Or Set the element's inner HTML.
Declaration
public string Html { get; set; }
Property Value
Type | Description |
---|---|
System.String | HTML to parse and set into this element |
Remarks
when get on a <div>
with one empty <p>
,
would return <p></p>
.
(Whereas
OuterHtml
would return
<div><p></p></div>
.)
when set, clears the existing HTML first.
if you want to use fluent API, write using Supremes.Fluent;
.
See Also
Id
Get the id
attribute of this element.
Declaration
public string Id { get; }
Property Value
Type | Description |
---|---|
System.String | The id attribute, if present, or an empty string if not. |
IsBlock
Test if this element is a block-level element.
Declaration
public bool IsBlock { get; }
Property Value
Type | Description |
---|---|
System.Boolean | true if block, false if not (and thus inline) |
Remarks
(E.g.
<div> == true
or an inline element
<p> == false
).
LastElementSibling
Gets the last element sibling of this element
Declaration
public Element LastElementSibling { get; }
Property Value
Type | Description |
---|---|
Element | the last sibling that is an element (aka the parent's last element child) |
NextElementSibling
Gets the next sibling element of this element.
Declaration
public Element NextElementSibling { get; }
Property Value
Type | Description |
---|---|
Element | the next element, or null if there is no next element |
Remarks
E.g., if a
div
contains two
p
s,
the
NextElementSibling
of the first
p
is the second
p
.
This is similar to NextSibling , but specifically finds only Elements
See Also
OwnText
Gets the text owned by this element only; does not get the combined text of all children.
Declaration
public string OwnText { get; }
Property Value
Type | Description |
---|---|
System.String | unencoded text, or empty string if none. |
Remarks
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.
See Also
Parent
Gets this element's parent element.
Declaration
public Element Parent { get; }
Property Value
Type | Description |
---|---|
Element |
Parents
Get this element's parent and ancestors, up to the document root.
Declaration
public Elements Parents { get; }
Property Value
Type | Description |
---|---|
Elements | this element's stack of parents, closest first. |
PreviousElementSibling
Gets the previous element sibling of this element.
Declaration
public Element PreviousElementSibling { get; }
Property Value
Type | Description |
---|---|
Element | the previous element, or null if there is no previous element |
See Also
SiblingElements
Get sibling elements.
Declaration
public Elements SiblingElements { get; }
Property Value
Type | Description |
---|---|
Elements | sibling elements |
Remarks
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.
Tag
Get the Tag for this element.
Declaration
public Tag Tag { get; }
Property Value
Type | Description |
---|---|
Tag | the tag object |
TagName
Get or Set the name of the tag for this element.
Declaration
public string TagName { get; set; }
Property Value
Type | Description |
---|---|
System.String | the new tag name |
Remarks
E.g. div
For example, convert a <span>
to a <div>
with el.TagName = "div";
.
if you want to use fluent API, write using Supremes.Fluent;
.
See Also
Text
Get or Set the combined text of this element and all its children.
Declaration
public virtual string Text { get; set; }
Property Value
Type | Description |
---|---|
System.String | unencoded text |
Remarks
when get, whitespace is normalized and trimmed.
For example, given HTML
<p>Hello <b>there</b> now! </p>
,
p.Text
returns "Hello there now!"
when set, any existing contents (text or elements) will be cleared.
See Also
TextNodes
Get this element's child text nodes.
Declaration
public IReadOnlyList<TextNode> TextNodes { get; }
Property Value
Type | Description |
---|---|
IReadOnlyList<TextNode> | child text nodes. If this element has no text nodes, returns an empty list.
For example, with the input HTML:
|
Remarks
The list is unmodifiable but the text nodes may be manipulated.
This is effectively a filter on ChildNodes to get Text nodes.
Val
Get or Set the value of a form element (input, textarea, etc).
Declaration
public string Val { get; set; }
Property Value
Type | Description |
---|---|
System.String | value to set |
Remarks
if you want to use fluent API, write using Supremes.Fluent;
.
See Also
Methods
AddClass(String)
Add a class name to this element's
class
attribute.
Declaration
public Element AddClass(string className)
Parameters
Type | Name | Description |
---|---|---|
System.String | className | class name to add |
Returns
Type | Description |
---|---|
Element | this element |
After(Node)
Insert the specified node into the DOM after this node (as a following sibling).
Declaration
public override Node After(Node node)
Parameters
Type | Name | Description |
---|---|---|
Node | node | to add after this element |
Returns
Type | Description |
---|---|
Node | this element, for chaining |
Overrides
See Also
After(String)
Insert the specified HTML into the DOM after this element (as a following sibling).
Declaration
public override Node After(string html)
Parameters
Type | Name | Description |
---|---|---|
System.String | html | HTML to add after this element |
Returns
Type | Description |
---|---|
Node | this element, for chaining |
Overrides
See Also
Append(String)
Add inner HTML to this element.
Declaration
public Element Append(string html)
Parameters
Type | Name | Description |
---|---|---|
System.String | html | HTML to add inside this element, after the existing HTML |
Returns
Type | Description |
---|---|
Element | this element |
Remarks
The supplied HTML will be parsed, and each node appended to the end of the children.
See Also
AppendChild(Node)
Add a node child node to this element.
Declaration
public Element AppendChild(Node child)
Parameters
Type | Name | Description |
---|---|---|
Node | child | node to add. |
Returns
Type | Description |
---|---|
Element | this element, so that you can add more child nodes or elements. |
AppendElement(String)
Create a new element by tag name, and add it as the last child.
Declaration
public Element AppendElement(string tagName)
Parameters
Type | Name | Description |
---|---|---|
System.String | tagName | the name of the tag (e.g.
|
Returns
Type | Description |
---|---|
Element | the new element, to allow you to add content to it, e.g.:
|
AppendText(String)
Create and append a new TextNode to this element.
Declaration
public Element AppendText(string text)
Parameters
Type | Name | Description |
---|---|---|
System.String | text | the unencoded text to add |
Returns
Type | Description |
---|---|
Element | this element |
Before(Node)
Insert the specified node into the DOM before this node (as a preceding sibling).
Declaration
public override Node Before(Node node)
Parameters
Type | Name | Description |
---|---|---|
Node | node | to add before this element |
Returns
Type | Description |
---|---|
Node | this Element, for chaining |
Overrides
See Also
Before(String)
Insert the specified HTML into the DOM before this element (as a preceding sibling).
Declaration
public override Node Before(string html)
Parameters
Type | Name | Description |
---|---|---|
System.String | html | HTML to add before this element |
Returns
Type | Description |
---|---|
Node | this element, for chaining |
Overrides
See Also
Child(Int32)
Get a child element of this element, by its 0-based index number.
Declaration
public Element Child(int index)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | index | the index number of the element to retrieve |
Returns
Type | Description |
---|---|
Element | the child element, if it exists, otherwise throws an
|
Remarks
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.
See Also
Empty()
Remove all of the element's child nodes.
Declaration
public Element Empty()
Returns
Type | Description |
---|---|
Element | this element |
Remarks
Any attributes are left as-is.
Equals(Object)
Compares two Element instances for equality.
Declaration
public override bool Equals(object o)
Parameters
Type | Name | Description |
---|---|---|
System.Object | o |
Returns
Type | Description |
---|---|
System.Boolean |
Overrides
GetAllElements()
Find all elements under this element (including self, and children of children).
Declaration
public Elements GetAllElements()
Returns
Type | Description |
---|---|
Elements | all elements |
GetElementById(String)
Find an element by ID, including or under this element.
Declaration
public Element GetElementById(string id)
Parameters
Type | Name | Description |
---|---|---|
System.String | id | The ID to search for. |
Returns
Type | Description |
---|---|
Element | The first matching element by ID, starting with this element, or null if none found. |
Remarks
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)
GetElementsByAttribute(String)
Find elements that have a named attribute set.
Declaration
public Elements GetElementsByAttribute(string key)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute, e.g.
|
Returns
Type | Description |
---|---|
Elements | elements that have this attribute, empty if none |
Remarks
Case insensitive.
GetElementsByAttributeStarting(String)
Find elements that have an attribute name starting with the supplied prefix.
Declaration
public Elements GetElementsByAttributeStarting(string keyPrefix)
Parameters
Type | Name | Description |
---|---|---|
System.String | keyPrefix | name prefix of the attribute e.g.
|
Returns
Type | Description |
---|---|
Elements | elements that have attribute names that start with with the prefix, empty if none. |
Remarks
Use
data-
to find elements
that have HTML5 datasets.
GetElementsByAttributeValue(String, String)
Find elements that have an attribute with the specific value.
Declaration
public Elements GetElementsByAttributeValue(string key, string value)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute |
System.String | value | value of the attribute |
Returns
Type | Description |
---|---|
Elements | elements that have this attribute with this value, empty if none |
Remarks
Case insensitive.
GetElementsByAttributeValueContaining(String, String)
Find elements that have attributes whose value contains the match string.
Declaration
public Elements GetElementsByAttributeValueContaining(string key, string match)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute |
System.String | match | substring of value to search for |
Returns
Type | Description |
---|---|
Elements | elements that have attributes containing this text |
Remarks
Case insensitive.
GetElementsByAttributeValueEnding(String, String)
Find elements that have attributes that end with the value suffix.
Declaration
public Elements GetElementsByAttributeValueEnding(string key, string valueSuffix)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute |
System.String | valueSuffix | end of the attribute value |
Returns
Type | Description |
---|---|
Elements | elements that have attributes that end with the value suffix |
Remarks
Case insensitive.
GetElementsByAttributeValueMatching(String, Regex)
Find elements that have attributes whose values match the supplied regular expression.
Declaration
public Elements GetElementsByAttributeValueMatching(string key, Regex pattern)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute |
Regex | pattern | compiled regular expression to match against attribute values |
Returns
Type | Description |
---|---|
Elements | elements that have attributes matching this regular expression |
GetElementsByAttributeValueMatching(String, String)
Find elements that have attributes whose values match the supplied regular expression.
Declaration
public Elements GetElementsByAttributeValueMatching(string key, string regex)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute |
System.String | regex | regular expression to match against attribute values. You can use embedded flags (such as (?i) and (?m) to control regex options. |
Returns
Type | Description |
---|---|
Elements | elements that have attributes matching this regular expression |
GetElementsByAttributeValueNot(String, String)
Find elements that either do not have this attribute, or have it with a different value.
Declaration
public Elements GetElementsByAttributeValueNot(string key, string value)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute |
System.String | value | value of the attribute |
Returns
Type | Description |
---|---|
Elements | elements that do not have a matching attribute |
Remarks
Case insensitive.
GetElementsByAttributeValueStarting(String, String)
Find elements that have attributes that start with the value prefix.
Declaration
public Elements GetElementsByAttributeValueStarting(string key, string valuePrefix)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | name of the attribute |
System.String | valuePrefix | start of attribute value |
Returns
Type | Description |
---|---|
Elements | elements that have attributes that start with the value prefix |
Remarks
Case insensitive.
GetElementsByClass(String)
Find elements that have this class, including or under this element.
Declaration
public Elements GetElementsByClass(string className)
Parameters
Type | Name | Description |
---|---|---|
System.String | className | the name of the class to search for. |
Returns
Type | Description |
---|---|
Elements | elements with the supplied class name, empty if none |
Remarks
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");
.
See Also
GetElementsByIndexEquals(Int32)
Find elements whose sibling index is equal to the supplied index.
Declaration
public Elements GetElementsByIndexEquals(int index)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | index | 0-based index |
Returns
Type | Description |
---|---|
Elements | elements equal to index |
GetElementsByIndexGreaterThan(Int32)
Find elements whose sibling index is greater than the supplied index.
Declaration
public Elements GetElementsByIndexGreaterThan(int index)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | index | 0-based index |
Returns
Type | Description |
---|---|
Elements | elements greater than index |
GetElementsByIndexLessThan(Int32)
Find elements whose sibling index is less than the supplied index.
Declaration
public Elements GetElementsByIndexLessThan(int index)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | index | 0-based index |
Returns
Type | Description |
---|---|
Elements | elements less than index |
GetElementsByTag(String)
Finds elements, including and recursively under this element, with the specified tag name.
Declaration
public Elements GetElementsByTag(string tagName)
Parameters
Type | Name | Description |
---|---|---|
System.String | tagName | The tag name to search for (case insensitively). |
Returns
Type | Description |
---|---|
Elements | a matching unmodifiable list of elements. Will be empty if this element and none of its children match. |
GetElementsContainingOwnText(String)
Find elements that directly contain the specified string.
Declaration
public Elements GetElementsContainingOwnText(string searchText)
Parameters
Type | Name | Description |
---|---|---|
System.String | searchText | to look for in the element's own text |
Returns
Type | Description |
---|---|
Elements | elements that contain the string, case insensitive. |
Remarks
The search is case insensitive. The text must appear directly in the element, not in any of its descendants.
See Also
GetElementsContainingText(String)
Find elements that contain the specified string.
Declaration
public Elements GetElementsContainingText(string searchText)
Parameters
Type | Name | Description |
---|---|---|
System.String | searchText | to look for in the element's text |
Returns
Type | Description |
---|---|
Elements | elements that contain the string, case insensitive. |
Remarks
The search is case insensitive. The text may appear directly in the element, or in any of its descendants.
See Also
GetElementsMatchingOwnText(Regex)
Find elements whose own text matches the supplied regular expression.
Declaration
public Elements GetElementsMatchingOwnText(Regex pattern)
Parameters
Type | Name | Description |
---|---|---|
Regex | pattern | regular expression to match text against |
Returns
Type | Description |
---|---|
Elements | elements matching the supplied regular expression. |
See Also
GetElementsMatchingOwnText(String)
Find elements whose text matches the supplied regular expression.
Declaration
public Elements GetElementsMatchingOwnText(string regex)
Parameters
Type | Name | Description |
---|---|---|
System.String | regex | regular expression to match text against. You can use embedded flags (such as (?i) and (?m) to control regex options. |
Returns
Type | Description |
---|---|
Elements | elements matching the supplied regular expression. |
See Also
GetElementsMatchingText(Regex)
Find elements whose text matches the supplied regular expression.
Declaration
public Elements GetElementsMatchingText(Regex pattern)
Parameters
Type | Name | Description |
---|---|---|
Regex | pattern | regular expression to match text against |
Returns
Type | Description |
---|---|
Elements | elements matching the supplied regular expression. |
See Also
GetElementsMatchingText(String)
Find elements whose text matches the supplied regular expression.
Declaration
public Elements GetElementsMatchingText(string regex)
Parameters
Type | Name | Description |
---|---|---|
System.String | regex | regular expression to match text against. You can use embedded flags (such as (?i) and (?m) to control regex options. |
Returns
Type | Description |
---|---|
Elements | elements matching the supplied regular expression. |
See Also
GetHashCode()
Returns the hash code for this instance.
Declaration
public override int GetHashCode()
Returns
Type | Description |
---|---|
System.Int32 |
Overrides
HasClass(String)
Tests if this element has a class.
Declaration
public bool HasClass(string className)
Parameters
Type | Name | Description |
---|---|---|
System.String | className | name of class to check for |
Returns
Type | Description |
---|---|
System.Boolean | true if it does, false if not |
Remarks
Case insensitive.
InsertChildren(Int32, IEnumerable<Node>)
Inserts the given child nodes into this element at the specified index.
Declaration
public Element InsertChildren(int index, IEnumerable<Node> children)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | index | 0-based index to insert children at. Specify
|
IEnumerable<Node> | children | child nodes to insert |
Returns
Type | Description |
---|---|
Element | this element, for chaining. |
Remarks
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.
Prepend(String)
Add inner HTML into this element.
Declaration
public Element Prepend(string html)
Parameters
Type | Name | Description |
---|---|---|
System.String | html | HTML to add inside this element, before the existing HTML |
Returns
Type | Description |
---|---|
Element | this element |
Remarks
The supplied HTML will be parsed, and each node prepended to the start of the element's children.
See Also
PrependChild(Node)
Add a node to the start of this element's children.
Declaration
public Element PrependChild(Node child)
Parameters
Type | Name | Description |
---|---|---|
Node | child | node to add. |
Returns
Type | Description |
---|---|
Element | this element, so that you can add more child nodes or elements. |
PrependElement(String)
Create a new element by tag name, and add it as the first child.
Declaration
public Element PrependElement(string tagName)
Parameters
Type | Name | Description |
---|---|---|
System.String | tagName | the name of the tag (e.g.
|
Returns
Type | Description |
---|---|
Element | the new element, to allow you to add content to it, e.g.:
|
PrependText(String)
Create and prepend a new TextNode to this element.
Declaration
public Element PrependText(string text)
Parameters
Type | Name | Description |
---|---|---|
System.String | text | the unencoded text to add |
Returns
Type | Description |
---|---|
Element | this element |
RemoveClass(String)
Remove a class name from this element's
class
attribute.
Declaration
public Element RemoveClass(string className)
Parameters
Type | Name | Description |
---|---|---|
System.String | className | class name to remove |
Returns
Type | Description |
---|---|
Element | this element |
Select(String)
Find elements that match the Selector CSS query, with this element as the starting context. Matched elements may include this element, or any of its children.
Declaration
public Elements Select(string cssQuery)
Parameters
Type | Name | Description |
---|---|---|
System.String | cssQuery | a Selector CSS-like query |
Returns
Type | Description |
---|---|
Elements | elements that match the query (empty if none match) |
Remarks
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 .
See Also
ToggleClass(String)
Toggle a class name on this element's
class
attribute: if present, remove it; otherwise add it.
Declaration
public Element ToggleClass(string className)
Parameters
Type | Name | Description |
---|---|---|
System.String | className | class name to toggle |
Returns
Type | Description |
---|---|
Element | this element |
ToString()
Converts the value of this instance to a string.
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
System.String |
Overrides
Wrap(String)
Wrap the supplied HTML around this element.
Declaration
public Element Wrap(string html)
Parameters
Type | Name | Description |
---|---|---|
System.String | html | HTML to wrap around this element, e.g.
|
Returns
Type | Description |
---|---|
Element | this element, for chaining. |