How do I link scriptures in an EPUB file to Equipd?

Wouldn't it be nice if we could have the EPUB files open the scriptures in Equipd? Especially for users who are reading the Bible in multiple languages!

This article outlines one approach that can be used to get an EPUB to open scripture links in Equipd. The basic steps involve opening an existing EPUB file, inserting a JavaScript file, changing some existing files to point to this JavaScript file, and then putting the EPUB file back together again.

Please Note the Following

Before we get started please take note of the following points just to ensure we are on the same page:

  • The following instructions are intended for users comfortable with editing (X)HTML files and using tools like ZIP from the command line. 
  • This article is a "Proof of Concept". It is not intended to be the ultimate solution - it is just proving that an EPUB can open scriptures in Equipd, and providing some basic guidelines to explain how it works.
  • I am not able to provide ongoing support for this process. The basic steps and principles are outlined below, along with a working example to look at - the rest is over to you to work out.
  • If you get really stuck you can contact Victor who has offered to help others, but please be very considerate of his time.
  • This solution only enables scripture links to open in Equipd if the following conditions are met:
    • The EPUB reader must support EPUB Version 3 - which supports JavaScript. 
    • The EPUB reader must be running on an iOS device (iPhone/iPad/iPod). This makes sense because Equipd only runs on iOS devices anyway.
    • If the reader does not comply with the above then the scripture links will still work - but they will not open Equipd.
    • The solution is tested and works great in iBooks

How to edit an EPUB file and link to Equipd

Right - let's get down to business. 
To begin with please download the working example of the modified Jeremiah Book. This EPUB has already been modified to open scriptures in Equipd and provides a live example for you to understand and experiment with.
  1. Download the example Jeremiah Book EPUB, as mentioned above.
  2. Change the extension from .epub to .zip. Note: If you are on Windows you might want to take a look at this link.
  3. Unzip the file. Note: On a Mac the inbuilt unzip will not work - see "Free Tools / Utilities" section below.
  4. In the folder with the unzipped files go into the OEBPS directory
  5. Have a look for a file called "equipd.js". This is the file that does all the magic. Open this file in any text editor. You can also view or download this file from here.
  6. Open up a chapter file like 03_JR_CH.1.xhtml in any text editor. Have a look around line 8 for this entry: 
<script type="text/javascript" src="equipd.js"></script>


So what is happening here? How does this work?

When you open a chapter in the Jeremiah Book, the chapter will now include the "equipd.js" file. This file contains instructions that go through the following steps:

  1. It locates all the links and takes over the click handler.
  2. When the user clicks a link this code is activated.
  3. The code checks that it is running on an iPad/iPhone/iPod AND that it is a scripture link that was clicked. If these conditions are not met then it will allow the default link behavior to take over.
  4. If it is a scripture link then it will use the Equipd URL Schemes to pass the scripture to Equipd to look up.

The beauty of this approach is that the original scripture links are not changed. This means that the links in this modified EPUB file should continue to work if the EPUB reader does not support JavaScript, or if you are using an EPUB reader on a desktop computer or non-iOS device.

If that description does not make much sense to you then not don't worry about it too much.

Right, so now we have seen what to change inside the files - how do we zip it back up into a single EPUB file again?
 

How to Zip the EPUB file back up again

So this is the most important step to get right. You cannot just "zip" up the entire folder - while this may work in iBooks, in general it will not comply with the EPUB standard, and will break in most other EPUB readers.

At the bottom of this page is some links to some tools that may help you to zip up your EPUB file. But here are the manual steps that must be taken.
On a Mac f rom inside the folder that contains the EPUB contents run the following commands: 
zip -X Jeremiah.epub mimetype<br />zip -rg Jeremiah.epub META-INF -x \*.DS_Store<br />zip -rg Jeremiah.epub OEBPS -x \*.DS_Store

Tips:

  • Make sure that your filename does not contain spaces or special characters as it will not work in all EPUB readers.
  • When you try to install a modified EPUB in iBooks, it often will just ignore the newer file and keep using the older version. Try deleting the existing file before installing the newer version.

Free Tools / Utilities 

The following tools may help with the process of unzipping / zipping EPUB files.

Unzipping:

Zipping:

The Future of EPUB files and Equipd

In the future the goal is to allow you to open any EPUB file in Equipd and to be able to highlight and annotate - so you will not even need to go to iBooks hopefully! But this is a while away yet. So this is just one solution you can use in the meantime, if you feel inspired.
Ideally somebody would take the process outlined above and  write a tool to automate it. I imagine a tool that allows you to import an existing EPUB file, press a button and output the new EPUB file with the links ready to go. Maybe I will get around to doing this one day, but I already have a lot on my plate supporting and improving Equipd - so in the meantime maybe you want to have a go? :-)

Still need help? Send me a message Send me a message