Skip to content

Commit

Permalink
README separate doc for cloud reader
Browse files Browse the repository at this point in the history
  • Loading branch information
@danielweck
danielweck committed Feb 8, 2018
1 parent 1fd3d27 commit ff919a0
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 22 deletions.
22 changes: 0 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -187,28 +187,6 @@ Example of Readium app hosted at *Surge*, and EPUBs hosted at *Firebase*: http:/
For more information about HTTP CORS, see https://docs.google.com/document/d/1RK_59-75OSE0PA6wexD9rYHQLnNYfoKIpsnH3SmDpUc


## Using the Cloud / Web Reader to test EPUB publications

The Readium Chrome App has become a popular choice to test/check EPUB2 and EPUB3 publications on desktop platforms (Windows, MacOS, Linux, and ChromeOS). Unfortunately, Google is deprecating the "apps" framework in the Chrome web browser, so the Readium app will soon be removed from the Chrome Web Store (during the first half of 2018). That being said, even if the Readium Chrome App remained available, there would be other limitations inherent to the Chrome "apps" model (such as Content Security Policy restrictions on inline Javascript, which breaks a number of existing interactive EPUB3 publications).

Thankfully, the Readium Cloud / Web Reader shares the majority of its codebase with the Chrome App, so they are functionally equivalent apart from how EPUB files are stored and accessed. The Readium Cloud / Web Reader can therefore also be used to test EPUB2 and EPUB3 publications, with the benefit of cross-browser support (not just Chrome). As this is a reading system designed to be deployed on the web (publications uploaded in the "cloud"), the workflow is slightly more complicated. It is however possible to configure it for "offline" use, by running a local web server. Follow these instructions:

1) Make sure NodeJS is installed on your computer ( https://nodejs.org )
2) Open a command window, and type or copy/paste: `npm install -g http-server`
3) Download the file `Readium_cloud-reader-lite.zip` from https://github.com/readium/readium-js-viewer/releases
4) Unzip `Readium_cloud-reader.zip` on your filesystem, for instance: `/PATH/TO/FOLDER/cloud-reader-lite/`
5) In the command window, type `cd /PATH/TO/FOLDER/cloud-reader-lite/` to move into this new folder
6) Open the filesystem explorer and navigate to `/PATH/TO/FOLDER/cloud-reader-lite/`
7) Create a subfolder called `epub_content` (full path: `/PATH/TO/FOLDER/cloud-reader-lite/epub_content`
8) Copy publications into this folder, for example `MY_BOOK.epub`
9) Ideally, unzip the `MY_BOOK.epub` file (rename it with the `.zip` extension first), so that the publication contents reside in the `epub_content/MY_BOOK/` folder
10) Now back into the command window, invoke the following: `http-server -a 127.0.0.1 -p 8080 -c-1 .`
11) ... and open your web browser to: `http://127.0.0.1:8080/?epub=epub_content/MY_BOOK` (change `MY_BOOK` to your publication filename). If you skipped step (9), change `MY_BOOK` to `MY_BOOK.epub`, but remember: for best results publications should be extracted / unzipped first (because of performance / memory issues, and broken features such as audio and video playback)
12) Optionally, you may also drag and drop EPUB files onto the browser window, but once again: ideally publications should be extracted / unzipped beforehand!
13) In fact, for quick-testing simple and small EPUBs, you can also drag and drop files on the browser window at https://readium.firebaseapp.com (but once again: not the recommended practice!)

To conclude, note that a new desktop app is being developed, as part of the Readium2 project. This should be ready for public use later in 2018.

## NPM (Node Package Manager)

NOTE THAT THIS FEATURE IS NOT FULLY IMPLEMENTED YET (PLEASE REFERENCE THE GITHUB REPOSITORIES INSTEAD FROM YOUR PACKAGE.JSON)
Expand Down
21 changes: 21 additions & 0 deletions README_cloud-reader.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Using the Cloud / Web Reader to test EPUB publications

The Readium Chrome App has become a popular choice to test/check EPUB2 and EPUB3 publications on desktop platforms (Windows, MacOS, Linux, and ChromeOS). Unfortunately, Google is deprecating the "apps" framework in the Chrome web browser, so the Readium app will soon be removed from the Chrome Web Store (during the first half of 2018). That being said, even if the Readium Chrome App remained available, there would be other limitations inherent to the Chrome "apps" model (such as Content Security Policy restrictions on inline Javascript, which breaks a number of existing interactive EPUB3 publications).

Thankfully, the Readium Cloud / Web Reader shares the majority of its codebase with the Chrome App, so they are functionally equivalent apart from how EPUB files are stored and accessed. The Readium Cloud / Web Reader can therefore also be used to test EPUB2 and EPUB3 publications, with the benefit of cross-browser support (not just Chrome). As this is a reading system designed to be deployed on the web (publications uploaded in the "cloud"), the workflow is slightly more complicated. It is however possible to configure it for "offline" use, by running a local web server. Follow these instructions:

1) Make sure NodeJS is installed on your computer ( https://nodejs.org )
2) Open a command window, and type or copy/paste: `npm install -g http-server`
3) Download the file `Readium_cloud-reader-lite.zip` from https://github.com/readium/readium-js-viewer/releases
4) Unzip `Readium_cloud-reader-lite.zip` on your filesystem, for instance: `/PATH/TO/FOLDER/cloud-reader-lite/`
5) In the command window, type `cd /PATH/TO/FOLDER/cloud-reader-lite/` to move into this new folder
6) Open the filesystem explorer and navigate to `/PATH/TO/FOLDER/cloud-reader-lite/`
7) Create a subfolder called `epub_content` (full path: `/PATH/TO/FOLDER/cloud-reader-lite/epub_content`
8) Copy publications into this folder, for example `MY_BOOK.epub`
9) Ideally, unzip the `MY_BOOK.epub` file (rename it with the `.zip` extension first), so that the publication contents reside in the `epub_content/MY_BOOK/` folder
10) Now back into the command window, invoke the following: `http-server -a 127.0.0.1 -p 8080 -c-1 .`
11) ... and open your web browser to: `http://127.0.0.1:8080/?epub=epub_content/MY_BOOK` (change `MY_BOOK` to your publication filename). If you skipped step (9), change `MY_BOOK` to `MY_BOOK.epub`, but remember: for best results publications should be extracted / unzipped first (because of performance / memory issues, and broken features such as audio and video playback)
12) Optionally, you may also drag and drop EPUB files onto the browser window, but once again: ideally publications should be extracted / unzipped beforehand!
13) In fact, for quick-testing simple and small EPUBs, you can also drag and drop files on the browser window at https://readium.firebaseapp.com (but once again: not the recommended practice!)

To conclude, note that a new desktop app is being developed, as part of the Readium2 project. This should be ready for public use later in 2018.

0 comments on commit ff919a0

Please sign in to comment.