Feature Proposal: Controlling component pagination settings within Editoria
Summary
This proposal envisions laying the groundwork to allow users to specify more granular pagination options from within the Book Builder interface on a component-by-component basis, starting with a “do not include in TOC” option for frontmatter. It also proposes a mechanism by which certain front and backmatter components can be linked to CSS designed for a specific component, to allow it to be displayed differently than the rest of the book when it is paginated.
This proposal is deliberately modest in scope from a user perspective because it involves a fair amount of technical groundwork and changes to how the pagination happens under the hood. Building the features above as a starting point would serve as a proof of concept and starting point for including more pagination options within Editoria itself.
Proposal
Currently users generally cannot change anything about how a component is displayed via any interface in Editoria. Making changes to how a book is paginated - what is and isn’t included in the Table of Contents, how certain components are laid out on the page, etc. - requires updating CSS templates or Javascript scripts, which isn’t possible for most users.
This proposal includes two specific features that would be apparent to a user of Editoria:
- Add a “Do not include in TOC” control to the Book Builder interface, which could be set per component. This would also prevent the component’s name (e.g. “Half title”) from actually appearing when it is paginated, and stop the page number from being printed on the page. This button could be as simple as a toggle icon or checkbox to start, appearing inline with every component.
- Link Book Builder components that have special CSS templates just for them (copyright page, title page) to the right template by matching the component’s Book Builder name with the CSS template’s name. For example, the “Copyright page” would get its special copyright layout when it was paginated because of a correspondingly named CSS template. Components with titles that don’t correspond to any specific CSS templates get paginated with the default CSS for book content. This feature currently exists in a limited way but should be expanded.
Both of the above results can currently be achieved with a workaround (square brackets in the title of the component), but this proposal would replace it. This feature proposal suggests some behind-the-scenes changes to how the book pagination works (passing pagination information to Paged.js via HTML classes), which will enable more pagination controls to be added as Editoria interfaces the future.
Current workaround from user's perspective
A workaround to provide limited pagination control from the Book Builder interface was developed while producing a book with the University of California Press. By wrapping a Book Builder component’s name in brackets [like this], a book editor can indicate that specific components needed special handling to paginate correctly. Specifically, according to UCP’s design spec, certain components need to be omitted from the Table of Contents, need a specific CSS template applied to them, shouldn’t display a page number, and need their titles removed from them before being paginated.
Take the copyright page as an example:
- The copyright page should not be included in the Table of Contents
- The copyright page is not supposed to have a literal title “Copyright page” at the top of it in the print-ready book
- The copyright page shouldn’t display a page number
- The copyright page is formatted quite differently than other parts of the book, and has its own special CSS template so it will look right when it’s paginated.
Let's say a user had uploaded a book as a series of files, and wants to ensure the copyright page is handled correctly. He or she would:
- Open the component and style it
- Type "[Copyright page]" in the component (if that text isn't already there) and tag it with the Title style.
The brackets in the title mean the component gets special processing, and the copyright page gets its special formatting because its name "Copyright page" matches the name of an existing CSS template, made just for the copyright page.
How the workaround works
After a user has finished styling the book, and is ready to see the paginated output:
- In the “EXPORT BOOK” interface in the top right of the Book Builder, any user selects “PagedJS” from the dropdown menu and press the “GO” button.
- Editoria assembles the contents of all of the components from the Book Builder into one single HTML file, generating a Table of Contents, compiling the notes, etc.
- Editoria sends this single HTML file to Paged.js.
- Before the book is paginated, Paged.js runs a Javascript cleanup process that does some manipulation of the HTML file. For each component with a title enclosed by brackets, the cleanup:
- Updates the TOC HTML created by Editoria to remove the component
- Sets the component’s Title from the HTML to not display at all. For example, the copyright page’s HTML includes an Title element containing the literal text “Copyright page,” which needs to be hidden because it shouldn’t actually be included in the paginated book.
- Normalizes the component’s name from the Book Builder and adds it as a class attribute to the component’s HTML element. E.g. "[Copyright page]" becomes "copyright-page".
- The updated HTML is then given to Paged.js to do the actual pagination. It applies the CSS that determines how the paginated book looks. If any CSS matches any of the component names added to HTML elements by the previous step, it’s applied to that component.
Proposed changes to implementation
- Include normalized Book Builder component names as class data on ALL front and backmatter components, not just bracketed ones. The square brackets are required to check for named CSS templates, but they also exclude the component from the TOC. By passing all component names as classes, components could be included in the TOC and also match special templates by name. (tracked in #322 (closed))
- Editoria itself, not a preprocessing Javascript step before Paged.js, should add the FM/BM component titles as class names. Since Editoria already generates an HTML file from Editoria’s book contents for export to Paged.js, it should add this class information as it does, so more processing isn’t needed later. (tracked in #322 (closed))
- Similarly, Editoria, not the Javascript cleanup, should include the information on whether to hide the component title in the paginated display and hide the page number as an HTML class attribute when it exports HTML to Paged.js. These options would be controlled by the “Do not include in TOC” interface. (2nd task in #323 (closed))
- Currently, Editoria makes a TOC with ALL components, and the Javascript cleanup then corrects the TOC by removing components that should have been excluded. Instead, Editoria should simply exclude components that shouldn’t be in the TOC in the first place. (3rd task in #323 (closed))
- Finally, the existing CSS that governs how the pagination looks should be updated to change to reflect the new HTML class information: include/exclude from TOC, component name, etc. (4th task in #323 (closed))
Further enhancements
If this proposal is successfully implemented as a proof of concept starting point, it would provide a path to add more granular pagination controls to Editoria in the future via class information. Examples of other pagination options might eventually include:
- TOC inclusion, page number display, and hide/display component title in book, all as options independent of one another
- Whether FM/BM component pages are numbered, where page numbering starts/restarts
- FM/Body/BM numbering style: roman numerals, arabic numerals, etc.
- Whether a component should begin on a left- or right-breaking page
In the meantime, these options can be set with CSS.