JSON Locator not parsing Fragments correctly

[jspizziri]

Bug Report

It appears that this libraries Locator isn't automatically parsing #'s in hrefs and adding them as fragments to the Locator objects locations. I'd also like to note that the kotlin-toolkit seems to be doing this fine.

What happened?

If you pass a JSON object like the one below to the Locator constructor you will not be properly navigated to it, as the fragment isn't parsed.

{
    "href": "7604861093435514544_67098-h-0.htm.xhtml#pgepubid00012",
    "type": "application/xhtml+xml"
}

Expected behavior

It seems like for consistency withkotlin-toolkit we should be parsing those fragments and adding them automatically. Perhaps similar to how the deprecated Link constructor is doing it.

How to reproduce?

1. Feed the attached epub file into the Readium app: pg67098-images-3.epub.zip
2. Build a Locator object out of the above JSON object.
3. Feed the Locator to navigator.go.
4. Observe that the link is not properly navigated to.

Environment

• Readium version: 2.4.0

Testing device

• iOS version: 16.1
• Model (e.g. iPhone 11 Pro Max): iPhone 14 Pro
• Is it an emulator? Yes

1. Feed the attached epub file into the Readium app.
2. Build a Locator object out of the above JSON object.2. Build a Locator object out of the above JSON object.
3. Feed the Locator to navigator.go.
4. Observe that the link is not properly navigated to.4. Observe that the link is not properly navigated to.

Environment### Environment

• Readium version: 2.4.0* Readium version: 2.4.0

Testing device#### Testing device

• iOS version: 16.1* iOS version: 16.1
• Model (e.g. iPhone 11 Pro Max): iPhone 14 Pro* Model (e.g. iPhone 11 Pro Max): iPhone 14 Pro
• Is it an emulator? Yes* Is it an emulator? Yes

Additional Context

I found this issue while working this one 5-stones/react-native-readium#11 (comment). You can read that if you want some more context.

[mickael-menu]

I'm not sure I see where the discrepancy is with the Kotlin toolkit, the Locator constructor doesn't parse the anchor either. Do you know which API exactly is behaving differently?

As for your use case (I read the original issue), it looks like you are trying to parse a Link object as a Locator (in their minimal versions, they are very similar). The table of contents is a list of Link objects, to navigate to a toc item, you need to:

1. Create a Link object from the JSON if you don't have one already.
2. Call publication.locate(link) to get the proper Locator object.
3. Use publication.go(to: locator).

Or more directly, use publication.go(to: link) which is doing the same thing under the hood.

[jspizziri]

@mickael-menu thanks for educating me and sorry for being a n00b.

In general, is there some documentation I can read about the differences between Links and Locators and how and when they're used? Specifically, how do I know the difference between them from a JSON representation? I had read through this and naively assumed that's all there was to it. I haven't been able to find any docs on Links.

Thanks in advance!

[mickael-menu]

You can read the specification of the Link object here. Generally a Link represents (declares) a whole resource while a Locator is a discrete location inside a resource. The table of contents is a bit overlapping these definitions and could have been a list of Locator, I guess that's where the confusion came.

This PR describes use cases for locators, but it was never merged.

[jspizziri]

@mickael-menu thanks again! This is super helpful.

When looking at the schemas it looks like if an object doesn't have any locations then it must be a Link and visa versa (assuming the objects are properly constructed of course).

Thanks again!

[mickael-menu]

Technically this JSON could both be a Link object or a Locator :

{
    "href": "resource.xhtml",
    "type": "application/xhtml+xml"
}

So you should look at each API or JSON schema/specification to know what to expect. With the native Kotlin/Swift APIs it's easy as it's fully typed. With JavaScript you might need to look into the JSON schemas.

[jspizziri]

@mickael-menu ahh, I see. Thanks.

One final question: Do locators completely subsume links? For instance, I could just convert all links into locators for the TOC and return those and then only ever deal in Locators.

It seems like that could be possible.

[mickael-menu]

You couldn't because a table of contents can be a tree, thanks to Link.children. A Locator cannot represent a nested structure, it's only a single discrete location. Saying that I, (re-)understood why the toc is made of Link and not Locator objects. 😉

[jspizziri]

Ahh, unfortunate, but that makes sense. Thanks again!