Paged.js: Paginating content (and making books) in browser

There are several ways to extend the rendering of Paged.js. Selecting the best method will depend on how the code will be called and what it needs to access.

When creating a script or library that is specifically aimed at extending the functionality of paged.js, it is best to use hooks and a handler class.

Paged.js has various points in the parsing of content, transforming of CSS, rendering, and layout of HTML that you can hook into and make changes to before further code is run.

A handler is a JavaScript class that defines functions that are called when a hook in Paged.js is ready to defer to your code. All of the core modules for support of paged media specifications and generated content are implemented as handlers. To create your own handler, you extend this same handler class.

class MyHandler extends Paged.Handler {
    constructor(chunker, polisher, caller) {
        super(chunker, polisher, caller);
    }
}

The handler also exposes the underlying tools for fragmenting text ( Chunker ) and transforming CSS ( Polisher )—see below.

Within this class, you can define methods for each of the hooks, and specify when they will be run in the code. A return that is asynchronous will delay the next code using await .

class MyHandler extends Paged.Handler {
    constructor(chunker, polisher, caller) {
        super(chunker, polisher, caller);
    }

    afterPageLayout(pageFragment, page, breakToken) {
        console.log(pageFragment, page, breakToken);
    }
}

Paged.js contains the following asynchronous hooks:

Chunker

beforeParsed(content
afterParsed(parsed)
beforePageLayout(page)
afterPageLayout(pageElement, page, breakToken)
afterRendered(pages)

Polisher

beforeTreeParse(text, sheet)
onUrl(urlNode)
onAtPage(atPageNode)
onRule(ruleNode) runs
onDeclaration(declarationNode, ruleNode)
onContent(contentNode, declarationNode, ruleNode)

Finally, the new handler needs to be registed in order to be used.

Paged.registerHandlers(MyHandler);

This can be registered anytime before the preview has started and will persist through any instances of Paged.Previewer that are created.

If a JavaScript library, such as MathJax, needs access to the content before it is paginated, you can delay pagination until that script has completed its work. This will give the library full access to the content of the book but has the disadvantage of needing to render the entire book before rendering each page, which can cause a significant delay.

Given that the polyfill will remove the page contents as soon as possible, adding a window.PagedConfig will allow you to pass a Promise that will delay until it is resolved.

let promise = new Promise((resolve, reject) {
  someLongTask(resolve);
});

window.PagedConfig = {
  before: () => {
      return promise;
  }
};

It is also possible to delay rendering of the polyfill until called by passing auto: false .

window.PagedConfig = {
    auto: false
};

window.PagedPolyfill.preview();

When the Previewer class is used directly, the preview() method can be called at any point that is appropriate.