Additionally, the wiki has been updated with new information on how you can learn more about Readium and get involved. I encourage you to go check it out!

EPUB Canonical Fragment Identifiers (CFIs)

A stand-alone library that provides support for the EPUB 3.0 CFI specification has been added to the Readium repository. This library has also been integrated into Readium and is used to support CFI based page-list navigation. This is demonstrated by the Georgia-CFI EPUB sample.

The intention is also to use the CFI library to support bookmarking and annotations in Readium in the next little while.

Rate and volume controls for Media Overlays

New UI controls have been added to the Readium toolbar to support rate-of-playback and volume adjustment for Media Overalys. The MO controls now appear only for the parts of EPUBs that have Media Overlays. This should make it more obvious when this feature is available in an EPUB, or a particular part of it.

A number of other improvements have been made to the way that Media Overlay playback reacts to changes in the state of the EPUB, such as for page-turns, loading new content documents and saving and reloading the position of the playback. Improvements have also been made to the way MO highlighting is shown on the screen.

Drag and drop and faster unpacking in the library view

A new library - and some HTML 5 web workers - are now being used to unpack .epub files. This has increased the speed of unpacking and means that for all but the largest EPUBs, loading the packed .epub files is probably pretty feasible. EPUB files can now also be dragged and dropped onto the library view to load them into Readium, rather than having to use the “add EPUB” button on the toolbar.

SVG and Bitmap images in spine

Both SVG and bitmap images, included in an EPUB as spine items, are now supported in Readium.

Internationalization framework

The Chrome i8ln framework has been added to Readium to provide language support for Readium. We hope to add to the set of translations available for Readium, so if you’re able to provide translations in a language besides English, this would be a good way to help out!

Internal changes

Aside from the changes above, we’re continually refactoring the code base, fixing bugs and looking out for new ways to improve Readium. As usual, providing feedback and creating issues in the issue tracker is always welcome.

So, I’m going to cover a few topics which include the rationale and goals for refactoring, Readium’s conceptual model for rendering EPUBs, the refactored implementation AND how we’re going to go about deploying the changes.

But first…

Housekeeping

Beyond the refactoring, we’ve moved Readium to manifest version 2 for Chrome extensions. There were some complications due to a new content security policy for Chrome extensions, which Matthew discusses here. Interesting stuff if you’re using extensions elsewhere.

Also, we have a Readium contributors call today where we’ll establish new priorities for Readium development over the next couple months. We’re also thinking about a more formal way to keep the community up-to-date on current development priorities and/or something resembling milestones or a release calendar. Stay tuned for more on this.

Anyway, back to the main purpose of this post…

Readium is successful, time to refactor?

Readium has been going pretty well so far. We’ve got a lot of positive feedback from stakeholders and we’ve managed to continually add features and address concerns. Considering that things are trucking along just fine, why the refactoring?

Well, first off, Readium development has been iterating quickly from a starting point of nothing. As Readium has developed, so has our understanding of how best to implement certain features. Also, some tight deadlines have meant that we had to hack in some changes that we knew would be best implemented differently; all part of the typical development process. Since there was a lull between the end of the Tokyo Book Fair (where versions of Readium were presented) and our next priorities call, it seemed like a good time to refactor parts of the code base to address some of these issues and lay the groundwork for the next set of features.

What were the goals for refactoring?

There were a number of goals for refactoring. First and foremost was to increase the accessibility and understandability of the Readium codebase. We wanted to refactor to ensure Readium’s conceptual model for rendering EPUBs was represented in an obvious way in the code. It is a major goal of the Readium project to provide a reference implementation of an EPUB 3 reader. As such, we don’t just want Readium to “go”, we want developers to be able to understand (easily) how and why it “goes.”

The second goal was to support further development on Readium. Having a clear and understandable code base is important for our ability to continually extend the application with new functionality. Extending the application with new features was already getting tricky due to the growing complexity of the code. A few of our backbone models were getting large and dodgy dependencies were growing… It was about time for two of our best friends, abstraction and encapsulation, to come help us manage complexity.

However, before I get into the details of the refactoring it’ll be useful to discuss Readium’s conceptual model for rendering EPUBs, as this isn’t something we’ve provided a lot of documentation on in the past.

The conceptual model

There are a number of important concepts providing the foundation for rendering EPUBs in Readium; some obvious, some not. They are…

An EPUB

Basically everything that makes up a .epub file. Given that Readium is a viewer and not an authoring tool, the concept of an EPUB is of a read-only nature. Readium unpacks them, reads them, but doesn’t alter them.

Rendering (a view of) an EPUB

There can be a lot to an EPUB. How all the various parts - and which parts - of the EPUB get put up on the screen is called rendering. We have different ways (views) responsible for rendering different types of EPUB.

EPUB type

There are a number of ways that EPUB authors can choose to have an EPUB rendered.

One is “fixed layout,” where the author of the EPUB specifies the way in which the EPUB will be rendered on the screen, as well as the properties of that rendering. This includes fonts, backgrounds, margins, sizes etc.

Another is “reflowable,” where it is up to the reading system to decide how an epub is rendered. “Reflowable” means that content such as text can “flow” into available space on the screen and reflow, as that space changes.

The final option is scrolling text, which is reflowable text rendered in a scrolling window. This is not actually part of the EPUB spec but rather a convenience in Readium for solving a few different problems. However, the scrolling view may be removed at some point in the future.

Pagination

This is the concept of converting the content of an EPUB (text, images etc.) into a discrete number of “pages” we can put up on a screen. Pages are a useful abstraction that allow us to do things in a consistent way with renderings of the different types of EPUB.

Fixed layout EPUBs define their “pages” explicitily, reflowable EPUBs do not. In the case of a reflowable EPUB the number, size and display of pages is entirely dependent on the reading device and screen. In the case that the screen is resized, the pagination of content changes. It is important to handling some of the complexity here that the concept of “pages” is distinct from that of the content of the EPUB (although obviously, a conceptual link is maintained). Readium must maintain page state, including the number of pages in the current pagination, the currently displayed page etc.

Modifiable EPUB rendering properties

Readium allows users to set a number of properties for the rendering of an EPUB. These include the number of pages to display on the screen (one or two), font size, margin size, day or night styles etc. These preferences are persisted for each EPUB a user has loaded into Readium. As such, this state is maintained in Readium.

The above concepts are how we think about putting EPUBs up on the screen. The conceptual model is pretty simple but a picture is equal to ONE THOUSAND WORDS:

Before and after refactoring

The conceptual model I just described has existed all along. However, it was becoming increasingly muddied as to which parts of the code were responsible for which parts of that model. Essentially, as the original set of backbone models were extended, our abstractions and encapsulation were breaking down a bit. The image below shows the set of backbone models at the beginning of the refactoring process:

In particular, the Ebook model was becoming the “kitchen sink,” and was increasingly responsible for a great deal of the conceptual model I described. This included interaction with the currently rendered EPUB, behaviour for pages and the implementation of parts of the EPUB spec (such as Media Overlays). Additionally, the lack of clarity regarding the roles and responsibilities of the various models and views was resulting in new functionality bleeding into less-than-ideal places.

To meet our two goals for refactoring, outlined above, this core set of models and views was refactored into the following (A description follows of how each backbone model was refactored):

Ebook

This model was refactored into a set of models with specific responsibilities:

1) EPUB: This is a “read-only” model that represents the content of an EPUB loaded in the Readium application. The attributes of this model are now persisted separately from those of EPUBController, in order to maintain a clear separation between the “read-only” properties of an EPUB and the rendering properties maintained by Readium to display an EPUB. The attributes for this model are only persisted a single time when an EPUB is unpacked and are not updated by Readium.

2) EPUBController: This model represents the concept of “an EPUB being represented” in the Readium system. It wraps EPUB (and others, like the package document) and exposes it to the Readium application, as well as maintaining attributes such as the current location (the current spine element) in the EPUB’s content, whether one or two pages are displayed, current font-size etc. This model is also intended to manage the interaction between the rest of the application and the content of an EPUB.

3) ReadiumPagination: This model represents a set of EPUB content that has been “paginated” by one of the backbone views (discussed below). The intention is to abstract and encapsulate page management from other parts of the system. Instances of this model are managed by the currently instantiated backbone view, which itself is responsible for paginated some set of content.

4) PageNumberDisplayLogic: In Readium, displaying “pages” includes toggling the number of pages displayed (one or two), navigating forward or backward through an EPUB or switching the view to a particular page. The logic required for implementing this is actually more complex than it would first appear. The correct layout depends on the type of EPUB, any preferences the author might have set for the EPUB, the page-progression-direction and the specified reading-order for the EPUB. This logic is now encapsulated in its own model, with all the attendent benefits.

5) Media Overlay models: Media Overlays functionality was temporarily taken out and will be refactored into its own set of models from the MO development fork.

Paginator

This model was refactored into PaginationStrategySelector. Additionally, the logic of this model was simplified, with some of the code for rendering fixed layout EPUBs refactored into the fixed layout backbone view. This model was also renamed to clarify its role: It does not actually paginate EPUB content but rather selects a pagination strategy and calls the appropriate backbone view to “paginate” a set of content.

The views

The backbone views have the primary responsibilty of paginating the content of an EPUB and rendering it on the screen. The inheritence structure of the views did not change, but some functionality was refactored from EBook and Paginator into the appropriate view. In particular, the API for each of the views was made consistent (base, fixed layout, reflowable and scrolling). Each of these views has a render() method that when called, paginates some of the content of an EPUB and creates an instance of the ReadiumPagination model. The instantiated ReadiumPagination object then represents the current set of paginated content.

Some other notes about the code

Interfaces

I find it’s very helpful to be able to look at an object or model and know right away which methods are called by other parts of the code and which are intended to be “helpers” within the object/model itself. tl;dr I want to know the interface and the abstraction it’s implementing. Javascript doesn’t provide us some of the tools for this that we might have in another language (public/private declarations, interfaces etc.). However, I still think it’s useful to apply conventions to make the interface clear.

In the refactored models, we’ve re-ordered the methods and created comment headers to indicate which methods are part of the interface of each model/view, and which are “internal” helpers for that object. Obviously, nothing in the code actually enforces “public” and “private” - and neither do I think it’s necessary we do so. However, the hope is that this convention will make clearer the intention and dependencies of each model/view.

Code commenting

Generally, I think it’s best that code speak for itself. It should be written-to-be-read (by humans). Comments that document step-by-step functionality are a bit redundant (although not always). On the other hand, I think in-line comments are very useful for documenting both high-level intentions (for methods/blocks etc.) and for, most importantly, rationale. I find rationale - the set of reasons underlying a particular approach or implementation - to be the most difficult thing to infer from code. To this end, comments at the beginning of important methods usually include an attempt at explaining intention and rationale; in particular, things that have a non-obvious or unusual rationale. I encourage you to do the same if you’re contributing to Readium.

Deployment

A branch has been published in readium/readium. It’ll be there to test for regression bugs and other omissions and while we update some of the test cases and add in some of the excluded Media Overlay functionality. When we’re comfortable with it, probably early next week, we’ll push it up as the master and continue Readium development from there. If you have any questions, please come and find us.

To this end, I wanted to bring your attention to an epub validating parser that Brian Buck has been working on. More details are available on his github page but as an overview, the project is a (fast) EPUB validating parser that has been tested in a number of environments, including iOS. We haven’t been doing much iOS work with Readium yet, but I suspect this’ll be interesting to a lot of people out there. By way of a disclaimer, this is not the “official” epub validiator we’re using for Readium but it’s great to have people working on and looking at all parts of the EPUB toolchain. We hope that the interest and improvements generated by Brian’s project will help us improve Readium in the future.

Thanks Brian!

Contributing

First up, there has been a lot of recent interest from people who want to contribute to the Readium project, which is always encouraging and very welcomed. It’s especially helpful to have contributors who can read and debug the rendering of ePubs in languages other than English. Matthew did a great job (more below) getting vertical Japanese text to render, which he was pretty excited about. Did it actually render something that made sense? We had no idea (it did). But it was vertical.

We also have users contributing bug reports, which is definitely helpful as these improve our understanding of what kind of ePubs are getting put together out there. So, if you’ve come across the Readium project and tried your unique ePub and it’s not working, let us know by creating an issue in the tracker. We can’t promise quick fixes for everything, but it goes a long way to helping build a full-spec reader.

docco

We had a suggestion from Simon Schmid to set up docco to make the code base more accessible and understandable. docco pulls comments directly out of source files and lines them up with your code in a nicely formatted web page. It uses markdown and only pulls out the // comments; /**/ comments are left in the source. In any case, you don’t have to do anything but comment, we’ll take care of deploying the updated docco-mentation. We’ve got it set up and it can be accessed from the documentation tab on this blog (you can navigate to other docco pages with the widget in the top right). In general contributing documentation is a great way to help out while familiarizing yourself with an open source project and Readium could use some more comments, so comment away.

IRC channel

We’ve set up an IRC channel for the Readium project on freenode.net. The channel is #Readium. Matthew or I will try to be on there during PST working hours and hopefully we can answer questions if they come up. I can’t imagine we’re going to have too many flame wars about Readium but since this is the internet, I would feel negligent not to remind everyone to keep it respectful.

CSS regions no more

In order to better support different forms of writing - right-to-left, vertical etc. - Matthew changed the reflowable pagination approach from the use of CSS3 regions to CSS columns. This was a big step forward for Readium as CSS columns are supported on almost all modern browsers. Also, because this approach is able to execute entirely within an iframe it solved a number of other issues we had been having (eg scoping of style rules). We are also able to allow spine level scripting for the reflowable content, which a lot of EPUB content creators were really excited to start working with.

Alternate Style Tags

An implementation of the Alternate Style Tags specification has been added to Readium. It is set up to interpret arbitrary sets of tags generally, although currently only day/night tags are specifically handled. This can be demonstrated with the use of the Wasteland ePub from the Sample-Project, which has an alternate style set for “night” mode. If anyone sees any problems, missing parts of the spec or misinterpretations, please let me know!

Wrap-up

So that’s it for now. As always if you have questions, want to contribute, or submit bug reports, we can be contacted on github, by email, or now on IRC!

But today I am going to take the first step towards writing this wrong. I am planning a series of (at least) 3 blog posts explaining how the internals of Readium operate. I think the end result will be interesting not only to Readium contributors, but also to ebook publishers, developers of other ebook reading systems and anyone building large applications with HTML5 / javascript.

Unpacking an EPUB

I felt that the most natural place to start diving into Readium is the beginning. Readium currently ships with an empty library, so the first thing that every new user of our system does is import a file into their library.

How do you wanna do this?

As of writing, Readium offers users three ways to import content into their library: from a remote URL, from their local filesystem in packed format and from their local filesystem as an unpacked directory. Of these three cases, importing from the local filesystem in packed form is the most complex (the other two options are really just subcases of this problem), so we will explore this use case for the rest of the post.

Pick a file any file

To enable a user to select a file from their local filesystem Readium makes use of a plain html <input type='file'> element. But if you have done any web development before you will notice that what happens next is completely non-traditional. In a classic web application an HTML form is really a user friendly tool for adding parameters to an HTTP request. When you click the submit button of an HTML form, the browser serializes whatever you typed in the form’s fields into application/x-www-form-urlencoded data, tacks it on as the payload of an HTTP POST request (usually) and sends to the server.

But Readium is 100% client side; there is no server to send the data to. We use the <input type='file'> element only to get a copy of user’s file into our javascript sandbox. Once we have that we use the HTML5 javascript method window.URL.createObjectURL to create a URL that points to the file they selected. This is exactly where we would start if instead of selecting an EPUB from their filesystem, the user entered a URL (like I said, subcases).

XYZ PDQ

The next step is to unpack the file. EPUBs use the ZIP file format to compress and archive their contents. To decompress this content we make use of an open source library for unzipping the content in javascript. Unfortunately, decompressing files in javascript is dreadfully slow. This is because even though it has them, the bitwise operators in javascript are slow. This is because javascript does not have an int type. But, when performing bitwise operations it pretends that it does. The result is that in order for a javascript engine to perform a bitwise operation, it needs to do a conversion from its floating point Number type to the equivalent 32bit signed integer, perform the operation, and then convert back to its Number type.

This performance constraint is what motivated us to start allowing users to load an unpacked directory into Readium. To get this working we use the nifty webkitdirectory attribute on the form <input>. If you have never seen this in action before (or never knew of its existence) there is a pretty good demo available here or better yet, check it out in the Readium source code.

The Extraction

All of Readium’s logic for importing an epub from both zipped and unpacked formats is contained in /scripts/extractBook.js. For those of you who speak the Unified Modeling Language, here is a rundown of what is in there:

Perched at the top of the hierarchy is Backbone.Model. This is not actually defined in Readium. It is an object provided by Backbone.js, a framework used widely throughout Readium. I am planning on explaining our decision to use Backbone in more depth in a future post, but for now the most important part to understand is its Events module. Basically Backbone makes triggering and subscribing to custom event super simple. Here is a quick rundown of it in code:

1
2
3
4
5
6
7
8
9
10
11

// create a vanilla Backbone model
var foo = new Backbone.Model();

// register a handler on foo
foo.on("banana", function() {
  // this code will execute when the banana event occurs
  alert('Wow, that was easy');
})

// fire the banana event on foo
foo.trigger("banana")

Instances of Backbone.Model also have a set of observable attributes, that is to say, they fire change events when they are changed automagically. The entire control flow of unpacking logic is driven by Backone events. Event firing happens both explicitly (ie this.trigger("something")) and implicitly by changing an observable attribute (ie this.set("someprop", "newVal")).

The next level in the hierarchy is BookExtractorBase. This is where all of the shared logic for parsing, managing and writing the imported EPUB to disk lives. I am going to come back to this in the next section.

At the bottom of the hierarchy are ZipBookExtractor and UnpackedBookExtractor. Each of these contains the logic for going through either a ZIP archive or unpacked EPUB and calling the necessary extraction / importing logic (located primarily in BookExtractorBase). Let’s consider ZipBookExtractor.

ZipBookExtractor

Constructor logic is added to a Backbone.Model by overloading its initialize() method. The Readium.ZipBookExtractor.Initialize method does a few things:

1. It makes sure that the a URL has been passed in to the constructor, if not, it throws an exception.
2. If a URL has been passed in, it takes an MD5 hash of the string formed by concatenating a timestamp to the URL. This serves as a unique identifier, which readium uses to keep track of the file and also the name of the root filesystem directory Readium will write its contents to.
3. It captures the src filename of the users upload. This is captured only for the purpose of displaying it later in the UI, and is not needed for any technical reason.

Once a ZipBookExtractor instance has been created, the importing process is initiated by calling its extract() method. This method sets up the order in which the rest of the extraction process should execute by hooking up each method of the process to the event that will be fired upon completion of the previous step. Finally, it calls the asynchronous constructor of Readium.FileSystemApi, which is our own very thin wrapper around the HTML5 filesystem API.

Once the filesystem is opened, the process continues by calling the constructor of our zip library. This constructor is also asynchronous. When initialized, it executes callback with the Zip object as its this context. The Zip has not been decompressed at this stage, only the archive data structures have been parsed, so it does contain information about all of the archive entries. We decompress individual entries as needed (the code for this is in the extractEntryByName method).

What to unpack first

After we perform some very rudimentary validations on the Zip object (mostly checking for the existence of a few essential items) we get into the brunt of unpacking the book. In general when unpacking an epub, what you want to get your hands on is the OPF Package Document but first you need to find it. In order to find it, you have to parse another xml file first: META-INF/container.xml. All epubs must have this file and it must be located at this absolute path in the archive. The container.xml specifies the absolute path of package document within the archive on an xml <rootfile> node. This is the only information that we take from this file.

Parsing the package document

Once we are able to find the package document within the archive the next step is to parse it. The logic for this is contained in the PackageDocumentBase class definition. This is separated from the unpacking code because we also parse package documents right before we display a publication.

Whenever possible, we try to parse xml using a library called Jath. Jath allows declarative, template based parsing of xml into a structure of Javascript objects. Again I will differ the design justification for this to a later post.

At this stage when parsing the package document we are really only interested in the meta data that it contains. Essentially what we are looking for is everything we need to show the publication in the library view (title, author, cover image etc). Once we have this information, we add in a bit more of our own (most importantly where we are going to write the package document on disk) and then save it to the browser’s local storage for quick access. We then iterate through the remaining archive contents and extract them one by one and write them to the HTML filesystem.

Monkey Patching

The last step of the unpacking process is something that I have termed Monkeypatching the URLs. There are a couple of reasons for this but the main motivation is that when we open an EPUB in the viewer, there are no guarantees that it will be loaded in a document with a URL pointing to where it actually exists on disk. The implication is that in order for us to ensure that URLs in individual spine items are handled correctly by the browser (for example consider the src attribute of an <img> tag) we need to convert them into fully qualified, absolute URLs, pointing to where we saved the file in the HTML5 filesystem. This logic is contained in scripts/models/path_resolver.js. This process is a little muddy right now and there are a few bugs left to iron out (so if you are looking for some way to contribute :) this might be a good spot to jump in).

Time to open

Once the book is fully unpacked, monkey patched and written to disk, we fire off an event to let the library code know that we are done. In response, we open the file in the viewer. How this happens, I will save for a future post.

How it works

Because we cannot access the HTML5 filesystem API in most browsers, we are hosting the EPUB files on the server and fetching the content via AJAX from the viewer when they are opened. This means that you cannot actually load an EPUB file into this version of Readium but we think this will be OK for a lot of use cases (think online bookstore that wants to allow access to files for its customers) and there may be ways to implement this functionality (see below).

The next thing you might notice is that pagination of re-flowable content is very broken on most browsers. That is because almost nobody has support for the CSS regions property yet. Thankfully one of contributors has come up with a polyfill that should provide a fallback in these cases and is currently working on integrating it.

What’s next

There is obviously a lot left to do if we want to get this version to a publicly usable state. Here are a few things we have thought about taking on:

• Fix bugs - there are a lot of issues that are stemming from the fact that serving thing over the web is different than serving them from a .crx. We need to take care of these one by one
• Tune up the UI / UX - the Readium UI needs to be tweaked a little to make if feel at home on a mobile touch interface.
• Package up the build as a Phonegap application - This may be a little further down the road, but once done it will give as another means to interact with the filesystem and let users import and read their own EPUB3 files on their devices.

As always in anyone thinks they can help with any of these items (or anything else for that matter). Please don’t hesitate to create items in the github issue tracker or better yet submit pull requests with patches.

Work on native support of MathML in WebKit has begun but is a long way from being ready to use. With MathJax, Readium will be able to render MathML, an important step towards Readium’s full EPUB 3 support. Additionally, MathJax offers zoom for accessibility and cut-and-paste of mathematical content.

The necessary code has been pulled into the master branch and, as of version 0.1.9, Readium displays math beautifully. You can find a sample here.

Thanks to Davide Cervone, MathJax’s Lead Developer, for his help in making MathJax work in Readium.

Our regions based pagination algorithm basically looks like this:

• whenever a repagination event occurs:
  • make a pessimistic guess about how many pages are needed
  • add that many pages to the dom
  • while the last page has overflow:
    • add another page

This was all working well enough in terms of paginating the content. There were some bugs related to click-able areas not being rendered where they were expected but we assumed these were bugs in Webkit / chrome and would get ironed out in future versions. Then one day we found out that regions were going to be shut off by default in webkit. Sure enough I installed chrome canary, regions were gone and Readium did not handle it well. This was not good news for us.

Challenge Accepted

We decided that a short term solution to our problem would be to find a way to allow CSS3 regions to be turned back on. With a little support from the awesome chrome team at google, I managed to stumble through the chromium source code and submit a patch that allows regions to be turned on via the command line. This patch has landed.

So What Can You do About it?

If you are using chrome Canary or you are from the future where chrome has moved to a version in which CSS3 regions are off by default here are the steps you can take to turn them back on:

1. Open a new tab in your browser and enter about:flags into the url bar
2. In the page that opens find an entry called Enable CSS Regions and click the enable link
3. Restart chrome for the changes to take affect

Once you do this, you will may also notice that readium runs smoother and has a fewer bugs. This is all product of webkit’s regions implementation becoming more mature (just as we had hoped).

A Better Solution

We realize that the above solution does not provide the best user experience, and we are currently seeking other solutions. One idea is to distribute Readium with a custom build of Webkit that has regions turned on. This may seem a bit heavy handed, but we were planning on creating a custom Webkit in order support vertical typography all along. A simpler solution that is likely to show up soon will be to degrade gracefully when regions are not available or come up with a pagination strategy that works without CSS regions. This will also help us to take a big step towards creating a version of Readium that runs as normal web page (not packaged as a chrome extension). If you have any good ideas for how we might do this please put them in the issue tracker.