Skip to content

Development

Jump to bottom
Shinyu Murakami edited this page Aug 14, 2019 · 35 revisions

Updated 2019-08-05: JS-to-TS migration finished. Vivliostyle.js changed its type check system from Google Closure Compiler to TypeScript.

Vivliostyle Viewer consists of two components:

  • vivliostyle.js: Core page layout engine. Written in TypeScript now.
  • vivliostyle-ui: Viewer UI for Vivliostyle.js. Written in JavaScript (ES6 modules).

Setting up development environment

Make sure that the followings are installed:

Note: Recommend Node.js 10 or 11 for now. The vivliostyle-ui's build script uses Gulp 3 and not yet updated to Gulp 4 and Gulp 3 is broken on Node 12.

Clone vivliostyle.js and vivliostyle-ui:

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

Vivliostyle.js is listed as a dependency in package.json of vivliostyle-ui. During development, you want to use the local copy of vivliostyle.js, 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:

cd ../vivliostyle.js
npm run build-dev
cd ../vivliostyle-ui
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. The b parameter also accepts Web publications (multi-HTML documents). See the PR: Support Web Publications and similar multi-HTML documents with TOC navigation.

Test HTML files, intended 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.org.

Testing

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

The TypeScript source files are compiled and minified by webpack with ts-loader. To build the minified JS file, 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.js. See files under test/wpt/ for details. (Currently not working, need fix!)

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 github pages and can be accessed from the sample page on vivliostyle.org, 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), the compiled JS file vivliostyle.dev.js and source map file vivliostyle.dev.js.map (both located under vivliostyle.js/src) are loaded by the browser and you can debug TypeScript code in the browser's developer tools.

To debug vivliostyle.js with other web app

When debug vivliostyle.js with a web app that uses vivliostyle.min.js, it will be useful if source-level debugging is possible without changing the file name vivliostyle.min.js to vivliostyle.dev.js. For this purpose use npm run build-debug. This build mode is almost same as build-dev but the output filename is same as production build, vivliostyle.min.js, and the source map file vivliostyle.min.js.map is generated.

Maintaining documents

Please update following documents as developing.

Code

Lint and code formatting

Run npm run lint for lint and code format check (using ESLint with eslint-plugin-prettier) for the vivliostyle.js source code.

Run npm run lint-fix to fix fixable errors.

We use the default options of Prettier for code formatting. Use npm run lint-fix to keep the code pretty.

Source files

Source files under src/ts are briefly described below.

vivliostyle/viewer.ts
Exposed interface of vivliostyle.js. To use vivliostyle.js, instantiate vivliostyle.viewer.Viewer, set options, register event listeners by addListener method, and call loadDocument or loadPublication method.
vivliostyle/constants.ts
Defines constants used throughout the library.
adapt/task.ts
Task scheduling.
adapt/exprs.ts
Definitions for expressions of Adaptive Layout.
adapt/css.ts
Definitions for various CSS values.
adapt/cssparse.ts
CSS parser.
adapt/csscasc.ts
Classes for selector matching and cascading calculation.
adapt/vtree.ts
View tree data structures.
adapt/cssstyler.ts
Apply CSS cascade to a document incrementally.
adapt/font.ts
Web font handling.
adapt/pm.ts
Classes for page masters of Adaptive Layout.
vivliostyle/pagefloats.ts
Page floats.
adapt/vgen.ts
Generation of view tree.
adapt/layout.ts
Content layout inside regions, including column breaking etc.
vivliostyle/pages.ts
Support for CSS Paged Media.
adapt/ops.ts
Select page master, layout regions (columns) one by one etc.
adapt/epub.ts
Handling EPUB metadata, rendering pages etc.
(There are more files... See the `src/ts` directory)

Other dev documents

Clone this wiki locally