Welcome to the ReadiumJS viewer project. This project encapsulates several applications.
- A basic EPUB viewer
- A Chrome packaged app for managing an EPUB library and reading EPUBs.
- A generic EPUB library management and viewer application that requires you to implement your own backend
The viewer is the default viewer for Readium.js, a JS library for rendering EPUB files on any modern browser, via any web server. If you'd like to learn more, check out the ReadiumJS website](http://readium.org/projects/readiumjs), and/or source on Github. ReadiumJS is in early development and it is not yet recommended that you use it for production deployment of EPUB files.
- An online instance of the ReadiumJS viewer (CloudReader)
- Basic EPUB viewer
- Embeddable EPUB Viewer
- Chrome packaged app
- Custom EPUB management system
- Running the Tests
ReadiumJS uses git submodules to embed other repositories and it uses Node.js and associated tools and libraries. Do the following steps to be up and running:
- Install Node.js (details depend on your operating system)
- Install the Grunt build tool using the command line:
npm install -g grunt-cli
(requires at least version 0.4.4) - From the command line run
git clone https://github.com/readium/readium-js-viewer.git
- From the command line run
cd readium-js-viewer
- From the command line run
git submodule update --init --recursive
- install Node.JS
- From the command line run
npm install -g grunt-cli
- From the command line run
npm install
(in the readium-js-viewer directory) - From the command line run
cd readium-js
- From the command line run
npm install
(a second time in the readium-js directory) - From the command line run
cd ..
- You should now be able to run the grunt commands specified below.
There easiest way to see the Readium Cloud Reader in action is to navigate to the CloudReader instance here. The content hosted there isn't that interesting since it is aimd primarily at providing a frequently updated instance of the CloudReader that can be crowd-tested. We are working on a more interesting instance and will post the link here soon.
To test the ReadiumJS viewer on any static web server:
- Perform the above steps and clone https://github.com/readium/readium-js-viewer.git into a content directory in your web server (e.g. into a "www/readium-js-viewer" folder)
- For zipped EPUB files support, configure your web server for HTTP Byte Serving so that Readium.js library can fetch only the necessary portions of a zipped EPUB file that contain content for the displayed page
- Visit yourdomain/readium-js-viewer/simpleviewer.html?epub=epub_content/moby_dick and enjoy!
- There is no step three! (but it is not recommended to deploy the build-related files onto a publicly-accessible server)
You can also use the Grunt build configuration contained in cloned sources to run an embedded Node.JS + Express web server that serves the demo application:
- Initialize your repository as described above
- Run the embedded webserver by running
grunt
(this is the default task) - Visit http://localhost:8080/simpleviewer.html?epub=epub_content/moby_dick in your browser
- Quit the webserver by pressing Ctrl-C on the console
One of advantages of the embedded Node.JS + Express web server is that it supports HTTP Byte Serving out of the box, without additional configuration, required for efficient handling of zipped EPUB files.
The viewer uses the epub
url query parameter to find the ebook to display. The project comes with several epubs already (look under the epub_content directory). To add a new EPUB simply unzip an epub to be anywhere on the same server as the viewer. Example steps:
- unzip any
(*)
valid(**)
.epub file (EPUB 2 or EPUB 3 version) in the "epub_content" directory - navigate to http://localhost:8080/simpleviewer.html?epub=epub_content/new_book_directory
(*)
NOTE1: This is somewhat aspirational; as Readium.js is still in early development not all EPUB 3 features are yet supported in - see issues trackers for the consituent sub-projects for more info
(**)
NOTE2: "valid" means EPUBCHeck 3.0 reports zero errors. At this time Readium.js does not have robust error handling
The Grunt build configuration also contains an optional task that builds the latest versions of Readium.js library files and places them in the lib/
directory.
Assuming that you have Grunt and project's dependencies already installed (see above), in order to run this task, execute the following command:
grunt update-readium
You can host an embeddable epub viewer using the same instructions as the Basic EPUB viewer. For example, if you wanted to add epub content to a blog or similar.
Follow the same instructions as setting up the Basic EPUB viewer then embed the epub reader using an iframe like so
<iframe width="600" height="400" src="http://localhost:8080/simpleviewer.html?epub=epub_content/moby_dick&embedded=true" style="border:1px #ddd solid;" allowfullscreen mozallowfullscreen webkitallowfullscreen></iframe>
Note the embedded=true
query parameter. This adds a special UI and handling for a smaller screen. See the embed.html
file in the root of the source tree for a complete example that works with the Basic EPUB viewer setup.
To run the chrome packaged app, you will need to initialize your repository and then:
- Build the application with
grunt chromeApp
- Load the app as an unpacked extension from
(project-root)/build/chrome-app
. Directions here - Open the App in Chrome under chrome://apps
The code that runs the chrome packaged app can also be run on a web server. However, it requires a backend to store and retrieve EPUB files. You would have to implement this yourself. You can see this in action by following the directions to run a node web server and then navigating to http://localhost:8080/index.html. The backend the example uses is just static files so it doesn't support updating.
Alternatively you can build a package using either of the following two commands:
grunt cloudReader
grunt cloudReaderWithEpub; # Comes with ePubs bundled
The viewer project contains some basic regression tests. These are run using chromedriver, Selenium WebdriverJS, and nodeunit. The tests target the chrome packaged app. Assuming you have already followed the steps above to run the packaged app, these are the additional steps if you want to run the tests
- Install chromedriver for your platform and ensure it's on your system path somewhere.
- Install the Google Chrome browser or have it already installed in the default install location for your platform.
- run
grunt test
Licensing information can be found in the file license.txt in the root of the repo, as well as in the source code itself.