Locators

Locators are meant to provide a precise location in a publication in a format that can be shared outside of the publication.

There are many different use cases for locators:

  • bookmarks
  • notes and highlights
  • current position in a publication
  • human-readable (and shareable) reference to a fragment

Each locator consist of one or more locations.

Locations can be divided into two different groups:

  • locations that are tied to the structure of a resource, such as CFI or XPath
  • and those that are not related to any particular resource

While locations that are tied to the structure of a resource provide a much more fine grained information, there are also more likely to break when the resource is updated.

That’s one of the reason why Readium-2 recommends using a mix of different locations when implementing some of the use cases listed above.

The Locator Object

Locators can be grouped together using a Locator Object.

A Locator Object must contain at least one location.

A Locator Object may contain the following keys:

Key Definition Format
href Contains the URI of the resource where the locator points to. URI
locations Contains one or more locators . Locators
text Contains a number of strings that can be useful to identify a locator. Locator Text Object

This document defines the following list of locations:

Key Definition Format
cfi Contains the right-most part of a Canonical Fragment Identifier (CFI). CFI
id Contains a specific id available in the resource. String
position Contains an position in the publication. Integer
progression Contains an overall progression (%) in the publication based on the reading order. Float between 0 and 1

This document also defines the following keys for the Locator Text Object:

Key Definition Format
after Text after the locator. String
before Text before the locator. String
highlight Text that corresponds to the locator. String

Example: Pointing to the first chapter of Pride and Prejudice

{
  "href": "http://example.com/chapter1",
  "locations": {
    "position": 10,
    "progression": 0.01452
  },
  "text": {
    "after": "It is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife."
  }
}

Calculating Positions & Progression

There are a number of ways that positions can be calculated:

  • for image or page based publications, each position can simply point to the resource (href) without any additional locator
  • for other types of publications, the service should calculate that each position in a text-based publication contains 1024 characters (not bytes). 1024 is arbitrary but matches what RMSDK uses.