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
- Download the example Jeremiah Book EPUB, as mentioned above.
- Change the extension from .epub to .zip. Note: If you are on Windows you might want to take a look at this link.
- Unzip the file. Note: On a Mac the inbuilt unzip will not work - see "Free Tools / Utilities" section below.
- In the folder with the unzipped files go into the OEBPS directory
- 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.
- 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:
- It locates all the links and takes over the click handler.
- When the user clicks a link this code is activated.
- 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.
- 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.
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:
- Stuffit Expander (Mac)
- ePub Unzip (Mac)