cssSelector not available for highlights in EPUBs

[hubertadamusinkbook]

We have troubles with CSS Selectors, as described in the documentation.

We are using the test-app as the baseline for tests, since it includes the highlights functionality. Any created highlight (so a Locator) returns null in response to a call of the extension value Locator.Locations.cssSelector from org.readium.r2.shared.publication.html.Locator.kt. In other words, this renders us unable to retrieve CSS Selectors from any highlight.

On a technical level, the cssSelector value retrieves the "cssSelector" key value from the otherLocations field of the Locator class. This means that otherLocations do not contain the "cssSelector" key.

We would be very grateful for guidance on how to access CSS Selectors of created highlights.

[mickael-menu]

Decorations / highlights use the locator that the host app provides. Are you talking about the Locator returned by the currentSelection() API instead?

kotlin-toolkit/readium/navigator/src/main/java/org/readium/r2/navigator/SelectableNavigator.kt

Line 18 in dc25e7b

public suspend fun currentSelection(): Selection?

That's true that only the text is returned by this API:

kotlin-toolkit/readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorFragment.kt

Lines 717 to 721 in e5f5ad1

	return Selection(
	locator = currentLocator.value.copy(
	text = Locator.Text.fromJSON(json.optJSONObject("text"))
	),
	rect = rect

If you'd like to contribute this feature in the toolkit (it could be useful IMHO), you would need to modify the above API, and return the CSS selector from the JavaScript layer here:

kotlin-toolkit/readium/navigator/src/main/assets/_scripts/src/selection.js

Lines 39 to 46 in 92fd6e8

	export function getCurrentSelection() {
	const text = getCurrentSelectionText();
	if (!text) {
	return null;
	}
	const rect = getSelectionRect();
	return { text, rect };
	}

To compute the CSS selector, you can use one of the third-party dependencies we already have:

import { getCssSelector } from "css-selector-generator";

getCssSelector(element);

There's an example here:

kotlin-toolkit/readium/navigator/src/main/assets/_scripts/src/dom.js

Lines 54 to 56 in c868166

	locations: {
	cssSelector: getCssSelector(element),
	},

For more information about modifying the JavaScript layer, see this document: https://github.com/readium/kotlin-toolkit/blob/develop/CONTRIBUTING.md#modifying-the-epub-navigators-javascript-layer

Why do you need the CSS selector in this locator, by the way?

[hubertadamusinkbook]

Thank you for the detailed response. We need the CSS selector in our new Reader app, that is developed without the basis of test-app, that will rely on the CSS selector to precisely pinpoint the location of notes and bookmarks (as per our requirements).

[llemeurfr]

It seems this is a first effort to support annotations (hightlights are simplified annotations). In this case, please see https://github.com/readium/annotations, i.e. a model for shareable annotations (and hightlights). There is a CSS Selector + TextPositionSelector defined in the spec.
It will be implemented in the mobile toolkit sometime in the future.