Pressbooks 5: Developer Guide

Pressbooks 5 will introduce some significant changes to the ways we store and retrieve data within the book, a new export module, modifications to two existing export modules, and some changes to the filesystem for user generated content. This post outlines these key changes and the migration paths that we’ve built in to facilitate the upgrade to Pressbooks 5.

Data Changes

Content Visibility

In Pressbooks 4.x and earlier, the visibility of content across different media is controlled by a combination of custom post metadata and core post status. For front matter, back matter and chapters, the pb_export post meta value determines whether or not they appear in exports, while their post status (draft, pending, private, or publish) determines their visibility in the webbook.

In an effort to better conform to WordPress best practices and streamline the user experience, we’re using the post status as the source of truth for whether front matter, chapters, and back matter appear in web, exports, or both. We’ve added a new web-only post status, and content visibility will now be determined as follows:

Post Status Web + REST API Exports
draft hidden hidden
web-only visible hidden
private hidden visible
publish visible visible

In terms of the user interface, we’re changing this:

A mockup of the Export Settings & Publish panels in Pressbooks 4.x.

To this:

A mockup of the Status & Visibility panel for a new chapter in Pressbooks 5.
The panel for a new chapter.
A mockup of the "Status & Visibility" panel for an existing chapter in Pressbooks 5.
The panel for a new chapter.

Note that we’re changing the primary action button from “Publish” for new content and “Update” for existing content to “Create” and “Save”, respectively.

Your front matter, back matter and chapters will be automatically updated when you visit your book after updating to Pressbooks 5.

Contributor Management

Pressbooks 4.x lets you add a single author and multiple contributing authors, editors, and translators in your Book Information and lets you add a single author for each front matter, back matter, or chapter. Pressbooks 5 imports all your existing authors (and Pressbooks users who are assigned to your book) and creates entries in a new contributor taxonomy. Then, it repopulates new relevant metadata fields with a list of contributors that match your book’s existing contributors. For example, if you have an author named Alice X and two editors named Bob Y and Eve Z, your Book Information will contain the following in Pressbooks 4.x:

Field Value
pb_author 'Alice X'
pb_editor ['Bob Y', 'Eve Z']

In Pressbooks 5, your Book Information will contain the following:

Field Value
pb_authors 'alice-x'
pb_editors ['bob-y', 'eve-z']

The values saved in Book Information are the slugs of entries in the contributor taxonomy. Also, for backwards-compatibility, the new field names are pluralized so that any third-party code that looks for the old fields will still be able to retrieve them for the time being.

You’ll be able to edit the display names of these contributors in one place — the new Contributors page, which is a standard WordPress taxonomy management page — and you’ll be able to quickly and easily select from your list of contributors to add assign authors throughout your book (if you have a book that consists of chapters with different authors, and you also want to include credits for all the authors in your Book Information, this will make maintaining that information much easier). In future releases of Pressbooks, we will be able to add metadata to contributors, including profile pictures, author websites, and more, for display on your webbook cover page or individual front matter, back matter, and chapters.

We’re also adding a new class, \Pressbooks\Contributors\, and some other related functions to retrieve arrays or formatted lists of contributors.

The migration of your book’s contributor data will happen automatically when you visit your book after updating to Pressbooks 5.

Licenses

In the same way that we’re moving contributor data to a contributor taxonomy, we’re moving the available licenses into a new license taxonomy. That way, if you need to add a custom license for your book, it will immediately be available in all chapters, front matter, and back matter as well as your Book Information. This migration will happen automatically when you visit your book after updating.

Export Changes

HTMLBook Preview

In Pressbooks 5, we’ve introduced a new HTMLBook export module as a proof of concept. We’re excited about the potential of adopting and advancing this proposed standard for the semantic representation of books on the web, and we will be actively developing our export module in the months to come. We’re also working with the creators of HTMLBook to expand and improve the standard (to begin with, we’re proposing the addition of new front matter and back matter types and of new block elements, including educational textboxes).

At this time, our HTMLBook exporter is not production-ready, but we will be using it as a testbed to refine our best practices for coding export modules in Pressbooks.

XHTML and EPUB Markup Changes

We’re making a change to the way we mark up our XHTML and EPUB exports, but only for themes that use our SCSS component library, Buckram. In Pressbooks 4.x, chapter subtitle and author elements are not wrapped in the same container as the chapter number and title:


<div class="chapter standard" id="chapter-1">

  <div class="chapter-title-wrap">

    <h3 class="chapter-number">1</h3>

    <h2 class="chapter-title">Loomings</h2>

  </div>

  <div class="ugc chapter-ugc">

    <h2 class="chapter-author">Herman Melville</h2>

    <h2 class="chapter-subtitle">The First Chapter</h2>

    <p>Call me Ishmael.</p>

  </div>

</div>

This makes it very difficult to reliably style the first page of front matter, back matter, and chapters.

In Pressbooks 5, books that use Buckram-based themes will now have the following markup:


<div class="chapter standard" id="chapter-1">

  <div class="chapter-title-wrap">

    <h3 class="chapter-number">1</h3>

    <h2 class="chapter-title">Loomings</h2>

    <h2 class="chapter-author">Herman Melville</h2>

    <h2 class="chapter-subtitle">The First Chapter</h2>

  </div>

  <div class="ugc chapter-ugc">

    <p>Call me Ishmael.</p>

  </div>

</div>

This change will only impact themes using Buckram, which include our open source Clarke theme and the premium Asimov theme (the latter only available to Pressbooks EDU or Pressbooks.com users). We are thoroughly testing these Buckram-based themes to ensure that this change does not affect existing books. If you have built a theme using Buckram, we suggest you test your theme as well once this issue has been closed.

Filesystem Changes

In Pressbooks 4.x, all export files, (S)CSS and other user-generated files are stored in subfolders of your book’s uploads directory. We’re moving them all into a pressbooks folder to prevent conflicts between our files and any other files that plugins may generate. This will happen without the need for any intervention on your part.

Pressbooks 4.5.0, Pressbooks Book 1.12.0, and Clarke 2.1.1

We tagged Pressbooks 4.5.0Pressbooks Book 1.12.0, and Clarke 2.1.1 on GitHub yesterday and deployed them across our hosted networks. Here’s what’s changed:

Pressbooks 4.5.0

NOTICE: Pressbooks >= 4.5 requires PHP 7.0 or greater.
NOTICE: Pressbooks >= 4.5 requires WordPress 4.9.1.

  • [FEATURE] Switching to a new theme will now update some PDF theme options to match the theme’s values (see #456, #984).
  • [FEATURE] Add initial support to PDF and Ebook theme options for themes which skip lines between paragraphs by default (see #985).
  • [CORE ENHANCEMENT] Use standard build tools package pressbooks-build-tools for asset handling, upgrade Stylelint (see #1000).
  • [CORE ENHANCEMENT] Require PHP 7.0 or greater (see #935, #987).
  • [CORE ENHANCEMENT] Add exclude and include support to Pressbooks\Utility\rcopy()(see #990).
  • [CORE ENHANCEMENT] Improve Theme Lock feature in preparation for Pressbooks 5.0 (see #995).
  • [CORE ENHANCEMENT] Add Prettier for SCSS and JS formatting (see #991).
  • [CORE ENHANCEMENT] Optimize subsection parsing (see #992).
  • [CORE ENHANCEMENT] Optimize __UNSET__ style (see #999).
  • [CORE ENHANCEMENT] Optimize unit testing (see #997).
  • [FIX] Replace ‘Sites’ with ‘Books’ throughout Pressbooks interface (see #993).
  • [FIX] Replace ‘Exotic formats’ with ‘Other formats’ on the Export page (see #996).
  • [FIX] Fix bug related to #42574 which prevented widget editing on the root blog (#998).
  • [FIX] Fix type mismatch in \Pressbooks\Licensing class (see 23ee4ff)
  • [FIX] Fix typo in EPUB exporter — the acronym is OEBPS (Open eBook Publication Structure) (props @bdolor; see #988).

Pressbooks Book 1.12.0

  • [CORE ENHANCEMENT] Updated Ekatra fonts (for the Gujarati language) to the latest version.
  • [FIX] Fixed an issue where invisible parts would appear in the webbook TOC (props to Michael Shiflet for the bug report).

Clarke 2.1.1

  • Fixed incorrect fonts in description.

Pressbooks 4.4.0, Pressbooks Book 1.11.0, Clarke 2.1.0, and Donham 1.7.0

We tagged Pressbooks 4.4.0Pressbooks Book 1.11.0, Clarke 2.1.0 and Donham 1.7.0 on GitHub today and deployed them across our hosted networks. Here’s what’s changed:

Pressbooks 4.4.0

NOTICE: Pressbooks >= 4.4 requires WordPress 4.9.

  • [FEATURE] You can now assign Thema subject categories to your book on the Book Information page (see #978).
  • [FEATURE] Part slugs are now editable (props to @colomet for the suggestion; see 3f5eca2).
  • [CORE ENHANCEMENT] Pressbooks now uses WordPress’ included CodeMirror scripts and styles for our Custom Styles editor (see #980).
  • [CORE ENHANCEMENT] Added the pb_global_components_path filter which lets book themes override the global components path to point to their own bundled components libraries (see #982).
  • [CORE ENHANCEMENT] Added the pb_pre_export action to allow tweaks prior to an export routine (see 5302eea).
  • [CORE ENHANCEMENT] Our app() function now matches Laravel 5.4’s function signature (see cdcb9e8).
  • [FIX] Importing a Word document with multiple images now works properly (props to @rootl for the bug report; see #288 and #977).
  • [FIX] Chapters will now correctly inherit their book’s license in the API (see #979).
  • [FIX] Chapters will no longer show raw content in the API if they are password-protected (see #975).
  • [FIX] Uploading an image to the user catalog no longer causes an error (props to @emasters for the bug report; see #983).

Pressbooks Book 1.11.0

  • [FEATURE] Add parameter to pressbooks_copyright_license() to allow hiding custom copyright license (see #50).
  • [CORE ENHANCEMENT] Remove WordPress generator meta tag (see 6c621ad).

Clarke 2.1.0

  • Preparations for Book 2.0 compatibility.

Donham 1.7.0

  • Preparations for Book 2.0 compatibility.

Pressbooks 4.3.5 and Pressbooks Book 1.10.5

We tagged Pressbooks 4.3.5 and Pressbooks Book 1.10.5 on GitHub today and are now deploying them across our hosted networks. Here’s what’s changed:

Pressbooks 4.3.5

NOTICE: Pressbooks >= 4.3.3 requires WordPress 4.8.2.
NOTICE: Users of the Pressbooks Custom CSS theme must upgrade to Pressbooks Custom CSS 1.0 for compatibility with Pressbooks >= 4.3.0.

  • [CORE ENHANCEMENT] Use Laravel Container instead of Pimple as our service container; add Laravel Blade support for future templated outputs (see #831, #962, and #970).
  • [FIX] Content imported from EPUB is now ordered by spine order instead of manifest order (props to @hakkim-pits; see #442 and #968).
  • [FIX] Custom styles are no longer sanitized in ways that improperly encode characters (see #972).
  • [FIX] Sanitize body font size PDF theme option as a float instead of an integer to allow more size options (see #969).
  • [FIX] home_url is now used instead of site_url when linking to front-end content (see #971; reference: roots/bedrock#316).
  • [FIX] Shortcodes will now be cloned as is to preserve more footnote and LaTeX data (see #973).
  • [FIX] Special characters in a book title will no longer lead to filename issues under certain circumstances (see #974).

Pressbooks Book 1.10.15

  • [FIX] Added cache busting to ensure that custom styles are loaded after save (see #46).

Pressbooks 4.3.4 and Pressbooks Book 1.10.4

We tagged Pressbooks 4.3.4 and Pressbooks Book 1.10.4 on GitHub today and are now deploying them across our hosted networks. Here’s what’s changed:

Pressbooks 4.3.4

NOTICE: Pressbooks >= 4.3.3 requires WordPress 4.8.2.
NOTICE: Users of the Pressbooks Custom CSS theme must upgrade to Pressbooks Custom CSS 1.0 for compatibility with Pressbooks >= 4.3.0.

  • [CORE ENHANCEMENT] The user catalog title can now be changed via the pb_catalog_titlefilter (props to @monkecheese; see #961).
  • [CORE ENHANCEMENT] SCSS variables from theme options will now be passed to the SCSS compiler as key/value pairs rather than by building SCSS in PHP (see #782 and #963).
  • [FIX] Fixed an issue where the PDF margins theme option was not being applied properly.
  • [FIX] Fixed a conflict between the updated Pressbooks LaTeX module and third-party renderers (props to @monkecheese; see #958 and #959).
  • [FIX] The publication date should now save properly, regardless of book language (thanks to @thomasdumm for the bug report; see #965 and #966).

Pressbooks Book 1.10.4

  • [FIX] Fixed an issue where part numbering would not reset properly in Prince if the part was the book’s first content (see #45).

Pressbooks 4.3.3, Pressbooks Publisher 3.1.3 and DocRaptor for Pressbooks 2.1.0

We tagged Pressbooks 4.3.3, Pressbooks Publisher 3.1.3, and DocRaptor for Pressbooks 2.1.0 and deployed them across our hosted networks today. Here’s what’s changed:

Pressbooks 4.3.3

NOTICE: Pressbooks 4.3.3 requires WordPress 4.8.2.

  • [CORE ENHANCEMENT] The Pressbooks plugin is now self-updating — GitHub Updater is no longer required (see #897 and #954).
  • [CORE ENHANCEMENT] Error logs from export routines can be emailed to an array of email addresses supplied via the pb_error_log_emails filter (see #956).
  • [CORE ENHANCEMENT] Images in cloned or imported books can now be properly edited using the WordPress image editor (see #920 and #949).
  • [FIX] We’ve implemented a better solution for the PDF profile bug (see #951, #952).
  • [FIX] URLs like /catalog/page/1 will no longer attempt to load user catalogs (see #953).

Pressbooks Publisher 3.1.3

  • [FIX] Removed duplicate footer markup (thanks to @jeremyfelt; see #11).

DocRaptor for Pressbooks 2.1.0

  • [CORE ENHANCEMENT] The DocRaptor for Pressbooks plugin is now self-updating — GitHub Updater is no longer required (see #19, #20, and #21).

 

Our new roadmap

At the start of 2017, we established a development roadmap for Pressbooks to guide our work through the coming year. This past week we had the opportunity to review and reflect on that roadmap during our retreat at Pressbooks HQ, and you can see our new roadmap here.

2017: Year of Core

I want to highlight a few of our accomplishments from the past nine months (you’ll see them crossed out on the old roadmap). In retrospect, our clear focus over the past nine months was improving Pressbooks’ core technology. When Dac came back, having a second developer let us expand upon my efforts in recent years to standardize our development processes under the hood. We now use consistent coding standards across all of our open source projects, and we have adopted a standardized build process for admin and front end assets. We have expanded our code coverage on the core Pressbooks plugin, and continue to do so with every release. These improvements let us work more efficiently and give open source contributors a clear framework within which to contribute to the Pressbooks ecosystem.

Our most significant core enhancement is our new REST API, built on the WordPress Core REST API infrastructure. This is the engine that powers our new cloning tool, and we will be making use of it in other areas over the next year. We’re also extremely excited to see what the Pressbooks Open Source community does with an API for books. If you are building something with it, let us know.

2018: Year of the Author

The roadmap for our next year has a new focus: improving Pressbooks for authors. There are a number of editing features that we included on our last roadmap that didn’t make the cut, and our goal for the next year is to fill as many of these gaps in the Pressbooks authoring toolset as we can. This includes:

  • Broadening our support for math, interactive content, video and audio across all formats (with graceful fallbacks in static formats like PDF)
  • Adding support for multiple contributors: authors, editors, translators and more
  • Adding indexing and glossary support

And more! Take a look at our new roadmap to see our comprehensive plans for improving Pressbooks’ authorship and editing tools, as well as all other aspects of the project.

I’m very excited about our accomplishments since January 2017, and I’m looking forward to building on them over the next year. Thanks to Apurva, Dac, Hugh, Liz, and Zoe for making Pressbooks such a productive team!

Pressbooks 4.3.1 and Pressbooks Book 1.10.3

We tagged Pressbooks 4.3.1 and Pressbooks Book 1.10.3 on GitHub today and deployed them across our hosted networks. Here’s what’s changed:

Pressbooks 4.3.1

NOTICE: Pressbooks 4.3.1 requires WordPress 4.8.1.
NOTICE: Users of the Pressbooks Custom CSS theme must upgrade to Pressbooks Custom CSS 1.0 for compatibility with Pressbooks 4.3.1.

  • [CORE ENHANCEMENT] Added a debugging switch to Custom Styles (see #946).
  • [FIX] Resolved an issue where some fonts would not be loaded properly during the PDF export routine (see #944 and #945).
  • [FIX] Updated routines that use XPath for compatibility with HTML5, resolving some issues with multi-level TOC and EpubCheck validation (see #947).

Pressbooks Book 1.10.3

  • [FIX] Fix some issues with Biblical Hebrew, Devanagari, and Turkish fonts.

Pressbooks 4.3, Pressbooks Book 1.10.2, Pressbooks Custom CSS 1.0, and Pressbooks Publisher 3.1.2

We tagged Pressbooks 4.3.0, Pressbooks Book 1.10.2, Pressbooks Custom CSS 1.0.0, and Pressbooks Publisher 3.1.2 on GitHub yesterday, and we’re deploying them across our hosted networks today. Here’s what’s changed:

Pressbooks 4.3

NOTICE: Pressbooks 4.3.0 requires WordPress 4.8.1.
NOTICE: Users of the Pressbooks Custom CSS theme must upgrade to Pressbooks Custom CSS 1.0 for compatibility with Pressbooks 4.3.

  • [FEATURE] Custom Styles: Navigate to AppearanceCustom Styles on your book’s dashboard to add custom CSS or SCSS to any book theme (see #658, #912, #925, #937, #938, #940, #941, and #942).
  • [ENHANCEMENT] Expanded the license property of the /metadata endpoint to include a human-readable license name and custom license text (if present) (see #934 and #936).
  • [ENHANCEMENT] Added the book’s short description to the /metadata endpoint as a disambiguatingDescription (see #930 and #932).
  • [ENHANCEMENT] Clarified errors when trying to clone a book from Pressbooks < 4.1 (see #914and #931).
  • [ENHANCEMENT] Renamed several action and filter hooks and deprecated the old versions (see #926).
  • [FIX] Fixed an issue which would prevent super administrators without any books on a network from accessing the cloning page (see #913 and #933).
  • [FIX] Fixed a regression which blocked the use of custom LaTeX renderers (props to @monkecheese; see #928).

Pressbooks Book 1.10.2

  • [ENHANCEMENT] Updated to version 2.1 of pressbooks/mix.
  • [FIX] The cover page now displays the subtitle from Book Information as the book’s subtitle, rather than the tagline.

Pressbooks Custom CSS 1.0.0

NOTICE: Pressbooks Custom CSS 1.0.0 requires Pressbooks 4.3.0.

  • [ENHANCEMENT] Custom CSS functionality is now included in this theme (see #2).

Pressbooks Publisher 3.1.2

  • [FIX] Prevented Pressbooks Publisher’s wrapper from being added to the user catalog page.

Pressbooks 4.2 and Pressbooks Book 1.10.1

We tagged Pressbooks 4.2.0 and Pressbooks Book 1.10.1 on GitHub today and we’re deploying them across our hosted networks tomorrow. Here’s what’s changed:

Pressbooks 4.2

NOTICE: Pressbooks 4.2 requires WordPress 4.8.1.

  • Feature: Full-sized images will be used where possible in Print PDF exports to ensure that exported PDFs meet image resolution requirements (see #894, #898 and #900).
  • Feature: WXR import and clone operations will now attempt to fetch original images from the source book in addition to the scaled/cropped version in the book content (see #895 and #902).
  • Feature: Content on the organize page now has a View link as will as Edit and Trash (see #840and #893).
  • Enhancement: The Masterminds HTML5 parser is now used instead of \DOMDocument where possible for improved error handling and compatibility with HTML5 elements (see #889 and #896).
  • Enhancement: Unnecessary HTTP calls have been removed from export routines (see #899).
  • Enhancement: Installation instructions are now linked from the readme file instead of being included (see #891 and #892).
  • Fix: Resolved some inconsistencies with custom copyright notice and copyright year display (see #922).
  • Fix: Clone operations now have a 5-minute time limit which should reduce the occurrence of timeouts (props to @bdolor for the bug report; see #903 and #904).
  • Fix: Visiting /catalog on the root site no longer causes an error (see #905).
  • Fix: Pressbooks LaTeX settings no longer appear on the root site’s dashboard (see #910 and #911).
  • Fix: The Organize page now supports all post statuses (see #915).
  • Fix: Fixed an issue where the Pressbooks News dashboard widget would be cached in the wrong language (see #918 and #921).
  • Fix: Removed some unused code from the PB LaTeX symbiont (props to @jeremyfelt; see #923).

Pressbooks Book 1.10.1

  • Fix: Consistent display of custom copyright notice (see #38).