Navigator API: Did we reach the last screen page yet?

[mickael-menu]

Being able to know when the navigator reached the last screen page came up at least 3 times (e.g. readium/r2-testapp-kotlin#292 (comment)) already. This can be used, for example, to present a rating dialog when the user reaches the end of the publication.

The current implementation of the Locator/positionList doesn't work for that, because the last position doesn't have a totalProgression of 100%, since the progression is located at the start of the location. Moreover, a single position can actually contain several screen pages on smaller devices. It's not a guarantee we reached the end of the publication.

I can think of three different ways to tackle this:

• Synthesizing an extra locator when the navigator reaches the last screen page, using the last position (in Publication.positionList) but with the totalProgression set to 100%. This is the less disruptive, but also it breaks a bit the coherence of totalProgression which so far points to the start of the page, not the end.
• We could add an extension to Locator.locations to handle this extra information, such as an enum of generic locations (start, end) that would be set for these special locations.
• Another approach could be to share a Navigation context when broadcasting the LocationChanged event, which would contain this information. This could be useful if we need to add other information that won't fit our current models.

cc @Bolling88

[mickael-menu]

Another solution suggested by Hadrien, which is better in my opinion: Broadcasting a PublicationEndReached event (and a PublicationStartReached for symmetry).

[HadrienGardeur]

Should we start a vote?

[Bolling88]

I like the event approach the best, since it doesn't break current implementations of Readium, and it is easy to subscribe to the events that are of interest.

[rkwright]

I like the broadcast approach, but how do we know the user really reached the end of the publication? Obviously if they navigated to the last screen (and I use that term deliberately) we can't know if they actually read the text (or images) but we can't solve everything. But do we know, unambiguously, that the user navigated to the last screen?

[mickael-menu]

Indeed, it's a very imperfect approach. It's even worse than that because most books have extra chapters after the actual content (indexes, bibliography, etc.), so there's little chance that the reader will actually reach the last screen.

As far as I know, EPUB doesn't provide a way to mark the end of the content. Maybe that could be something to be added in the evolution of the spec? I'm pretty sure Amazon is adding this manually to its Kindle books to present the "Rate this book" dialog after the user turns the last page of content.

But do we know, unambiguously, that the user navigated to the last screen?

Yes, this we can know.

[JayPanoz]

EPUB doesn't provide a way to mark the end of the content.

At least in some EPUB3 files, you should have epub:type="backmatter" as an imperfect way to check when body matter ends?

I know how imperfect it is because we had this issue (for preprocessing) and obviously some files won’t have that.

[mickael-menu]

At least in some EPUB3 files, you should have epub:type="backmatter" as an imperfect way to check when body matter ends?

That's interesting. Unfortunately it's not part of the OPF, so it requires to parse the documents. So I'm not so sure that Readium should do that, but it could be useful to think about how a reading app would extend Readium to figure out the backmatter.

Maybe a simple JS injection would be enough, if it detects epub:type="backmatter", then it would broadcast an event to perform the "end of publication" action. This also fixes the issue raised by Ric, since it's only broadcasted after we swipe the last page of content.

I wonder how frequent is this added in EPUB authoring.

[JayPanoz]

it requires to parse the documents.

I can recall finding it in the landmarks (nav doc) on a few occasions, although I wouldn’t say it’s the norm. So that could be the priority, and then parsing the docs.

And well another important detail is that frontmatter, bodymatter, and backmatter are not mapped in DPUB ARIA.

The best I could see happening is some heuristics as, by tradition, some parts are more or less guaranteed to be backmatter in, at least, some cultures (e.g. index, acknowledgements, etc. in western books).

That said, my knowledge on this matter isn’t anything close to what one could call expertise so I’ll appreciate to be proven wrong. :-)

[HadrienGardeur]

This latest point is already being discussed in another repo: readium/webpub-manifest#50

[llemeurfr]

Mickaël said that the toolkit knows when the user IS on the last screen (I suppose the use case is a paginated view). In a scroll view, the user will try to move down until it reaches the bottom of the resource, therefore the toolkit knows he bumps to the bottom of the last resource in the reading order. If there is a backmatter indication in the landmarks (i.e. an annex, usually as a new resource), the toolkit knows when the user moves to this new resource. If the backmatter indication is an epub:type, the toolkit is aware of its presence once the user has moved to it.

In these 4 situations, the toolkit is therefore able to send an event of type PublicationEndReached.

It seems sufficient for the app to decide it should do something specific with this event, isn't it?

[mickael-menu]

In these 4 situations, the toolkit is therefore able to send an event of type PublicationEndReached.

Yes we could do that, unless there's a need to really get the last screen page of the publication, in which case we could have two events.

I would rename the event to BodyEndReached or PublicationBodyEndReached then.