Public API (Use Cases)

[JayPanoz]

OK, sorry if it feels like I'm bringing myself into at an early stage of discussion but it seems to me this is an important issue and it'd better be discussed at this point.

For the last four years, some people have been trying to improve UX in reflow using JavaScript. Historically, this has been painful since simple functions tend to grow into huge snippets of bloat made of conditional statements and pagination implementation workarounds. As a result, you often get poor performance, which actually deteriorate UX—and you can't necessarily afford to optimize those snippets because it costs the publisher money and time it is not willing to spend.

Problem is that even simple interactions might be painful. Let’s see some use cases.

Adding/Removing contents

Issue

Let’s say you want to use details, which is a HTML5 tag.

Summary Goes Here

...this is hidden, collapsable content...

Every rendering engine but Trident/EdgeHTML now supports that (landed in Firefox 49) so it works in Reading Systems like iBooks, ADE on OS X, Readium, iOS apps using a web view, etc.

Problem is, it doesn't automatically trigger a pagination recalc. In other words, details is expanded and contents at the end of your XHTML file may be pushed out of the “last page” (overflow).

Obviously, this also apply to content you append/insert based on user interaction, content which is already in the DOM with display: none and you show/hide, etc.

In this case, which is quite a standard pattern on the web, a public function to push pagination recalc would help. A lot. Or maybe something in the vein of regionOverset.

Use cases

• Fanta has purchased a textbook which is quite aside-heavy. He would like to collapse all those asides at first reading in order to focus on the primary content. But maybe he will expand some asides at first reading because they explain concepts instead of extending them.
• Champagne has written a CSS memento in which she is using details extensively. The assumption is that a memento is a utility and should be designed as such (expanded details would make it harder to parse when you're searching for something).
• Mister Pickles is a teacher who added interactive Multiple Choice Questions in his book. Since he saw display: none was a no-go, he used visibility: hidden. In order not to have whitespace everywhere in his book, he defined height and overflow-y for the answer container. But this is suboptimal since scroll might be buggy in some apps and each MCQ is not the same height on every device.

Modals/Popups/Popover

Issue

Managing offset and/or position is tough when all RS don't implement pagination in the same manner. Some are using columns (in some conditions), others report negative values, others require a timeout, etc.

It might be debatable because a lot of people think you should not do that but custom methods could be useful.

Like, for instance, a method to get the page/spread on which the element is actually positioned. For the sake of simplification, something like:

var el = document.getElementById('where-is-waldo');
    el.isOnPage();

Which could have properties like top, left, width, etc. but for the page/spread. Cf. getBoundingClientRect

And then you could theoretically position a modal hands down, even if you're not “a NASA engineer” (quoted from people I actually train).

Use cases

• Colada has quite a bunch of wild abbreviations (abbr) in her essay. While she has used the title attribute, it won’t work on touch devices (the tooltip only displays on mouse hover). She would like to use a popup/popover on mobile but pagination makes scripting much much more difficult than it should be (offset, position, viewport etc.). As a result, her script works in some conditions but will fail spectacularly in others.
• George R.R. has written a series of fantasy novels. The first novel in the series has won awards, a TV drama is currently being broadcasted and his publisher would like to launch an enhanced version with maps (modals) and characters’ info (popups). Unfortunately, this is too hard to do at the moment so they turned to a proprietary authoring solution providing those widgets; widgets are only supported in a specific iApp though, and all readers won't be able to enjoy those enhancements.

Accessibility

To some extent, this is an extension of the two previous sections.

Issue

This is probably where a solid API could help authors improve eBooks spectacularly, by covering cases which aren't covered by default. It’s not all about interactivity any longer, it’s about empowering users—or at least helping them access books in the best conditions.

Sometimes you might want to override the RS’ settings (background-color, text color, etc.). Other times you might want to be in sync with those RS’ settings.

For instance, maybe you want to apply a different type scale when the font-size user setting reaches a specific value (see Mabel’s use case). Or maybe you'd like to add a couple of settings depending on the existing RS’s settings.

Use cases

• Mabel is 72 years old. She loves to read but she has vision problems. Her daughter has bought her an eReader because it is way more comfortable. She started to read Moby Dick and increased the font-size to 36 pt. Problem is chapter titles’ are now 72 pt and are quite unreadable. If only the eBook author has known the container’s width to apply specific styles for this case…
• Jiminy is currently developing a framework for dyslexia. He has planned to implement background colors, image collapsing (global), letter- and word-spacing, and a reading rule based on the position of the mouse. This should probably be a plugin but for the time being, it is not an option so the script must be embedded in EPUB files.
  • background-color can't necessarily be applied to the whole UI (but only the container, be it a div or an iframe);
  • image collapsing needs pagination recalc;
  • letter- and word-spacing needs pagination recalc as well;
  • the reading rule, which is one simple line of JS in its simplest incarnation, needs a ton of workarounds and conditional statements (multiple situations, pagination implementation, RS’ versions, etc.).

He doesn't have much time to deal with those issues, the project comes to a standstill.

---

I know an API with functions/methods isn't particularly easy to design and implement. It may well be debatable too.

However, it could remove a lot of the barriers limiting what we can do in reflow, the performance we can achieve and the frameworks/plugins we can build.

(Sorry for the inconvenience.)

[edit]

• added reference to regionOverset in “Adding/Removing Contents”;
• added reference to plugins in conclusion;
• edited conclusion to make it clearer.

[danielweck]

Regarding "Adding/Removing contents", the latest revision of Readium in the develop branch now makes use of a so-called "resize sensor" in order to determine when custom font-faces (author and user-specified CSS font-family) are loaded and rendered. Prior to that, an attempt was made to use the Font Loader API (and a fallback polyfil) but this led to other issues.
Anyway, more to the point: support for pagination of reflowable content with "dynamic" sizes (e.g. expandable/collapsible details element) should now be available. We are in the process of testing this.
@olivierkorner

EDIT: done. Works just fine in reflow and scroll views.