Development

Shinyu Murakami edited this page Apr 30, 2018 · 12 revisions

Vivliostyle.js consists of two components:

  • vivliostyle-core: Core page layout engine. Written in raw ES5 (with type annotations in comments), type-checked and minified with Closure Compiler.
  • vivliostyle-ui: Viewer UI for Vivliostyle.js. Written in raw ES5 + ES6 modules. ES6 modules are concatenated with Babel.

Setting up development environment

Make sure that the followings are installed:

  • Node.js
  • Java (To run Closure Compiler)
  • Compass (To build vivliostyle-ui)

Clone vivliostyle-core (repo is named as vivliostyle.js) and vivliostyle-ui:

git clone git@github.com:vivliostyle/vivliostyle.js.git
git clone git@github.com:vivliostyle/vivliostyle-ui.git

Vivliostyle-core is listed as a dependency in package.json of vivliostyle-ui. During development, you want to use the local copy of vivliostyle-core, rather than a package installed from npm. For this purpose, use npm link to make a symbolic link:

cd vivliostyle-ui
npm install
npm link ../vivliostyle.js

Build and serve with Node.js:

npm run serve-dev

With npm run serve-dev, vivliostyle-ui is built, a web server starts (Browsersync with live-reload enabled), and Google Chrome should automatically open. If no browser opens, open http://localhost:3000/vivliostyle.js/test/files/. On saving any source file, the browser automatically reloads.

If you want to start a web server on your own, run npm run build-dev instead of npm run serve-dev, then start your favorite web server.

Viewer and test files

Viewer HTML file (in development mode) is located at vivliostyle-ui/build/vivliostyle-viewer-dev.html. You can open an (X)HTML file with a URL (relative to the viewer HTML file) specified to x hash parameter. For example, http://localhost:3000/vivliostyle-ui/build/vivliostyle-viewer-dev.html#x=../../vivliostyle.js/test/files/print_media/index.html opens a test file for print media located at vivliostyle.js/test/files/print_media/index.html. You can also open an EPUB directory (unzipped EPUB file) by b parameter. For example, http://localhost:3000/vivliostyle-ui/build/vivliostyle-viewer-dev.html#b=../../vivliostyle.js/samples/niimi/ opens a sample EPUB directory located at vivliostyle.js/samples/niimi/. Note that you cannot omit the trailing slash.

Test HTML files, indented to be used during development, are located at vivliostyle.js/test/files/. You are encouraged to add test files useful for implementing and verifying features.

vivliostyle.js/samples/ directory holds a public sample files, which are deployed to the sample page on vivliostyle.com.

Testing

You need to run npm install under vivliostyle.js directory before running the followings.

JS files are type-checked and minified with Closure Compiler. To run the Closure Compiler, run npm run build (under vivliostyle.js directory). The sources are type-checked and the minified file is generated under lib/ directory.

Jasmine is used for unit testing. Spec files are located under test/spec/. To run unit tests on a local machine, run npm run test:local.

A forked version of CSSWG reftests can be run with vivliostyle-core. See files under test/wpt/ for details.

The unit tests and reftests (listed in test/wpt/metadata/MANIFEST.json) are automatically run on push to GitHub on Travis CI. When pushed to master, after all tests pass, the code will be automatically deployed to the sample page on vivliostyle.com, so please be careful when pushing to master (merging PR).

Building production version

You can build a production version of Vivliostyle.js by running npm run build under vivliostyle-ui directory. All JS files of vivliostyle-ui and vivliostyle.js are concatenated to a single file.

Development mode

In development mode (npm run build-dev/serve-dev), source JS files of vivliostyle-core (located under vivliostyle.js/src) are directly loaded by the browser. The loading order is written in src/source-list.js. When you add a new JS file, do not forget to add it to the list in a correct position.

Maintaining documents

Please update following documents as developing.

cd doc
curl -o anchors.json -H "Accept: application/json" 'https://test.csswg.org/shepherd/api/spec/?anchors&draft'  # Download spec data
node ../build/generate-property-doc

Code

Source files under src/ are briefly described below.

vivliostyle/viewer.js
Exposed interface of vivliostyle-core. To use vivliostyle-core, instantiate `vivliostyle.viewer.Viewer`, set options, register event listeners by `addListener` method, and call `loadDocument` or `loadEPUB` method.
vivliostyle/constants.js
Defines constants used throughout the library.
adapt/task.js
Task scheduling.
adapt/expr.js
Definitions for expressions of Adaptive Layout.
adapt/css.js
Definitions for various CSS values.
adapt/cssparse.js
CSS parser.
adapt/csscasc.js
Classes for selector matching and cascading calculation.
adapt/vtree.js
View tree data structures.
adapt/cssstyler.js
Apply CSS cascade to a document incrementally.
adapt/font.js
Web font handling.
adapt/pm.js
Classes for page masters of Adaptive Layout.
vivliostyle/pagefloat.js
Page floats.
adapt/vgen.js
Generation of view tree.
adapt/layout.js
Content layout inside regions, including column breaking etc.
vivliostyle/page.js
Support for CSS Paged Media.
adapt/ops.js
Select page master, layout regions (columns) one by one etc.
adapt/epub.js
Handling EPUB metadata, rendering pages etc.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.