Pressbooks 3.6.0

Pressbooks 3.6.0 just went live on Pressbooks.com and all of our other production networks. Here’s what’s changed:

  • Requires WordPress 4.5.3.
  • Feature: Structural SCSS and supports are in place for the new book theme model (see https://pressbooks.org/core/2016/05/16/rethinking-book-themes/).
  • Feature: Clarke 2.0 has been rebuilt on the new book theme model (see https://pressbooks.com/themes/clarke).
  • Feature: Themes built on the new book theme model can display publisher logos on the title page via add_theme_support( 'pressbooks_publisher_logo', [ 'logo_uri' => $logo_uri ] ).
  • Feature: Themes built on the new book theme model define support for global typography using add_theme_support( 'pressbooks_global_typography', [ $language_codes ] ).
  • Feature: Custom post types, built-in taxonomies and custom taxonomies can now be imported from a Pressbooks or WordPress XML file using the filters pb_import_custom_post_types and pb_import_custom_taxonomies (props to @monkecheese).
  • Feature: Filter hooks have been added which allow content to be appended to front matter, chapters and back matter via pb_append_front_matter_content, pb_append_chapter_content and pb_append_back_matter_content(props to @monkecheese).
  • Feature: Network administrators can now clear all of a book’s exports (this is useful for testing).
  • Enhancement: The Export page is now responsive.
  • Enhancement: script.js is no longer required for Prince exports (if the the file is not there it will no longer trigger an error).
  • Enhancement: The <base href=""> tag has been removed from XHTML outputs, which should make these files more functional in some cases (props to @bdolor).
  • Fix: Search and Replace is now accessible to book administrators, not just network administrators.
  • Fix: The broken Forum link in the Pressbooks menu has been replaced with a link to our Help page.

Rethinking Book Themes

Pressbooks has built book themes the same way for quite a while, with the only significant change being the switch from CSS to SCSS in Pressbooks 3.0. Shown below is the structure for one of our open-source themes, Clarke (with a couple of omissions that aren’t relevant to this post).

├── export
│   ├── epub
│   │   ├── images
│   │   │   ├── asterisk.png
│   │   │   ├── em-dash.png
│   │   ├── style.scss
│   ├── prince
│   │   ├── images
│   │   │   ├── em-dash.png
│   │   ├── script.js
│   │   ├── style.scss
├── _fonts-epub.scss
├── _fonts-prince.scss
├── _fonts-web.scss
├── _mixins.scss
├── functions.php
├── style.css
├── style.scss
├── theme-information.php

We’re in the midst of a significant re-think of how we build themes, and here’s what it looks like so far.

├── assets
│   ├── images
│   │   ├── em-dash.png
│   │   ├── epub
│   │   │   ├── asterisk.png
│   ├── scripts
│   │   ├── prince
│   │   │   ├── script.js
│   ├── styles
│   │   ├── epub
│   │   │   ├── _fonts.scss
│   │   │   ├── style.scss
│   │   ├── prince
│   │   │   ├── _fonts.scss
│   │   │   ├── style.scss
│   │   ├── web
│   │   │   ├── _fonts.scss
│   │   │   ├── style.scss
│   │   ├── components
│   │   │   ├── _accessibility.scss
│   │   │   ├── _alignment.scss
│   │   │   ├── _colors.scss
│   │   │   ├── _elements.scss
│   │   │   ├── _elements-special.scss
│   │   │   ├── _media.scss
│   │   │   ├── _structure.scss
│   │   │   ├── _titles.scss
│   │   │   ├── _toc.scss
├── functions.php
├── style.css
├── theme-information.php

All three core outputs now keep their assets in the assets folder, with shared assets going in the directory roots of assets/fonts (when needed), assets/images, assets/scripts and assets/styles. We used to keep the uncompiled web stylesheet in the theme root along with a compiled version, but this caused some confusion. The style.css file in the theme root was never loaded in the web view; since Pressbooks 3.0, we’ve always used a freshly compiled version which is generated when the user changes themes or changes their theme options. But WordPress requires that theme information be stored in the file header of style.css. Our practice moving forward will be to use the style.css file in the root for theme information only, and keep a style.scss file for the web book in assets/styles/web/.

Each of the files in assets/styles/components imports a global components file or file(s) and a variables file for the relevant item(s) from the Pressbooks plugin’s assets/book/styles/ directory (which is loaded by our SCSS compiler). For example, assets/styles/components/_elements.scss might contain the following:

// Elements

$orphans: 3 !default;

// Change variables above this line, using the !default flag to allow overrides.
@import 'variables/elements';

// Add custom SCSS below these imports and includes.
@import 'components/elements/links';
@import 'components/elements/blockquotes';
@import 'components/elements/body';
@import 'components/elements/headings';
@import 'components/elements/lists';
@import 'components/elements/miscellaneous';
@import 'components/elements/paragraphs';
@import 'components/elements/tables';
@include tables();

In this hypothetical theme, all of the default element styles have been imported but the theme developer has changed the orphan property from 1 to 3. (Using the SCSS !default flag allows a variable like this to be overridden by the book user once we overhaul our theme options.)

All of these component files are imported into the EPUB, PDF and web style.scss files, like so:

$type: 'prince';

@import 'fonts';
@import '../components/alignment';
@import '../components/colors';
@import '../components/elements';
@import '../components/specials';
@import '../components/media';
@import '../components/titles';
@import '../components/structure';
@import '../components/toc';

So now we have a book theme with a more coherent structure, comprehensive default variables and an easy method to override them, and lots of possibilities.

We have lots to do to move forward with the implementation of this new theme structure (including backwards compatibility). You can follow along on the theme-structure branch to observe or participate in the implementation process. If you want to get involved in the discussion of these changes, feel free to join in on the relevant GitHub issue!

Pressbooks 3.5.2

Pressbooks 3.5.2 just went live on Pressbooks.com and all of our other production networks. Here’s what’s changed:

  • Feature: Login screen logo and color scheme can now be changed via filters (see pressbooks@d09a104).
  • Enhancement: Google Fonts are now requested over https under all circumstances.
  • Enhancement: Added some functionality to the Disable Comments plugin (props to @bdolor).
  • Fix: Imports will no longer fail in certain environments (props to @monkecheese for the bug fix).
  • Fix: Subsection titles are now properly sanitized for XHTML output.

Pressbooks 3.5.1

Pressbooks 3.5.1 just went live on Pressbooks.com and all of our other production networks. Here’s what’s changed:

  • Requires WordPress 4.5.2.
  • Fixed: Resolved a formatting issue on the Export page (props to @bdolor).
  • Under the Hood: Added anchor, superscript and subscript buttons to core MCE routines (eliminating dependencies).

Pressbooks 3.5

Pressbooks 3.5 just went live on Pressbooks.com and all of our other production networks. Here’s what’s changed:

  • Feature: Search and Replace functionality has been rebuilt and more closely integrated with Pressbooks core.
  • Feature: Pressbooks plugins (specifications forthcoming) can now be activated at the book level by book administrators.
  • Fixed: Some image asset paths were updated.
  • Fixed: Default mPDF options were updated.
  • Under the Hood: Pressbooks now bundles the WordPress API feature plugin (more to come on this front).
  • Under the Hood: Our namespace is now \Pressbooks.