Note: Please don't use the zip download feature on this repo as this repo uses submodules and this is not supported at present by github and will result in an incomplete copy of the repo.

readium-js-viewer

EPUB reader written in HTML, CSS and Javascript.

This Readium software component implements the Readium Chrome extension / app for offline reading ( https://chrome.google.com/webstore/detail/readium/fepbnnnkkadjhjahcafoaglimekefifl ), and the "cloud reader" for online e-books ( https://readium.firebaseapp.com is the deployment URL for automated builds from the develop branch, https://readium-master.surge.sh links to the latest app release from the master branch).

Please see https://github.com/readium/readium-shared-js for more information about the underlying rendering engine.

License

BSD-3-Clause ( http://opensource.org/licenses/BSD-3-Clause )

See license.txt.

Prerequisites

• A decent terminal. On Windows, GitBash works great ( https://msysgit.github.io or https://git-for-windows.github.io or https://git-scm.com/download/win ), and optionally Cygwin adds useful commands ( https://www.cygwin.com ).
• NodeJS ( https://nodejs.org ) v4+ (Note that NodeJS v6+ and NPM v3+ are now supported, including NodeJS v7+ and NPM v4+)
  • Optionally: Yarn ( https://yarnpkg.com ) v0.23+

Development

Git initialisation

• git clone --recursive -b BRANCH_NAME https://github.com/readium/readium-js-viewer.git readium-js-viewer

  (replace "BRANCH_NAME" with e.g. "develop")

• cd readium-js-viewer

• git submodule update --init --recursive

  to ensure that the readium-js-viewer chain of dependencies is initialised (readium-js, readium-shared-js)

• git checkout BRANCH_NAME && git submodule foreach --recursive "git checkout BRANCH_NAME"

  (or simply

  cd

  inside each repository / submodule, and manually enter the desired branch name:

  git checkout BRANCH_NAME

  ) Git should automatically track the corresponding branch in the 'origin' remote.

Advanced usage (e.g. TravisCI) - the commands below automate the remote/origin tracking process (this requires a Bash-like shell):

• for remote in `git branch -r | grep -v \> | grep -v master`; do git branch --track ${remote#origin/} $remote; done

  to ensure that all Git 'origin' remotes are tracked by local branches.

• git checkout `git for-each-ref --format="%(refname:short) %(objectname)" 'refs/heads/' | grep $(git rev-parse HEAD) | cut -d " " -f 1`

  to ensure that Git checks-out actual branch names (as by default Git initializes submodules to match their registered Git SHA1 commit, but in detached HEAD state)

(repeat for each repository / submodule)

Source tree preparation

• npm run prepare:all

  (to perform required preliminary tasks, like patching code before building)
  • OR:

    yarn run prepare:yarn:all

    (to use Yarn instead of NPM for node_module management)

Note that in some cases, administrator rights may be needed in order to install dependencies, because of NPM-related file access permissions (the console log would clearly show the error). Should this be the case, running

sudo npm run prepare:all

Note that the above command executes the following:

• npm install

  (to download dependencies defined in

  package.json

  ... note that the

  --production

  option can be used to avoid downloading development dependencies, for example when testing only the pre-built

  build-output

  folder contents)

• npm update

  (to make sure that the dependency tree is up to date)
• + some additional HTTP requests to the GitHub API in order to check for upstream library updates (wherever Readium uses a forked codebase)

Typical workflow

No RequireJS optimization:

• npm run http

  (to launch an http server. This automatically opens a web browser instance to the HTML files in the

  dev

  folder, choose

  index_RequireJS_no-optimize.html

  , or the

  *LITE.html

  variant which do include only the reader view, not the ebook library view)
• Hack away! (e.g. source code in the

  src/js

  folder)
• Press F5 (refresh / reload) in the web browser

Or to use optimized Javascript bundles (single or multiple):

• npm run build

  (to update the RequireJS bundles in the build output folder)

• npm run http:watch

  (to launch an http server. This automatically opens a web browser instance to the HTML files in the

  dev

  folder, choose

  index_RequireJS_single-bundle.html

  or

  index_RequireJS_multiple-bundles.html

  , or the

  *LITE.html

  variants which do include only the reader view, not the ebook library view)

• npm run http

  (same as above, but without watching for file changes (no automatic rebuild))

And finally to update the distribution packages (automatically calls the

build

npm run build

• npm run dist

  (Chrome extension and cloud reader, including the lite / no-library variant)

The above task takes a lot of time (as it builds distributable packages for all ReadiumJS flavours), and is in fact not strictly necessary to test the cloud reader (see

npm run http

• npm run chromeApp

  (generates a ready-to-use Readium packaged app for Chrome, inside the usual

  dist/chrome-app

  folder)

Remember to activate "developer mode" in the Chrome web browser, so that the Readium packaged app / extension can be added directly from the

dist/chrome-app

Also note that the built-in local HTTP server functionality (

npm run http

dev

src

node_modules

readium-js-viewer

node node_modules/http-server/bin/http-server -a 127.0.0.1 -p 8080 -c-1 .

127.0.0.1

npm run http

0.0.0.0

RJS_HTTP_IP

0.0.0.0

export RJS_HTTP_IP="0.0.0.0"

RJS_HTTP_IP="0.0.0.0" npm run http

Remark: a log of HTTP requests is preserved in

http_app-ebooks.log

cat http_app.log

sed "s,x,x,g" http_app-ebooks.log

HTTP CORS (separate domains / origins, app vs. ebooks)

By default, a single HTTP server is launched when using the

npm run http

http2

http

npm run http2

Remark: logs of HTTP requests are preserved in two separate files

http_app.log

http_ebooks.log

cat http_app.log

sed "s,x,x,g" http_app.log

Forking

Assuming a fork of

https://github.com/readium/readium-js-viewer

USER

https://github.com/USER/readium-js-viewer

.gitmodules

readium

USER

.gitmodules

https://github.com/readium/

https://github.com/USER/

readium-js-viewer

readium-js

readium-shared-js

git submodule sync

Plugins integration

When invoking the

npm run build

build-output

readium-js/readium-js-shared/plugins/plugins.cson

plugins-override.cson

For example, the

annotations

include

readium-js/readium-js-shared/plugins/plugins-override.cson

display:none

.icon-annotations

src/css/viewer.css

RequireJS bundle optimisation

Note that by default, compiled RequireJS bundles are minified / mangled / uglify-ed. You can force the build process to generate non-compressed Javascript bundles by setting the

RJS_UGLY

This may come-in handy when testing / debugging the Chrome Extension (Packaged App) in "developer mode" directly from the

dist

Tests

Mocha-driven UI tests via Selenium (not PhantomJS, but actual installed browsers accessed via WebDriver):

• npm run test:firefox

• npm run test:chrome

• npm run test:chromeApp

npm run test

PS: you may need to install the Chrome WebDriver from https://sites.google.com/a/chromium.org/chromedriver/downloads

Via SauceLabs:

• npm run test:sauce:firefox

• npm run test:sauce:chrome

• npm run test:sauce:chromeApp

npm run test:sauce

Travis (Continuous Integration) automatically uses a chromeApp and Firefox test matrix (2x modes), and uses SauceLabs to actually run the test. See https://travis-ci.org/readium/readium-js-viewer/

Distribution

See the

dist

npm run dist

• cloud-reader

• cloud-reader-lite

  (same as above, without the ebook library feature)

• chrome-app

  (Google Chrome Extension / Packaged App)

The source maps are generated separately, so they are effectively an opt-in feature (simply copy/paste them next to their original Javascript file counterparts, e.g. in the

scripts

npm run dist+sourcemap

npm run dist

Note that

npm run http

dev

dist

node node_modules/http-server/bin/http-server -a 127.0.0.1 -p 8080 -c-1 ..

readium-js-viewer

http://127.0.0.1:8080/readium-js-viewer/dist/cloud-reader/index.html?epubs=http://127.0.0.1:8080/readium-js-viewer/epub_content/epub_library.opds

epub_library.json

epub_content

dist/cloud-reader

http://127.0.0.1:8080/readium-js-viewer/dist/cloud-reader/index.html

Cloud reader deployment

The contents of the

cloud-reader

epub_content/

epub_content/epub_library.opds

readium-js-viewer

epub_library.json

epubs

http://domain.com/index.html?epubs=http://otherdomain.com/ebooks.opds

http://domain.com/index.html?epubs=EPUBs/ebooks.opds

EPUBs/

index.html

ebooks.opds

cloud-reader/index.html

epubLibraryPath

javascript
require.config({
config : {
        'readium_js_viewer/ModuleConfig' : {
            'epubLibraryPath': VALUE
        }
});

:point_right: Note: It is STRONGLY RECOMMENDED that when deploying the CloudReader that you do not try to load packed (i.e. still zipped) EPUBs. This is because there are (so far) insurmountable reasons why the loading of large resources (e.g. videos, etc.) will be so slow as to be unacceptable or even time out. Instead, deployers should:

• Unpack / unzip EPUBs in remote storage, instead of serving the actual EPUB files, which will allow the assets to be streamed in the normal fashion
• De-obfuscate fonts on the server

For more info, see the document here

The issues associated with transmitting unencrypted fonts can be mitigated using HTTPS, HTTP_REFERER, and other web techniques designed to protect content ( e.g. http://blog.typekit.com/2009/07/21/serving-and-protecting-fonts-on-the-web )

The

cloud-reader-lite

http://domain.com/index.html?epub=http://otherdomain.com/ebook.epub

http://domain.com/index.html?epub=EPUBs/ebook.epub

EPUBs/

index.html

ebook.epub

epub_content/

Example of Readium app hosted at Surge, and EPUBs hosted at Firebase: http://readium.surge.sh/?epubs=http://readium.firebaseapp.com/epubcontent/epublibrary.opds (note that only the firebaseapp.com host specifies HTTP CORS headers, the Surge.sh server does not configure anything special to achieve this unilateral cross-origin resource sharing)

For more information about HTTP CORS, see https://docs.google.com/document/d/1RK_59-75OSE0PA6wexD9rYHQLnNYfoKIpsnH3SmDpUc

NPM (Node Package Manager)

NOTE THAT THIS FEATURE IS NOT FULLY IMPLEMENTED YET (PLEASE REFERENCE THE GITHUB REPOSITORIES INSTEAD FROM YOUR PACKAGE.JSON)

All packages "owned" and maintained by the Readium Foundation are listed here: https://www.npmjs.com/~readium

Note that although Node and NPM natively use the CommonJS format, Readium modules are currently only defined as AMD (RequireJS). This explains why Browserify ( http://browserify.org ) is not used by this Readium project. More information at http://requirejs.org/docs/commonjs.html and http://requirejs.org/docs/node.html

• Make sure

  npm install readium-js-viewer

  completes successfully ( https://www.npmjs.com/package/readium-js-viewer )
• Execute

  npm run http

  , which opens a web browser to a basic RequireJS bootstrapper located in the

  dev

  folder (this is not a production-ready minified application)

Note: the

--dev

npm install readium-js-viewer

How to use (RequireJS bundles / AMD modules)

The

build-output

Single bundle

The

_single-bundle

readium-js-viewer_all.js

This means that the full RequireJS library ( http://requirejs.org ) is not actually needed to bootstrap the AMD modules at runtime, as demonstrated by the HTML file in the

dev

Multiple bundles

The

_multiple-bundles

• readium-external-libs.js

  : aggregated library dependencies (e.g. Underscore, jQuery, etc.)

• readium-shared-js.js

  : shared Readium code (basically, equivalent to the

  js

  folder of the "readium-shared-js" submodule)

• readium-js.js

  : the core Readium code (basically, equivalent to the

  js

  folder of the "readium-js" submodule)

• readium-js-viewer.js

  : this Readium code (mainly, the contents of the

  js

  folder)

• readium-plugin-example.js

  : simple plugin demo

• readium-plugin-annotations.js

  : the annotation plugin (DOM selection + highlight), which bundle actually contains the "Backbone" library, as this dependency is not already included in the "external libs" bundle. )

In addition, the folder contains the full

RequireJS.js

Usage is demonstrated by the HTML file in the

dev

Note how the "external libs" set of AMD modules can be explicitly described using the

bundles

CSON vs. JSON (package.json)

CSON = CoffeeScript-Object-Notation ( https://github.com/bevry/cson )

Running the command

npm run cson2json

package.json

./package/package_base.cson

Why CSON? Because it is a lot more readable than JSON, and therefore easier to maintain. The syntax is not only less verbose (separators, etc.), more importantly it allows comments and line breaking!

Although these benefits are not so critical for basic "package" definitions, here

package.cson/json

script

npm run SCRIPT_NAME

Downside: DO NOT invoke

npm init

npm install --save

--save-dev

--save-optional