Thursday, June 2, 2011

Javascript and geolocation in Fixed Layout ebooks on iPad/iPhone

(Updated again on 17 June 2011 since Apple has approved the book and listed it in the iBookstore.)
(Updated with new discount on Friday morning.)

Rick Gordon sent a link to an interesting photo book the other day: it's a collection of photographs of San Francisco, set in fixed layout format as if it were a coffee table book. The photographs are lovely but I have to admit the whole thing just made me want to create my own. I have thousands of pictures of Barcelona and there is so much that I'd love to share about this place. I was totally inspired. Here's what I came up with:

Barcelona Beyond Gaudí Demo: Interactive Fixed Layout ebook from Liz Castro on Vimeo.  ($1.99 from iBookstore. Or $2.99 with $1 discount to any of my other EPUB titles* if you buy it directly from me.) It is a DRM-free EPUB file with Javascript that passes EpubCheck, and has been approved and accepted by Apple iBookstore. It is compatible with iPad, iPhone, and iPod touch.

The hardest part of the project, of course, was choosing the photographs. I decided to focus this first collection on architectural details of lesser known buildings. Tourists and Barcelonians alike are more than familiar with Antoni Gaudí and his Sagrada Família and Dragon House, so I decided to avoid his admitted gorgeous buildings altogether in order to highlight something new. I chose 50 landscape oriented photos to keep my layout simple and straightforward.

I wanted to display information about the photos but I also wanted to use as much of the screen as possible. I tried lots of different systems for adding captions—below and above the photos—but then I thought how nice it would be to add a caption right on top of a photo and then hide it when the reader was done. I'm no Javascript expert, but I was able to carve out a very simple script that changed the stacking order of my photographs depending on what was clicked. At first, I used an info button that a user could click to make the information appear. But it was too big on the iPad and too small on the iPhone. Then it occurred to me that I could use the whole image as a link, at least the left half of it: a user can click anywhere on the left page to make the caption appear. Then a click in the caption makes the caption disappear so that the entire photo can be viewed without distraction. I think it's very cool :)

Since iBooks already reacts to a user's clicks by showing and hiding the navigation system across the bottom and top, the user has to press a little longer than necessary to get the caption to show. In addition, the user has to avoid turning the page by clicking too close to the left margin. Finally, I decided to display the caption at the bottom of the page, but not too close so that it wouldn't be obscured by the navigation system.

The more I thought about the caption, the more I wanted to add location information so that if a reader wanted to visit one of these special buildings, they could find just where they were, and even chart a course. Since the book works fine on iPhone, readers could take a tour while they were walking about Barcelona. I learned how to create links to Google Maps using decimal coordinates for the buildings in question, and then I added a Maps icon with a link and made it appear along with the caption. When a reader clicks the Maps icon, they can choose to leave iBooks and view the location of the building in the Maps app. They can click the left Street View button to view the building right in the context of its own street, or click the Directions buttons to see how to get there from where they are that minute. It's pretty fun to play with. The only downside is that there is no quick way to return to iBooks once the reader is done looking at the map, short of clicking out of Maps and then clicking into iBooks again.

I was careful to write the Javascript in such a way that the EPUB file validated perfectly both in EpubCheck and in iTunes Producer. I am still not sure that Apple will approveApple has approved the file, thoughsince there's nothing in the specifications that says you can't have Javascript or link to Google Maps. But who knows.. Here is the link to the US iBookstore. At any rate, you can buy the Barcelona Beyond Gaudí EPUB file directly from my site as usual. It's only $2.99 $1.99* (after discount). As usual, it has no DRM so that you can unzip it and look at my code.

It's probably time I learned a bit more Javascript. There are just so many possibilities. This is just the tiniest tip of the iceberg. But boy it's exciting up here!

You'll note that Barcelona Beyond Gaudí costs $1.99 on the Apple iBookstore, but $2.99 on my own site. That's because my shopping cart (Kagi) won't let me make the price any lower. So, if you buy it directly from me, I'll include a coupon for $1 off any EPUB related title that I sell to make up the difference.


  1. Hi, Liz,

    I haven't seen the book yet, but thought that I'd add that without JavaScript, you can link through the Maps applications two ways:


    2) Or use a direct call to with: "maps://daddr=San+Francisco,+CA&saddr=cupertino"

  2. More on Google Maps URL construction at

    Note also that there are other iOS apps that can be accessed by URL:

    The protocol tel will launch the Phone app if available, and Contacts if not. I'm still seeking documentation on this stuff. So far, it's been mostly experimentation, but I had previously located (now lost) some documentation directed to app developers inside of

  3. Ahh, I think I understand now that the map links are not the issue that's solved by the Javascript. Oh well, maybe the info will be useful to someone anyway.

  4. Hi Rick,
    Thanks for posting the links. The Google wiki page is just the one I used to learn how to create my links that go directly to the landmarks in question.

    As you noticed the Javascript is not involved in the Maps. I use it to make the caption (and link to Maps) appear and disappear so that the information can be hidden and the image viewed without distractions.

  5. Hello Liz, your demonstration is awful. I owned your book in french, "Créez des documents epub", but there is no explanation inside about this fabulous fixed layout format. Did you make a tutorial about this technic? Anyway, I'm going to download immediately this "Barcelona"! :-)

  6. @Urbain, trop urbain... oh dear, awful? But you still want to buy it, so it can't be all bad!

    It's not included in the EPUB book because it didn't exist then. So, I have written a Fixed Layout miniguide, (though it doesn't cover the Javascript that I used in this example) more info here:

  7. Hi Liz,

    I am not sure whether Apple will accept this kind of ePub books. But for me, I have to sell my books outside iBookstore. It seems that Apple does not accept my enhanced ebooks, according, which contains audio, JavaScript and HTML5 Canvas. Here is my website:


  8. @Liz excuse-me, I'm not english speaker and I made some miserable linguistic mistake. I shall write "wonderful", "stunning", "ecstatic", etc. ;-)
    Thanks for your link.

  9. I love that you're addressing how to make an attractive photo book. This is my focus. But I have a question:

    Does your epub work only on an iPad or iPhone? How about on other ebook readers such as Adobe Digital Editions, the Barnes and Noble Nook, or any of the epub readers that run on Android?


  10. For "traditional" ePubs, I've been experimenting with another technique where tapping an image reveals a hidden caption. This involves putting the caption in a paragraph of height 0 - with the overflow visible by default; then immediately covering it up by following directly with the image. Then (via a bit of JavaScript invoked by tapping anywhere on the image) set the image opacity to .5, say, and the caption now shows through the faded image. Tap again to toggle the opacity between .5 and 1. This works fairly well, but wonder if it's considered legal.

  11. Wow. I am so glad that you are existent! Your photo book is great and it gives me some tools that I need to continue work on an ePub project. Thanks so much. You have helped a whole lot of people on theirs as well, I am sure.


More of my books