CustomReader (old version)

Note: This page is about the old, pre-Safari 6 version of CustomReader. See this page for information on the new version, which requires Safari 6.

Safari Reader is nice, but isn’t it annoying that you can’t change the font it uses? Palatino is so 90s. Hey, Reader! System 7 called, and it wants its font back! In fact, all you can change is the text size. Is that stupid? I thought so. So I wrote CustomReader as an alternative.

screenshot
CustomReader’s default style

With CustomReader, you can change pretty much anything you want about how the page’s simplified content is presented. Changing the font to your favorite is just the beginning. Want to make the column narrower? No problem. Prefer indented paragraphs with no space between? That’s easy. Fancy making images semi-transparent until you mouse over them? Okay!

Almost anything is possible, because CustomReader lets you directly edit the reading view’s HTML and CSS. Wait, did I say it “lets” you? I should say it makes you edit those things. If you want to change anything from the default style, that’s what you’ll have to do, because CustomReader does not have any checkboxes, radio buttons, menus, sliders, or other fancy UI controls to change things indirectly. If you’re afraid of a little HTML/CSS editing, well, CustomReader isn’t for you.

screenshot
CustomReader’s CSS editor

CustomReader has another feature that may be of interest to some. If you find yourself frequently invoking CustomReader on a certain kind of page at a specific site—for instance, articles on the New York Times website—you can have CustomReader automatically enter reading mode whenever you open that kind of page.

How to Use CustomReader

Getting started

The first step in using CustomReader is obtaining a free API token from Diffbot.com. CustomReader relies on Diffbot to provide the simplified page content for its reading view. While the basic Diffbot plan is free, it only allows 10,000 API calls per month. That’s plenty for most individuals, but if CustomReader were to use the same token for every user, that limit would quickly be exceeded. That’s why you have to get your own token.

The first time you click CustomReader’s toolbar button, the extension will open a popover or tab explaining how to get a Diffbot API token. (Don’t worry, it’s really simple. You just have to go to their signup page—the link is in the popover—and provide an email address. Diffbot will then mail you the token right away.)

Once you’ve received your free token, enter it in the same popover or tab. Now you’re all set to start using CustomReader.

Invoking the reader

There are three ways to start the reader:

  • Click CustomReader’s toolbar button (the one that looks like a pair of sunglasses).
  • Right-click a web page (but not on a link or an image) and select “Read This Page with CustomReader” from the context menu.
  • Type the keyboard shortcut, ⌘⇧R (that’s Command-Shift-R).

CustomReader will briefly display an indicator on the page to let you know that it’s fetching the simplified content from Diffbot. Depending on the amount of content on the page, how busy Diffbot is, and the quality of your internet connection, this can take anywhere from less than a second to several seconds. (CustomReader will time out and give up after waiting 30 seconds.) When the simplified content has been downloaded, the reader will open.

Exiting the reader

To exit the reader, either press Esc or click the margin of the page.

Customizing the reader

Now for the good stuff. To start editing the reader’s HTML/CSS template, you can do one of two things. If you’re using Safari 5.1 or higher and you haven’t hidden CustomReader’s toolbar button, you can long-click it to open the editor in a popover. (By long-click, I mean click and keep the mouse button down for a second.) The other way to open the editor is to right-click the page while in reading mode and select “Open CustomReader Settings”. This method is available even if you’re using Safari 5.0.x or you’ve hidden the toolbar button. (In either of those cases, the editor will open in an iframe within the page itself, not a popover. The iframed editor can be moved around by dragging its title bar.)

The editor consists of three tabs, entitled HTML, CSS, and Auto-Read. The HTML and CSS tabs are for…wait for it…editing the template’s HTML and CSS, respectively. (The Auto-Read tab is described in Setting up auto-read, below.)

To edit either the CSS or the HTML, just click inside the appropriate box and start typing. To save your changes, click the Save button or type ⌘S. To preview changes before saving them, hold down the Option key. To restore the default markup or revert to the last saved version, click the appropriate button.

Please note: Being mere HTML <textareas>, these “editors” are pretty darn crude. You’ll probably want to do your actual editing in a proper text editor, and then paste the markup into CustomReader.

Notes about editing the HTML

When you’re editing the CSS part of the template, you can do whatever you want without worrying about breaking the template. But when you’re editing the HTML, there are a couple of things to be aware of, because you don’t want to delete—or change the IDs of—certain tags that are essential to CustomReader’s operation.

These are the things you want to be careful about:

  • The single most important element is the <div id="story">. This is the element that contains the main body of the content downloaded from Diffbot. Don’t delete this element or change its ID, or you’ll have nothing to read.
  • The elements <h1 id="title">, <time id="date">, and <span id="author"> are supposed to contain the corresponding bits of information from the web page. (Not all of these items are provided by Diffbot for every page, however.) You can delete these tags if you want, but it’s probably a better idea to just hide them with CSS display:none or visibility:hidden if you don’t want to see them.
  • The element <img id="icon"> is for the site or page’s icon, which Diffbot sometimes provides. In the default CSS, this element is hidden with display:none.
  • The <a class="exit"> elements exit reading mode when clicked, but they are hidden by the default CSS.
  • You can change the tag name of any element in the template, and you can of course add or rearrange elements at will. Just don’t change the IDs of the ones mentioned above, as CustomReader’s JavaScript code refers to them by their IDs.
Setting up auto-read

The auto-read feature uses regular expressions to identify pages for which CustomReader will be automatically invoked when you visit them. This works because most of the time, similar pages on a particular site have URLs that are similar in specific ways, and regular expressions can be used to differentiate these URLs from those of dissimilar pages.

Take, for example, the website of the New York Times. Here’s the URL of a typical story page from that site:

http://www.nytimes.com/2012/06/07/opinion/the-age-of-unsatisfying-wars.html

You’ll notice that these story URLs—as opposed to the URLs of various kinds of index pages on the site—adhere to a particular pattern, which can be characterized as (ignoring the protocol prefix):

(hostname) / (four-digit year) / (two-digit month) / (two-digit day) / (one or more “section paths”) / (the filename ending in .html)

This pattern is captured in this regular expression:

www\.nytimes\.com/\d{4}/\d{2}/\d{2}(/.*)+/.+\.html

To enter a regular expression for the auto-read feature, open CustomReader’s template editor (as discussed under Customizing the reader, above) and switch to the Auto-Read tab. Enter each regular expression on its own line, and click Save.

You can find a lot of information about regular expressions on the web. I find this site particular helpful. But if you need help constructing a regular expression, you’re welcome to email me (canisbos@gmail.com), and I’ll see what I can do.

How It Works

CustomReader itself doesn’t do the hard work of distilling web pages down to their essential contents. It uses the excellent Diffbot API for that. CustomReader just takes the simplified page content Diffbot provides and pours it into an HTML/CSS mold that you provide.

When you click the extension’s toolbar button (or type its keyboard shortcut, or use its context menu item), CustomReader sends a request to Diffbot to provide the simplified content for the current URL. When Diffbot returns the content, CustomReader replaces the current page’s <body> element with a new one constructed from the HTML template filled in with the simplified content, disables the page’s native stylesheets, and applies the template’s CSS stylesheet. When you cancel the reading view, CustomReader restores the page’s original HTML and stylesheets.

If you specify a URL pattern (regular expression) for autoreading, all of this happens automatically as soon as a matching page starts to load.

Notes

CustomReader’s default style specifies the font Iowan Old Style for the main body (the #story element). This is not one of the Mac’s default fonts, so you’ll probably see the backup font, Georgia, instead. However, I highly recommend installing Iowan Old Style if you can get your hands on it. If you own Apple’s iOS book reading app, iBooks, you can (legally, for your own private use) copy Iowan Old Style from its application bundle. Here’s how to do that:

  1. If you’ve never synced your iOS device (with iBooks on it) with your Mac, do that now, so that the iBooks app bundle gets copied to your Mac.
  2. Find your iTunes Music folder (usually at ~/Music/iTunes/iTunes Music) and, within it, the Mobile Applications folder. Inside this folder you should see the file “iBooks x.x.x.ipa”, where x.x.x represents a version number. I think iBooks started including Iowan Old Style in version 2.0, so if you haven’t updated yet, do so.
  3. Copy the .ipa file to another folder somewhere, such as the Desktop.
  4. Change the copy’s extension to “zip”. Now double-click it to extract its contents.
  5. Inside the extracted folder, you’ll find a subfolder named Payload. Inside that, you’ll see the actual app bundle, which is named iBooks. Right-click this file and select Show Package Contents. Now you’re inside the app bundle.
  6. Look for these four files:
    • IowanOldStyle-Bold.ttf
    • IowanOldStyle-BoldItalic.ttf
    • IowanOldStyle-Italic.ttf
    • IowanOldStyle-Roman.ttf
  7. Copy or move these files into your Fonts folder, which is at ~/Library/Fonts. While you’re at it, you might as well copy the other fonts from here, as iBooks has a few other very nice ones.

And that’s it. Now you can enjoy this beautiful font in CustomReader, or any other program on your Mac.

2012 Canisbos Computing
Creative Commons License

Notes