Locations for HTML Documents
Additional properties for the location Object
This extends the main definition of the location object with constructs specific to HTML documents.
| Key | Definition | Format | Required |
|---|---|---|---|
cssSelector |
A CSS Selector | String | No |
partialCfi |
See full description below | String | No |
domRange |
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.
The domRange Object
This construct enables a serializable representation of a DOM Range.
| Key | Definition | Format | Required |
|---|---|---|---|
start |
A serializable representation of the “start” boundary point of the DOM Range | Object (see below) | Yes |
end |
A serializable representation of the “end” boundary point of the DOM Range | Object (see below) | No |
Note that 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.
The start and end Object
| Key | Definition | Format | Required |
|---|---|---|---|
cssSelector |
A CSS Selector to a DOM element | String | Yes |
textNodeIndex |
See full description below | integer, starting at zero ([0, n]) | Yes |
charOffset |
See full description below | integer, starting at zero ([0, n]) | No |
In a DOM Range object, the startContainer + startOffset tuple represents the “start” boundary point. Similarly, the the endContainer + 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.
The 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).
Impact on the text object
The definition of the locator’s text object includes highlight, before and 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.