3.org/TR/html401/intro/sgmltut.html#h-3.2.1">element in a specific {@linkplain Source source} document, which encompasses a {@linkplain #getStartTag() start tag}, an optional {@linkplain #getEndTag() end tag} and all {@linkplain #getContent() content} in between.
Take the following HTML segment as an example:
<p>This is a sample paragraph.</p>
The whole segment is represented by an Element
object. This is comprised of the {@link StartTag} "<p>
",the {@link EndTag} "</p>
", as well as the text in between.An element may also contain other elements between its start and end tags.
The term normal element refers to an element having a {@linkplain #getStartTag() start tag}with a {@linkplain StartTag#getStartTagType() type} of {@link StartTagType#NORMAL}. This comprises all {@linkplain HTMLElements HTML elements} and non-HTML elements.
Element
instances are obtained using one of the following methods:
- {@link StartTag#getElement()}
- {@link EndTag#getElement()}
- {@link Segment#getAllElements()}
- {@link Segment#getAllElements(String name)}
- {@link Segment#getAllElements(StartTagType)}
See also the {@link HTMLElements} class, and the
XML 1.0 specification for elements.
The three possible structures of an element are listed below:
- Single Tag Element:
- Example:
<img src="mypicture.jpg">
The element consists only of a single {@linkplain #getStartTag() start tag} and has no {@linkplain #getContent() element content}(although the start tag itself may have {@linkplain StartTag#getTagContent() tag content}).
{@link #getEndTag()}==null
{@link #isEmpty()}==true
{@link #getEnd() getEnd()}==
{@link #getStartTag()}.
{@link #getEnd() getEnd()}
This occurs in the following situations:
- An HTML element for which the {@linkplain HTMLElements#getEndTagForbiddenElementNames() end tag is forbidden}.
- An HTML element for which the {@linkplain HTMLElements#getEndTagRequiredElementNames() end tag is required}, but the end tag is not present in the source document.
- An HTML element for which the {@linkplain HTMLElements#getEndTagOptionalElementNames() end tag is optional}, where the implicitly terminating tag is situated immediately after the element's {@linkplain #getStartTag() start tag}.
- An {@linkplain #isEmptyElementTag() empty element tag}
- A non-HTML element that is not an {@linkplain #isEmptyElementTag() empty element tag} but is missing its end tag.
- An element with a start tag of a {@linkplain StartTag#getStartTagType() type} that does not define a{@linkplain StartTagType#getCorrespondingEndTagType() corresponding end tag type}.
- An element with a start tag of a {@linkplain StartTag#getStartTagType() type} that does define a{@linkplain StartTagType#getCorrespondingEndTagType() corresponding end tag type} but is missing its end tag.
- Explicitly Terminated Element:
- Example:
<p>This is a sample paragraph.</p>
The element consists of a {@linkplain #getStartTag() start tag}, {@linkplain #getContent() content}, and an {@linkplain #getEndTag() end tag}.
{@link #getEndTag()}!=null
.
{@link #isEmpty()}==false
(provided the end tag doesn't immediately follow the start tag)
{@link #getEnd() getEnd()}==
{@link #getEndTag()}.
{@link #getEnd() getEnd()}.
This occurs in the following situations, assuming the start tag's matching end tag is present in the source document:
- An HTML element for which the end tag is either {@linkplain HTMLElements#getEndTagRequiredElementNames() required} or {@linkplain HTMLElements#getEndTagOptionalElementNames() optional}.
- A non-HTML element that is not an {@linkplain #isEmptyElementTag() empty element tag}.
- An element with a start tag of a {@linkplain StartTag#getStartTagType() type} that defines a{@linkplain StartTagType#getCorrespondingEndTagType() corresponding end tag type}.
- Implicitly Terminated Element:
- Example:
<p>This text is included in the paragraph element even though no end tag is present.
<p>This is the next paragraph.
The element consists of a {@linkplain #getStartTag() start tag} and {@linkplain #getContent() content}, but no {@linkplain #getEndTag() end tag}.
{@link #getEndTag()}==null
.
{@link #isEmpty()}==false
{@link #getEnd() getEnd()}!=
{@link #getStartTag()}.
{@link #getEnd() getEnd()}.
This only occurs in an HTML element for which the {@linkplain HTMLElements#getEndTagOptionalElementNames() end tag is optional}.
The element ends at the start of a tag which implies the termination of the element, called the implicitly terminating tag. If the implicitly terminating tag is situated immediately after the element's {@linkplain #getStartTag() start tag}, the element is classed as a single tag element.
See the element parsing rules for HTML elements with optional end tags for details on which tags can implicitly terminate a given element.
See also the documentation of the {@link HTMLElements#getEndTagOptionalElementNames()} method.
The following rules describe the algorithm used in the {@link StartTag#getElement()} method to construct an element.The detection of the start tag's matching end tag or other terminating tags always takes into account the possible nesting of elements.
- If the start tag has a {@linkplain StartTag#getStartTagType() type} of {@link StartTagType#NORMAL}:
- If the {@linkplain StartTag#getName() name} of the start tag matches one of therecognised {@linkplain HTMLElementName HTML element names} (indicating an HTML element):
- If the end tag for an element of this {@linkplain StartTag#getName() name} is{@linkplain HTMLElements#getEndTagForbiddenElementNames() forbidden}, the parser does not conduct any search for an end tag and a single tag element is created.
- If the end tag for an element of this {@linkplain StartTag#getName() name} is {@linkplain HTMLElements#getEndTagRequiredElementNames() required}, the parser searches for the start tag's matching end tag.
- If the matching end tag is found, an explicitly terminated element is created.
- If no matching end tag is found, the source document is not valid HTML and the incident is {@linkplain Source#getLogger() logged} as a missing required end tag.In this situation a single tag element is created.
- If the end tag for an element of this {@linkplain StartTag#getName() name} is{@linkplain HTMLElements#getEndTagOptionalElementNames() optional}, the parser searches not only for the start tag's matching end tag, but also for any other tag that implicitly terminates the element.
For each tag (T2) following the start tag (ST1) of this element (E1): - If T2 is a start tag:
- If the {@linkplain StartTag#getName() name} of T2 is in the list of{@linkplain HTMLElements#getNonterminatingElementNames(String) non-terminating element names} for E1,then continue evaluating tags from the {@linkplain Element#getEnd() end} of T2's corresponding{@linkplain StartTag#getElement() element}.
- If the {@linkplain StartTag#getName() name} of T2 is in the list of{@linkplain HTMLElements#getTerminatingStartTagNames(String) terminating start tag names} for E1,then E1 ends at the {@linkplain StartTag#getBegin() beginning} of T2.If T2 follows immediately after ST1, a single tag element is created, otherwise an implicitly terminated element is created.
- If T2 is an end tag:
- If the {@linkplain EndTag#getName() name} of T2 is the same as that of ST1,an explicitly terminated element is created.
- If the {@linkplain EndTag#getName() name} of T2 is in the list of{@linkplain HTMLElements#getTerminatingEndTagNames(String) terminating end tag names} for E1,then E1 ends at the {@linkplain EndTag#getBegin() beginning} of T2.If T2 follows immediately after ST1, a single tag element is created, otherwise an implicitly terminated element is created.
- If no more tags are present in the source document, then E1 ends at the end of the file, and an implicitly terminated element is created.
Note that the syntactical indication of an {@linkplain StartTag#isSyntacticalEmptyElementTag() empty-element tag} in the start tagis ignored when determining the end of HTML elements. See the documentation of the {@link #isEmptyElementTag()} method for more information. - If the {@linkplain StartTag#getName() name} of the start tag does not match one of therecognised {@linkplain HTMLElementName HTML element names} (indicating a non-HTML element):
- If the start tag is {@linkplain StartTag#isSyntacticalEmptyElementTag() syntactically an empty-element tag}, the parser does not conduct any search for an end tag and a single tag element is created.
- Otherwise, section 3.1 of the XML 1.0 specification states that a matching end tag MUST be present, and the parser searches for the start tag's matching end tag.
- If the matching end tag is found, an explicitly terminated element is created.
- If no matching end tag is found, the source document is not valid XML and the incident is {@linkplain Source#getLogger() logged} as a missing required end tag.In this situation a single tag element is created.
- If the start tag has any {@linkplain StartTag#getStartTagType() type} other than {@link StartTagType#NORMAL}:
- If the start tag's type does not define a {@linkplain StartTagType#getCorrespondingEndTagType() corresponding end tag type}, the parser does not conduct any search for an end tag and a single tag element is created.
- If the start tag's type does define a {@linkplain StartTagType#getCorrespondingEndTagType() corresponding end tag type}, the parser assumes that a matching end tag is required and searches for it.
@see HTMLElements