How to display footnotes from an EPUB book into a dialog box?

The objective

The EPUB 3.0 specifications are designed to take advantage of HTML5.

From this version, an application for reading an EPUB book can display notes and footnote references separately by displaying the text of the note differently , for example, in a separate dialog box instead of showing them from within the main book text or chapter.

Having designed an Android  app that reads these kind of files using a WebView, my objective was to take advantage of this new EPUB feature.

Preview

EPUB book Moby-Dick downloaded from this link:

https://code.google.com/p/epub-samples/wiki/SamplesListing

mobydick_chapters

Without any particular treatment of the following EPUB annotation epub:type="noteref"used in the text of the EPUB 3.0 footnotes, all the footnotes and references using this annotation will be by default displayed with the rest of the text at the end of the page. You can see an example of this default behavior on the next image on the left.

 mobidick_default_footnote    mobidick_noterefdialog

On the other hand, in the image on the right, you can see the result of displaying the same text, but this time using a dialog box which can only be seen when the user clicks the link to the reference. This eliminates the need for the footnote text to be displayed at the end of the main page text.

The solution

My solution is built on the realization  that any Android application has to execute JavaScript code on the Android WebView component. A custom Javascript function helps me to retrieve the Id of the HTML element that was clicked using the onclick() event from the WebView window.

Then, once having verified that the clicked element contains the annotation corresponding to epub:type="noteref", I retrieve the text from the target HTML file at the target location and finally I show this text in a dialog box using the Android AlertDialog component.

The solution in details

In summary, I’ve separated the whole task into three parts:
  1. Creating the JavaScript file containing the custom code I want to use in all my HTML pages from my EPUB book. I’ve added this file to the ‘assets’ folder of my application’s project in order to be able to use it during run-time. The process of accessing this file could be done using the ContentProvider class, I did access the file this way but in order to avoid complicating this explanation, I won’t  explain this process here.
  2. Creating the Java class that is going to act as a bridge between the JavaScript code and the objects of my application.
  3. Injecting the JavaScript code into each webpage loaded in the WebView widget of my application.

1. JavaScript code to be injected into each HTML page to display.

For the purpose of this test I have named the JavaScript file: epub-support.js, this file has only one function used to intercept the onclick event of the page.

On each click event of the page this function calls a method of my ‘WebViewJavaInterface’ class which I have given the alias of ‘Android’.

2. WebViewJavaInterface class

This class contains three methods used for displaying the text of the footnote reference inside a dialog box.

The method showNoteRefDialog is the only one called directly from the JavaScript code, this then calls the other two methods, the first one in order to retrieve the footnote’s text and the second one in order to display the retrieved text in the dialog box.

The  getNoteRefText method then gets two parameters: the URL of the local file to read and the keyword of the element found in the text of the file. This method uses also another method from a custom class that I made to help me read and load data from any XML content that I called  LoadHelper.readFootNoteFromContentFile.

This last method uses the SAX library available for Java, but again this is another subject that I won’t explain here in detail.

3. JavaScript injection and setting up the WebView widget.

And next you will see the loading of each URL into the WebView.

 

This last method loadUrl takes as parameters the WebView used to display the XHTML pages from the EPUB file and the L’URL to be displayed.

My method FileIO.getContents returns the content of the file passed as parameter with the selected encoding, this method uses the Java Class RandomAccessFile in order to accomplish this task.

Finally I’ve included the following links that were very useful  to me concerning the same subject (reading EPUB files, footnotes, etc.) and I hope it could be useful for you too:

Inside EPUB (anglais) – Inside EPUB EPUB 3 Overview (anglais) – EPUB 3 Overview Creating pop-up footnotes in EPUB 3 (and thus in iBooks) (anglais) – Creating pop-up footnotes in EPUB 3 (and thus in iBooks)