Sprint Preview: September 24–October 5

This sprint, we’ll be working on:

  • Refinements to the forthcoming glossary feature
  • Cloning and API support for glossary terms
  • User experience and accessibility improvements to the Export page
  • Continued work on user experience improvements to the webbook table of contents
  • Developing a user experience strategy for the Theme Options page to make it more intuitive and less intimidating while improving its extensibility

Sprint Preview: August 20-31

Here are some of the things we’ll be working on this sprint:

  • Various small bug fixes and tweaks on themes
  • Implementing UX improvements to the Table of Contents (book landing page and sidebar) on webbooks
  • Add functionality to clone all media files when cloning a book
  • Continuing theme conversions to Buckram

Sprint Preview: July 23–August 3

Here’s what we’ll be working on this sprint:

  • Implementing new shortcodes for existing Pressbooks content
  • Explore options to improve the UX and accessibility of the exports page
  • Continuing Shibboleth research and development
  • Releasing updated versions of our premium Baker and Christie themes with Buckram compatibility
  • Updating our premium Andreessen and Dillard Plain themes for Buckram compatibility
  • Other small bug fixes

Sprint Preview: June 25 – July 6

This sprint, we’ll be working on:

Also, we’ll be off both Mondays this sprint, as it will be Québec and Canada’s national holidays, so the Open Source call will happen on Tuesday, July 3.

Sprint Preview: April 2–13

Here’s what we will be focusing on for our first sprint of Q2:

  • Buckram development: We are working to finalize a stable release of Buckram, our book theme component library, which will include improvements to image layout, ordered lists, running content, and textboxes.
  • Pressbooks 5.x and McLuhan bug fixes: We will be working on more improvements to McLuhan related to author name display and the web table of contents.
  • Expandable content: We will be implementing a new interactive content feature — content blocks which are progressively enhanced to be expandable and collapsible in the webbook.

(Note: We’ve decided to push the development of the new version tracking feature that was planned for our past sprint to a subsequent sprint.)

Pressbooks is on Open Collective

With our sprint previews, idea board, and various other initiatives, we’re increasing our efforts to foster and engage the Pressbooks Open Source community 1. As part of this process, we have decided to set up an Open Collective account for the Pressbooks Open Source project so that our Open Source users can, if they wish to, contribute financially to the ongoing development of Pressbooks. While we are very proud of our PressbooksEDU enterprise hosting service (and it remains the best way to provide stable, ongoing financial support to the project), we recognize that this isn’t the right option for many users, and that those who still rely on Pressbooks may want a different way to contribute. If that’s you, please consider backing us on Open Collective, with either a one-time donation or a small monthly contribution. Either way, even if you’re not in a position to contribute, we’re glad to have you in our Open Source community!

  1. And if you or anyone you know wants to join our monthly Slack calls, it’s now a whole lot easier.

Declaring your plugin’s compatibility with Pressbooks

Last summer, WooCommerce introduced a new feature in version 3.2 of their core plugin: compatibility alerts for installed add-on plugins when new versions of WooCommerce became available. By adding a line to the plugin headers of a WooCommerce add-on, developers could let users know the most recent version of WooCommerce with which they’d tested their plugin.

We really liked this idea, so Dac built a similar feature into Pressbooks 5. Now, when future updates to Pressbooks show up on the plugins page of a Pressbooks, users will see whether or not their Pressbooks-specific add-ons have been tested with the latest version:

Plugin compatibility notice

If you develop plugins that extend Pressbooks functionality (we check for pressbooks in the plugin slug, name, and description), you can add Pressbooks tested up to: 5.0.0 (or whatever version string is relevant) to your plugin headers, and Pressbooks will reflect your plugin’s compatibility in the update notice. We hope this feature will give network administrators a better understanding at a glance of whether they can safely update to the latest version of Pressbooks. Of course, we still encourage thorough testing in a development or staging environment before installing a major update.

GitHub Housekeeping

A quick note from the dev team: we are working to improve our GitHub issue management. With this in mind, we’re closing stale issues which have not seen any activity in the last 60 days. This does not mean that they will not be revisited — many of them are on our roadmap, in fact! We just want to reflect what we are actually working on.

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. A mockup of the "Status & Visibility" panel for an existing chapter in Pressbooks 5.

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.