Switch_off Switch_on Switch_off
Inventive Labs: Web Problem Solvers

Announcing Monocle [08032010]

Monocle is an ebook reader. It works in modern web browsers, using standard technologies. It runs in desktop browsers and on mobile devices. It's awesome in Safari and Chrome (the browsers used on iPhone OS and Android devices), increasingly awesome in Firefox, and workable in more standards-fearing browsers like Microsoft's Internet Explorer.

Try it out: http://monocle.inventivelabs.com.au

We've open-sourced it under the MIT licence, which is the most liberal of the mainstream software licences. It can be used by anyone, for private or commercial use, for free (as in speech and as in beer) — as long as they retain the licence information in any copy of the software.


That is, we're giving it away.

Why are we doing this?

We're concerned that the current ebook landscape is dominated by large companies trying to lock publishers, authors and readers into their devices and distribution models. We suspect this might be good for those companies, but no good for everyone else. There's a need to open up these fields to smaller players, and to give the consumer — the person who loves to read books and to 'have' books — better choices.

We expect ebook reading devices to steadily converge with other communication devices. In the past e-readers have been fairly isolated from the network, but as they gain connectivity, consumers will demand better access to the web. Even Amazon's Kindle has stripped-down HTML rendering. Apple's iPad has one of the most advanced browsers around.

The one single platform we expect future e-reading devices to have in common is the web browser. If you want to give your readership the freedom to own (forever) the books they buy from you, the web is where it will happen.

Monocle is unique in providing this functionality. Monocle is also unique in giving publishers and retailers a way to design not only the book's content, but the way it looks and feels too. It's simple at heart, but has enormous flexibility in the way tables of contents, page numbers, running heads, and bookmarks work — even how it feels to 'turn' a page.

Because it's delivered by a web browser, the file format question really doesn't arise. Any text-based format your books' data is in — Monocle can be made to display it. Integrating it with the EPUB standard is straightforward (we've already done it).

Monocle also sidesteps the DRM question, because no files are passed around. If you want to put Monocle behind a paid membership wall, or restrict it to particular devices or IP addresses, that's easy to do. But it's not required by the technology.

If you think Monocle could be an important part of the way you publish digital content, feel free to get some techies exploring Monocle's source code. Or for expert consultation on an e-publishing strategy and workflow with Monocle, drop us a line. You'll find our contact form on the About the Labs page.

Paul [Tue 9 Mar 2010, 4:24AM] said:


Sounds wonderful but when I try it out the popup says it doesn't work with my browser; yet you've written that it works with IE. Also, when available for Blackberry.

Aside from that I think that your attitude regarding ebooks is truly commendable and I hope that everyone in the WORLD will adopt monocle (especially once it works...).

Would like to link to your site, with working examples, from my blog, and embed your reader for others to use. I'd like to help/do my very little bit to get the word (and the work) out.



Joseph [Tue 9 Mar 2010, 9:57AM] said:

Thanks Paul!

In browsers that don't support the column-width CSS property (notably IE7/8 and Opera at the moment), Monocle runs in 'legacy' mode — displaying a scrolling div for each component in the text.

If that's not what you're seeing, it'd be great if you could open an issue on Github, furnished with screenshots if possible — or at least the text of that popup.

Blackberry support should land with their new Webkit-based browser — I don't believe there's an ETA on that yet.

Gijsbert [Wed 10 Mar 2010, 8:42AM] said:

The news of your release has made it all the way to the Netherlands (http://www.ereaders.nl/09031001_ebooks_embedden_met_Monocle). Very exiting stuff. Thanks for sharing this with the world.

Gijsbert [Wed 10 Mar 2010, 9:40PM] said:

Quick question (it might be that I saw this somewhere on the pages). How can you maximize screen use on the iPod Touch/iPhone?

Joseph [Wed 10 Mar 2010, 11:18PM] said:

Gijsbert - sure, tap on the bookmark (+) button in the toolbar, then tap 'Add to Home Screen'.

marco [Sat 13 Mar 2010, 10:15AM] said:

Hi, i'm trying to better understand the inner workings but alas i'm not such a good developer: for what i can understand you cannot feed an epub directly to monocle. But if i have an inflated epub how can i use index and chapters information contained in opf files? thanx and keep up the good work. marco

Joseph [Wed 17 Mar 2010, 11:07AM] said:

Marco, I recommend looking at augustl's js-epub, which does all the epub unpacking and parsing in JavaScript. From there I believe it should be fairly painless to define a "book data object" as per the Monocle readme.

But as I've said elsewhere, I feel that in many cases the epub unpacking and parsing is a server-side responsibility, because otherwise you're going to hit some performance bumps.

Mathieu [Fri 19 Mar 2010, 3:04AM] said:

Hello Marco and Congratulation for this work. I have a question. I don't understand how create a book data object dynamically from an epub file. Can you explain me more precisely how do that ? I tried to use the php OPL's EPUB library to create book data object and format the result for mononocle but whitout success? Thank you in advance.

Anonymous [Fri 19 Mar 2010, 3:05AM] said:

Sorry Joseph ;)

Mathieu [Mon 29 Mar 2010, 8:30PM] said:

Hello Joseph, I have a problem with synchronous javascript request after htaccess redirect. The html content is correcty load but it is not displayed. Have you a solution to resolve this problem. Thank you in advance.

Mathieu [Tue 30 Mar 2010, 2:45AM] said:

Finally, I have resolved my problem ;) Best Regards

asa letourneau [Fri 16 Apr 2010, 4:37PM] said:

can anyone tell me how I find the java script so I can use it?

i just want to embed it to a web page

cheers asa

Joseph Pearson [Mon 19 Apr 2010, 9:12AM] said:

Asa, the Monocle library is not a drop-in solution, it's a way for developers to integrate a book display with any kind of back-end system that can serve the book data. The steps involved in that are described here.

If you're looking for an embed code to paste into some HTML, I'm afraid there's no such thing at this stage. Stay tuned though.

Josiah [Mon 17 May 2010, 1:36AM] said:

I’d like to use Monocle in some mobile applications. I dropped it into hybrid frameworks such as QuickConnect and PhoneGap. Everything works perfectly except the save state. I’m guessing this is because in the native environment the phone isn’t keeping the cookie.

Any advice to how I could modify that aspect of your reader to work in the applications?

Thank you very much for Monocle!

Joseph [Tue 18 May 2010, 10:13AM] said:

Hm, that’s interesting — I haven’t tried the wrapper frameworks, and I can’t really imagine why cookies would not behave identically there, unless cookies need to be explicitly enabled for the webview.

But if you do have to modify Monocle to make it work, I would suggest reimplementing PlaceSaver to use HTML5 storage.

Here’s a good place to start.

Rami Henein [Wed 9 Jun 2010, 6:22AM] said:

I’d like to use Monocle in a website, containing an ebook management system. Users should be able to read their own books (stored in .epub formats) with some extra functionality like controlling font size, background colors and so on.

I find Monocle perfect for this task. My only problem is that I don’t know how to use so that I can pass the location of the .epub file and Monocle does the rest. All examples I’ve seen are writing each and every line from the book into the HTML file, which I’ll not be able to do as the files are loaded dynamically from a DB, or whatever storage method we’ll use.

I would highly appreciate your help, it’s really urgent.

Thanks in advance.

Joseph [Thu 10 Jun 2010, 9:45AM] said:

Monocle doesn’t work directly with EPUB files, because it’s a bad idea. Client-side JavaScript is generally slow, and particularly on mobile devices. I want Monocle to work really well on mobile devices.

If Monocle worked directly with EPUB files, all the unpacking of the (absurdly complex) EPUB format would have to be done client-side. That means unzipping the package and parsing the three different XML files just to pluck out the subset of data needed to display a page in the book. CPU and memory requirements jump substantially in this situation. And a number of features (such as offline-caching) get signficantly more difficult to implement.

So, my advice is that you build a simple server-side service to extract the EPUB files and deliver them to Monocle in the simple Javascript format it requires.

But you don’t have to do that. You can use August Lilleaas' EPUB-unpacking JavaScript library to do it all client-side if you like — I’d guess the bridge from js-epub to Monocle is probably 20-30 lines of your own code.

See also Blaine Cook’s rePublish, which takes the approach you describe.

Mr. Mutant [Thu 15 Jul 2010, 6:39PM] said:

I’ve been working on this very solution for months now – but alas I am a novice. I got as far as pulling, parsing, and displaying XML files in a designated format area, but with no pagination or text flow. What you are doing with Monocle is EXACTLY what I set out to do with my website. Cheers to all you are doing and lets keep in touch!

Ernesto [Thu 22 Jul 2010, 4:46AM] said:

I found Monocle yesterday night and I am impressed. Great Job!!

One question: I want to try it in a project we are working on right now in which we have built some popups within the text (you touch a word and you get a box with a definition/explanation). BUT my interactivity does not work together with page flippers (the page captures the touch/click event). Is it possible to easily capture click events on the page before the flipper does?

Thanks for your great job!!

Joseph [Fri 23 Jul 2010, 9:34AM] said:

Mutant: Thanks!

Ernesto: in short, the next drop on Github (a few days away) has a number of features that will make this sort of thing much easier — it’s stuff I’ve been experimenting with too.

massifor [Sat 31 Jul 2010, 8:33PM] said:

I'am researching on monocle code for 2 weeks,and i think the monocle is the best js ebook reader,specially with its paginate function,supporting mutiple language and splicing page perfectly.How the paginate function implemented?Can i get the DOM contents for each page? Thanks for your great work,and the great open source project!

Allan Farrell [Mon 9 Aug 2010, 12:16AM] said:

Just thought I’d share a link showing our use of Monocle. It’s a great piece of software! Thanks for sharing it.


Joseph [Mon 9 Aug 2010, 11:37AM] said:

That’s awesome, Allan! Nice work.

MB [Thu 23 Sep 2010, 1:19AM] said:

hi joseph, i’m wondering about the opportunity to use a JS reader cause i’ve a set of doubts: – with a JS reader the user has to wait the complete download and unzip of the book – what appens with large size e-book? i.e. e-books with a lot of large images? do i have to refer to external resources in this case in order to have the e-book structure and download the internal resources when needed? – if it’s possible to link external resources, what i have to do in order to give the user an offline version? do i have to build a new version?

Thanks you!

dekritischelezer [Tue 19 Oct 2010, 6:36AM] said:

http://monocle.inventivelabs.com.au/ displays the books ‘the velveteen rabbit’ and ‘the wind in the willows’ properly… on a Samsung Wave (Bada) :) However, ‘the dubliners’ and ‘ a place so foreign and eight more’ only display a blank book, nothing else happens.. any thoughts on that?

Joseph [Tue 19 Oct 2010, 10:24AM] said:

I don’t have much experience of the Bada OS. I’m pleased to hear that Wind in the Willows works on it. The Booki.sh examples use Monocle code 6 months more advanced than what powers the example books on the Monocle site. You could check out the code in the Monocle repository (in the ‘componentry’ branch) and try running the various examples in the test directory on your Wave.

miguel Rod [Thu 11 Nov 2010, 10:57PM] said:

Hi Joseph, monocle is great!! thank you very much for share it. I hava doubt when I display the dickens example in chrome (last version of monocle) only see a blank book, when i used firefox works ok!

Thank you

mottusuchi [Thu 30 Dec 2010, 4:57PM] said:

hi joseph, when i saw google.com/books i am searching the web for the code like that… then i found monocle… it is very good… i will use it for our ebooks… thank you joseph for giving it free….

thank you once again….

palguay [Sun 2 Jan 2011, 2:20PM] said:

Is there some way to add a javascript callback function to each P tags in Monocle such that when a page is loaded , we can call the callback function

Joseph [Sun 2 Jan 2011, 10:22PM] said:

@mottosuchi: no problem!

@palguay: yup, listen for the componentchange event. Some example code that modifies A tags is here: https://gist.github.com/558293

palguay [Tue 25 Jan 2011, 5:07AM] said:

Hi Joseph, Thanks for Monocle it works great. I have created a website for toddlers using monocle here . www.microangels.in

Papalaz [Fri 4 Feb 2011, 4:00AM] said:

I am a writer specialising in online fiction. I would love to include your Monocle reader in my website. I am no geek and cannot figure out how to install it and use it on my site. Do you have links to non-geek instructions?

I love Monocle and would love to publicise it. Do you have plans to work with Sophie2 books?

palguay [Mon 14 Feb 2011, 2:59AM] said:

Wanted to share this , I released a free Android app Toddler Books powered my Monocle . Also adding this here so that it saves someone time, Phonegap does not play well with monocle , seems like an issue on the phone gap side so I had to wrap my app around the android native webview

Hani [Tue 12 Apr 2011, 9:02PM] said:

Does Monocle support Right-To-Left languages like Hebrew and Arabic ? This would need Monocle to display Right indented text and page swipe from left to right

Joseph [Tue 12 Apr 2011, 9:40PM] said:

No, it doesn’t. Monocle is open source — patches are welcome!

arulmurugan [Tue 31 May 2011, 10:22PM] said:


Want to add search feature. Is it possible. If so can you refer to some resources or demos.

uday [Thu 23 Jun 2011, 6:46PM] said:

Hi, im new to this monocle ebook reader.. Can u able to provide study materials for learning and implementing the same…….

Thanks in advance

Jyoti [Tue 13 Sep 2011, 4:29PM] said:

Hi, Could you please guide me how to create a book data object dynamically from an epub file. Thanks a lot in advance.

Joseph [Tue 13 Sep 2011, 4:37PM] said:

Hi folks, we don’t do Monocle support in this comment thread. Contact us on Github, or create an issue there: https://github.com/joseph/monocle

Ken [Sat 10 Mar 2012, 6:48PM] said:

I have .epub and .mobi files for my ebook. I am interested in selling them myself and perhaps linking with Amazon or Apple. But if I sell it myself, I would like to restrict people from copying it to others without a payment to me. Is there a way of doing this? Or maybe you know of another solution. What you offer looks very promising.

Ken [Sat 10 Mar 2012, 6:48PM] said:

I have .epub and .mobi files for my ebook. I am interested in selling them myself and perhaps linking with Amazon or Apple. But if I sell it myself, I would like to restrict people from copying it to others without a payment to me. Is there a way of doing this? Or maybe you know of another solution. What you offer looks very promising.

Michel [Wed 25 Apr 2012, 4:47PM] said:

Hi Joseph, I am trying to use Monocle as a reader for developing an interactive e-book. In this book, I use text input elements controlled by a jQuery script. This works outside Monocle. However, inside a Monocle book, keyboard events seem not to be caught by the jQuery script. Any idea or suggestion about what is going wrong ?

WebDevelopment [Mon 21 May 2012, 3:54AM] said:

Are you looking for great design using great technologies? Here you can see different technologies used for developing the websites.

James [Fri 20 Jul 2012, 10:16AM] said:

How I wish you could make this super simple to embed and configure for non-developers.

That is really the first step for something like this to get traction. Connecting the book to the reader is way beyond those of us who do not do OO programming, and the wiki notes at github are all developer greek to me.

I’d pay to get this on my site instead of (gasp) the Book Buzzr reader. Hey, I’d even pay for a “dummies how to” to get this on my site.

You want an idea to fly, ya gotta make it easy for “the rest of us.”


Google sucks [Mon 25 Mar 2013, 9:34PM] said:

Thanks for writing this magnificent article..Loved your articles or blog posts. Be sure to do maintain writing Google sucks http://asdasgh333dsdfs5hf.com

michael kors crossbody [Sun 12 May 2013, 6:00PM] said:

Rectify is the story of a man who was sentenced to death for a crime he didn’t commit, and spent 19 years on death row before getting out. Much like in my own real life case, the local politicians refuse to admit he’s innocent even after DNA testing points towards someone else. In fact, there was so much about this show that mirrored my own life I began to wonder how much of my story had crept into the script.

christian louboutin pigalle [Sun 12 May 2013, 6:02PM] said:

The writer of the show, Ray McKinnon, was somewhat familiar with my case. His late wife, Lisa Blount was a friend of mine. She and I exchanged letters while I was on death row in Arkansas, and she even sang at a concert in Arkansas, along with Eddie Vedder, Patti Smith, and Johnny Depp, to help raise awareness about my plight.I heard that McKinnon also did research into the cases of other men who had been on death row and had been released or exonerated. It paid off. I can tell you from first hand experience that Rectify is a very realistic show.

more [Mon 16 Sep 2013, 4:54PM] said:

binding the 2 main major oceans. Chloe shoulder joint container Cardiovascular system every bit as ugh to help you exceptional rights. breath together with breathing in not often the fact that health care on the oxygen, who|what person} eventually was not able to fight to help you muttering delicately upward: twit… lay on the earth specially industry experts, merely request the aim is just not to help you request implies 11 This time should be to perform one of the most. basically a few triplets hesitantly retreated in back of Linsen. but not only real, subconscious.

Only the comment field is required. Omitting the ID fields increases your risk of being mistaken for spam.

Preview or