[Implementersâ doc] [Authorsâ info]
Depending on the platform and version youâre developing for, contents must be injected into:
Indeed, we must provide authors with a reliable context in which their styles and scripts are scoped.
Since we must take viewport units into account, especially vh
(viewport height), at least the top and bottom margins must be set on this container, and not inside it.
You may also want to set left and right margins on this container so that all margins are equal in the two-column view.
Finally, on larger screens, youâll have to set dimensions on this container so that it doesnât become too large.
Please note you must deal with the background-color
outside this container, especially as the user can set reading modes (night, sepia, etc.). In other words, it must be synced with this user setting so that the entire screen is the same background-color
.
As a friendly reminder, you can allow transparency for the iframe if youâre using one. That should help deal with background-color
at the global level.
<iframe src="source.xhtml" allowtransparency="true"></iframe>
Then set the --RS__backgroundColor
variable to transparent
in ReadiumCSS-base.css
, although you will have to modify the current user settings stylesheet so that it can work this way.
Contents are paginated using CSS multicolumns, for several reasons:
Pagination is a single column by default, which means the Reading System/app is responsible for its responsiveness.
For instance, if the reader is using a tablet in landscape mode and you want to display two âpagesâ/columns automatically, you have to tell ReadiumCSS by applying --USER__colCount: 2;
to the :root
element â if itâs not already set by this user of course.
This is a major change from version 1, as the responsive aspect of pagination was built-in.
Since we must inject contents and columns are implemented at the :root
level (i.e. html
), the Reading System owns the entire styling for this selector.
Font size is an important metric since the responsive design relies entirely on rem
(root em
) so this style must be enforced by any means necessary.
For body
, we own:
overflow
;(min-|max-)width
, (min-|max-)height
, box-sizing
;margin
and padding
.You can control horizontal margins in several ways:
column-gap
and padding
for :root
;column-gap
and margin
for the web view/chrome view/iframe;padding
for :root
and/or body
.Please note that when using padding
, you must take it into account when sizing :root
and/or body
. Their widths contain the padding set for the element.
This is the model youâre dealing with. Itâs been simplified in version 2 in order to be more reliable.
Page gutters are part of body
(--RS__pageGutter
), hence --USER__lineLength
(or --RS__defaultLineLength
if no user preference is set). Contents are centered in :root
using the auto
value for body
margins.
By default, --RS__pageGutter
is set to 0
. You can set it as you wish, but take into account it will substract from --USER__lineLength
.
Please note those variablesâ value can be redefined using media queries. You donât need to redeclare entire declarations.
--RS__colWidth
The optimal columnâs width. We set it to 100%
(100vh
in vertical-writing) for a single-column for Safari â otherwise it wonât fragment content, and auto
for multiple so that the column-count can be prioritized.
--RS__colCount
The optimal number of columns (depending on the columnsâ width).
--RS__colGap
The gap between columns. It must be set in pixels so that it wonât resize with font size.
You must account for this gap when scrolling.
--RS__pageGutter
The inline (horizontal by default, vertical in vertical-writing) page margins. It must be set in pixels so that it wonât resize with font size.
--RS__defaultLineLength
The default line-length when none is set by the user. It should be set in rem
in order to take :root
âs font-size
as a reference, whichever the body
âs font-size
might be.
--USER__lineLength
The line-length set by the user. It can be set in any unit CSS property max-width
accepts.
The pagination model will take care of itself if the correct dir
attribute is set on html
and body
.
In other words, if dir="rtl"
is set for both elements, the column-progression will be automatically reversed.
What implementers need to do:
page-progression-direction
for the spine
item;<dc:language>
items;xml:lang
and/or lang
attribute if itâs missing in XHTML documents;dir="rtl"
attributes if theyâre missing for both html
and body
in XHTML documents;page-progression-direction
(in RTL, next resource is on the left, previous is on the right);text-align
).The current implementation is limited to the following combinations:
Language | IANA tag | page-progression-direction | dir attribute |
---|---|---|---|
Arabic | ar | RTL | rtl |
Farsi (Persian) | fa | RTL | rtl |
Hebrew | he | RTL | rtl |
IANA Language Subtag registery.
We may add others at some point in the future. Please feel free to report the languages or scripts missing in this mapping. Please bear in mind a list of default (preferably system) fonts will greatly help to add support for those languages and scripts. See Default Fonts.
Test files can be retrieved from the Readium CSSâ i18n-samples OPDS feed.
As explicitly stated in CSS Writing Modes Level 3:
As a special case for handling HTML documents, if the
:root
element has a<body>
child element, the principal writing mode is instead taken from the values ofwriting-mode
anddirection
on the first such child element instead of taken from the root element.
What this means is that the dir
attribute (or the direction
CSS property) set for body
will override the one set for html
. Unlike most other CSS properties, which donât impact the parent element, the dir
attribute (or the direction
CSS property) propagates in this very specific case:
<html dir="ltr">
<body dir="rtl">
<!-- dir="rtl" should be used. -->
html {
direction: ltr;
}
body {
direction: rtl;
/* rtl propagates to html and overrides ltr.
You can think of it as a JS event bubbling up if that makes more sense. */
}
We MUST consequently force the direction for all documents in the publication, and canât manage ltr
documents in a rtl
publication.
Note: While this isnât necessarily the case in practice, in Blink, Gecko/Quantum and Webkit, and you can emulate a reversed column-progression for ltr
documents in a rtl
publication, this behavior may change in the future.
When publications are in Chinese, Japanese, Korean, and Mongolian, and laid out with a vertical-*
writing mode, we must switch to a different model of pagination.
Indeed, columns are automatically laid out on the y-axis
(vertical) with such writing modes, and the behavior of multi-column in orthogonal flows has been deferred to CSS Writing Modes Level 4. This means we must stick to a single column, and canât support several columns â they are stacked on top of one another, which is not what is expected.
This also implies the scroll progression is vertical, hence horizontal navigation/swipes have to be re-mapped on this y-axis
. You may also want to disable animations so that it doesnât feel disorienting to users.
We consequently use a âFragmented Modelâ, as it differs significantly from the âPagination Modelâ, especially the column-axis.
One can think of the fragmented model as the single page model rotated 90% clockwise.
Due to the limitations listed above, implementers may want to use their own model. It is not uncommon to handle vertical writing pagination programmatically, as it can be done relatively easily and efficiently thanks to characters being (mostly) monospace e.g. scrolling the viewport by an offset based on these characters.
Since pagination is the default view, if you donât want to use this model and implement yours, you can set --RS__disablePagination: readium-noVerticalPagination-on
on the :root
(html
) element.
What implementers need to do:
page-progression-direction
for the spine
item;<dc:language>
items;xml:lang
and/or lang
attribute if itâs missing in XHTML documents;Here is the correct mapping for combinations resulting in the vertical-*
writing mode:
Language | IANA tag | page-progression-direction | Writing-mode |
---|---|---|---|
Chinese | zh | RTL | vertical-rl |
Chinese (Traditional) | zh-Hant | RTL | vertical-rl |
Chinese (Taiwan) | zh-TW | RTL | vertical-rl |
Chinese (Hong Kong) | zh-HK | RTL | vertical-rl |
Korean | ko | RTL | vertical-rl |
Japanese | ja | RTL | vertical-rl |
Mongolian | mn-Mong | LTR / Default / None | vertical-lr |
IANA Language Subtag registery.
Test files can be retrieved from the Readium CSSâ i18n-samples OPDS feed.
If a publication doesnât need to be laid out in a vertical-*
writing mode, the default pagination model must be used.
There are still specific styles for CJK Horizontal to load though.
Here is the correct mapping for combinations resulting in the horizontal-tb
writing mode:
Language | IANA tag | page-progression-direction | Writing-mode |
---|---|---|---|
Chinese | zh | LTR / Default / None | horizontal-tb |
Chinese (Simplified) | zh-Hans | LTR / Default / None | horizontal-tb |
Chinese (Taiwan) | zh-TW | LTR / Default / None | horizontal-tb |
Chinese (Hong Kong) | zh-HK | LTR / Default / None | horizontal-tb |
Korean | ko | LTR / Default / None | horizontal-tb |
Japanese | ja | LTR / Default / None | horizontal-tb |
Mongolian | mn-Cyrl | LTR / Default / None | horizontal-tb |
IANA Language Subtag registery.
As explicitly stated in CSS Writing Modes Level 3:
As a special case for handling HTML documents, if the
:root
element has a<body>
child element, the principal writing mode is instead taken from the values ofwriting-mode
anddirection
on the first such child element instead of taken from the root element.
What this means is that the writing-mode
declared for body
will override the one declared for html
. Unlike most other CSS properties, which donât impact the parent element, writing-mode
propagates in this very specific case:
html {
writing-mode: horizontal-tb;
}
body {
writing-mode: vertical-rl;
/* vertical-rl propagates to html and overrides horizontal-tb.
You can think of it as a JS event bubbling up if that makes more sense. */
}
We MUST consequently force the writing-mode
for all documents in the publication, and canât manage horizontal-tb
documents in a vertical-rl
publication.
Weâve designed two extras for pagination:
The HTML5 patch deals with:
widows
, orphans
and page-break
);abbr
and wbr
.You can use it with or without pagination, it should not make any difference.
Safeguards deal with:
img
, svg
, audio
, video
);Once again, you can use it with or without pagination, it should not make any difference.
--RS__maxMediaWidth
The max-width
for media elements i.e. img
, svg
, audio
and video
.
--RS__maxMediaHeight
The max-height
for media elements i.e. img
, svg
, audio
and video
.
--RS__boxSizingMedia
The box model (box-sizing
) you want to use for media elements.
--RS__boxSizingTable
The box model (box-sizing
) you want to use for tables.