Skip to content

Latest commit

 

History

History
185 lines (114 loc) · 7.21 KB

CSS02-quickstart.md

File metadata and controls

185 lines (114 loc) · 7.21 KB
Raw

Quickstart

[Implementers’ doc]

Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides styles for reflowable text:

  • a CSS normalize for EPUB contents;
  • paged and scrolled views;
  • default styles;
  • reading modes (night, sepia, etc.);
  • themes;
  • user settings.

Note: Readium CSS stylesheets were not designed and should not be used for fixed-layout EPUB, nor other file formats like FB2, PRC, Mobi, TEI, etc.

Important info

TL;DR: use the stylesheets in the css/dist folder if you don’t need to customize Readium CSS. All the flags and variables can then be taken at face value in the docs.

  • The src files, which are modules, can’t be used AS-IS. They indeed have to be processed by PostCSS to create dist stylesheets.
  • By default, those modules are daisy-chained and compiled into 3 dist stylesheets:
    1. ReadiumCSS-before.css;
    2. ReadiumCSS-default.css (for unstyled ebooks);
    3. ReadiumCSS-after.css.
  • We’re currently managing RTL and CJK (including horizontal and vertical writing) scripts using specific dist stylesheets:
    1. Right to Left stylesheets are distributed in an rtl folder;
    2. CJK horizontal stylesheets are distributed in an cjk-horizontal folder;
    3. CJK vertical stylesheets are distributed in an cjk-vertical folder.
  • The build process is currently subpar as it has been designed for our default and must be changed entirely if you want to process and use modules directly – which would make sense with HTTP2 for instance.

How To

Inject ReadiumCSS stylesheets into the <head> of (X)HTML documents.

  1. ReadiumCSS-before.css
  2. Authors’ stylesheet(s) or ReadiumCSS-default.css for unstyled publications
  3. ReadiumCSS-after.css

Check the Stylesheets order doc for further details.

For RTL, you would then have to load the stylesheets in the rtl folder. Same for CJK. Check the “Internationalization” doc for guidance.

By default, we inject all stylesheets on load and rely on custom properties (a.k.a. CSS variables) set on html to apply user settings.

Customize

ReadiumCSS ships with a ReadiumCSS-config.css file you can use to customize it a little bit. It allows implementers to choose selectors for the user settings’ flags.

In order to provide this customization, we use custom selectors, which will hopefully become standards implemented at some point, but require PostCSS at the moment. Consequently, you’ll have to rebuild all dist stylesheets if you’re changing this file.

Flags for user settings

By default, we are using flags in the form of CSS variables to manage reading modes and user settings. But you might want to customize those flags in order to use custom attributes (data-*) or good old CSS classes.

A complete list of flags can be found in the User preferences doc.

As an example, if you want to use a CSS class for night mode, it could look like:

@custom-selector :--night-mode .night-mode;

And if you want to use custom attributes for advanced settings, it could look like:

@custom-selector :--advanced-settings [data-settings="advanced"];

Both would then have to be appended to html at runtime.

Once again, you must rebuild dist stylesheets.

Add and remove modules

We have to add and remove modules depending on the language/script of the publication so this need is covered out of the box.

In the css/src folder, you’ll find all the needed stylesheets you will process to css/dist. Those stylesheets contain a list of imports e.g. for ReadiumCSS-before.css:

@import "../ReadiumCSS-config.css";
@import "modules/ReadiumCSS-base.css";
@import "modules/ReadiumCSS-day_mode.css";
@import "modules/ReadiumCSS-fonts.css";
@import "modules/ReadiumCSS-html5patch.css";
@import "modules/ReadiumCSS-safeguards.css";

As a consequence, modules you want to use have to be listed in those -before and -after files. Then rebuild them using PostCSS.

Additional user settings MUST be added to the user-settings-submodules folder, and make the required flag clear, if applicable.

Please remember to take the cascade into account, as issues might arise just because the order has been changed or modules moved from -before to -after – in which case we won’t be able to reproduce and debug an issue if we don’t know this important detail. See Stylesheets order doc for further details.

Reading System variables

If you want to change the name of --RS__ prefixed variables, you will have to change it in every module.

User settings variables

If you want to change the name of --USER__ prefixed variables, you will have to change it in every module.

Build dist stylesheets

First, please make sure you have node.js installed. If you don’t, go download it on the official page.

Then navigate to the readium-css folder in your terminal and type:

npm install

This will install all dependencies needed to build dist stylesheets.

Once you have customized src files, in the terminal type:

npm run-script build

This will rebuild all dist stylesheets in their specific folder.

Options

Other scripts are available:

  • build:ltr for default stylesheets (Left to Right);
  • build:rtl for Right to Left stylesheets;
  • build:cjk for CJK scripts;
  • build:vertical for CJK and the Mongolian scripts in vertical writing.

Additional info

Further details about the build and test processes can be found in the npm doc.

Manage User Settings

Currently, user settings are managed by setting CSS variables at the :root level (html element).

Flags

At the top of each user settings submodule, you will find the required flag for the preference.

This flag is needed for the setting to work.

User variables

All settings can be set using --USER__ prefixed variables. Set those properties for html and the cascade will automatically do its job.

To set a variable:

var root = document.documentElement || document.getElementById("iframe-wrapper").contentWindow.document.documentElement; 

root.style.setProperty("--USER__var", "value");

To remove a variable:

var root = document.documentElement || document.getElementById("iframe-wrapper").contentWindow.document.documentElement; 

root.style.removeProperty("--USER__var");

Please note you must implement a fallback strategy if you want to support Internet Explorer 11 and early versions of Microsoft Edge.

Example

To change hyphenation and justification you would do the following:

root.style.setProperty("--USER__advancedSettings", "readium-advanced-on");
root.style.setProperty("--USER__textAlign", "justify");
root.style.setProperty("--USER__bodyHyphens", "auto");

Of course this example is simplistic. You could for instance create an helper to set multiple properties at once.


## Create Themes

In this model, themes are a set of user settings you can store and retrieve. Add the properties to `html` and you get a theme.

Check the [User Preferences doc](../docs/CSS12-user_prefs.md) for a list of available user variables.