Join GitHub today
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:
git clone email@example.com:vivliostyle/vivliostyle.js.git git clone firstname.lastname@example.org: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
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.
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
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.
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.
Please update following documents as developing.
- This file can be generated with
build/generate-property-doc.jsscript as follows:
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
- Document about features (values, selectors, at-rules, media queries and properties) supported by Vivliostyle. Automatically deployed to https://vivliostyle.github.io/vivliostyle.js/docs/supported-features.html. Update this file using information in
Source files under
src/ are briefly described below.
- 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.
- Defines constants used throughout the library.
- Task scheduling.
- Definitions for expressions of Adaptive Layout.
- Definitions for various CSS values.
- CSS parser.
- Classes for selector matching and cascading calculation.
- View tree data structures.
- Apply CSS cascade to a document incrementally.
- Web font handling.
- Classes for page masters of Adaptive Layout.
- Page floats.
- Generation of view tree.
- Content layout inside regions, including column breaking etc.
- Support for CSS Paged Media.
- Select page master, layout regions (columns) one by one etc.
- Handling EPUB metadata, rendering pages etc.