This extends the main definition of the
location object with constructs specific to HTML documents.
||A CSS Selector||String||No|
||See full description below||String||No|
||See full description in the next separate section||Object||No|
partialCfi is an expression conforming to the “right-hand” side of the EPUB CFI syntax, that is to say: without the EPUB-specific OPF spine item reference that precedes the first
! exclamation mark (which denotes the “step indirection” into a publication document). Note that the wrapping
epubcfi(***) syntax is not used for the
partialCfi string, i.e. the “fragment” part of the CFI grammar is ignored.
This construct enables a serializable representation of a DOM Range.
||A serializable representation of the “start” boundary point of the DOM Range||Object (see below)||Yes|
||A serializable representation of the “end” boundary point of the DOM Range||Object (see below)||No|
end field is optional. When only the
start field is specified, the
domRange object represents a “collapsed” range that has identical “start” and “end” boundary points.
||A CSS Selector to a DOM element||String||Yes|
||See full description below||integer, starting at zero ([0, n])||Yes|
||See full description below||integer, starting at zero ([0, n])||No|
In a DOM Range object, the
startOffset tuple represents the “start” boundary point. Similarly, the the
endOffset tuple represents the “end” boundary point. In both cases, the
start/endContainer property is a pointer to either a DOM text node, or a DOM element (this typically depends on the mechanism from which the DOM Range instance originates, for example when obtaining the currently-selected document fragment using the
window.selection API). In the case of a DOM text node, the
start/endOffset corresponds to a position within the character data. In the case of a DOM element node, the
start/endOffset corresponds to a position that designates a child text node.
Note that a recommended implementation feature is to “normalize” DOM Ranges so that the
start/endContainer property always references a DOM text node (i.e. not an DOM element). On mobile devices where touch interaction is used, browser engines may already perform such a normalization step. On desktop platforms where interaction is mouse-driven (or other accurate pointing device), the user selection may not necessarily be normalized ahead of time. Either way, the DOM Range serialization model described herein supports the element use-case.
cssSelector field always references a DOM element. If the original DOM Range
start/endContainer property references a DOM text node, the
textNodeIndex field is used to complement the CSS Selector; thereby providing a pointer to a child DOM text node; and
charOffset is used to tell a position within the character data of that DOM text node (just as the DOM Range
start/endOffset does). If the original DOM Range
start/endContainer property references a DOM Element, then the
textNodeIndex field is used to designate the child Text node (just as the DOM Range
start/endOffset does), and the optional
charOffset field is not used (as there is no explicit position within the character data of the text node).
The definition of the
text object includes
after. When specified in the context of a “range”
location, this textual information must be populated using the “raw” DOM character data (as opposed to a normalized / trimmed form), which typically includes insignificant leading/trailing/interspersed whitespaces. This is so that consuming APIs have the option to match the
locator.text information with the original DOM text. It is therefore advised that the text should be “cleaned-up” before being presented to end users.