Please add an attribute that allows each bookmark in an EPUB 3 table of contents to be individually set to either expanded or collapsed by default

[meng89]

Section

https://www.w3.org/TR/epub-33/#sec-nav

Describe the problem

As the creator of the EPUB3 ebook format, I've included a navigation structure with approximately two thousand <li> elements and several hundred <ol> elements. It would significantly enhance the reader's experience if a property could be introduced that allows EPUB readers to understand my intention as the format producer—for instance, to default certain sections to be collapsed and others to be expanded. This would make it much easier for readers to quickly locate desired chapters.

Describe the fix or new feature you propose

Maybe like this:
<ol default-state="collapsed">...</ol>
<ol default-state="expanded">...</ol>
<ol default-state="none">...</ol>

[iherman]

My first impulse is to say: do not re-invent the Web. There are a number of very simple and small javascript snippets, combined with some CSS to provide such collapsable lists. Let us reuse them.

I realize, however, that my first impulse is not correct, because Reading systems usually create their own TOC from the navigation document and they usually ignore all styling instructions (and, presumably) javascript. So my approach would only work if the navigation document is also in the spine (which is allowed).

A complete solution would require the change in the RS and would require the RS to provide collapsable TOC entries. I am not sure if that would work...

[meng89]

I'm a bit confused about how RS should display its TOC. I now understand why some readers have collapsible TOC, while others use indented and flat lists of all bookmark entries. Because of PDF, I used to naively think EPUB RS should have collapse and expand functions, and that the lack of this feature was due to lazy developers! Perhaps we could still use an attribute to tell the RS whether the TOC should be expanded or collapsed by default. An RS without a collapse function could just ignore this attribute. What do you think of this approach?

[iherman]

I'm a bit confused about how RS should display its TOC. I now understand why some readers have collapsible TOC, while others use indented and flat lists of all bookmark entries. Because of PDF, I used to naively think EPUB RS should have collapse and expand functions, and that the lack of this feature was due to lazy developers!

There is no rule on these; the specification does not prescribe a reading system behavior, it is up to the design choices of the specific reader. An EPUB document only provides the necessary data.

Perhaps we could still use an attribute to tell the RS whether the TOC should be expanded or collapsed by default. An RS without a collapse function could just ignore this attribute. What do you think of this approach?

It may be possible if RSs would accept to generally implement it. (Provided it has a proper specification of the required feature, which is not that obvious. What means 'default', for example? Is collapsing "recursive", ie, is a subitem of a collapsed subitem automatically collapsed? Etc.)

[meng89]

When there is no default-state attribute or this attribute is set to "none", let RS choose to expand or collapse. (If there is only a novel with less than ten chapters, maybe the reader can choose to expand. If it is a large technical book, maybe the reader will choose to collapse, of course, this is RS's business) I think the default-state="none" is only kept for the convenience of people who manually adjust EPUB.

The state will not recurse, that is, no matter what the state of the child item is, when the parent item is collapsed and then expanded, the child item will still be in the previous state. I think this is more reasonable.

Is this feasible?

[mattgarrish]

One problem with this proposal is that we've committed to stop diverging from the web. We've deprecated most of the custom elements and attributes originally added to EPUB 3, but this leads us back to creating a new attribute that only has relevance for reading systems. ARIA might be able to fill the gap with aria-expanded, but that would lead to more complicated authoring as it would require other roles to flesh out the tree widget aspect of the table of contents.

But more importantly, I'd want to hear from reading system developers that this is something they're interested in and are going to support before we try to work out a solution. We've tried to accommodate the desires of authors without great success at times (thinking of the fixed layout metadata we may end up deprecating).

[danielweck]

Different Reading Systems expose the EPUB navigation document's table of contents, landmarks, page list, etc. in different ways, especially when comparing across mobile apps, e-ink tablet, and desktop software.

I do not think it would be reasonable to expect RSs to consistently implement support in their respective GUI design for the suggested collapsed / expanded authored directive.

Conversely, that's where HTML, CSS and Javascript (minimally) can be used by content creators to offer a user experience that "should work" in most modern RSs, inside a rendered document placed in the publication spine. Said document wouldn't even need to be the EPUB navigation document, it could be an arbitrary HTML resource located near the start of the reading order.

[mattgarrish]

Said document wouldn't even need to be the EPUB navigation document, it could be an arbitrary HTML resource located near the start of the reading order.

Exactly, if you want to create your own you're free to do it in the spine. Author control over the reading system default rendering seems unlikely to get traction.

[HadrienGardeur]

I wouldn't recommend doing any effort in HTML/CSS/JS to allow users to collapse/expand either, since these interactions could be disabled by reading systems as well.

Expanding content is quite problematic in a paginated view, which is what most RS default to.

BTW I agree that having access to actions for expanding or collapsing everything is useful, but it's not very common unfortunately. Being able to search/filter among items is very useful as well for complex publications with many items and a deeply nested structure.