Documentation

Here you can find out detailed information on every aspect of Now Reading’s installation, upgrading and general usage. Whilst there is a large amount of detail, I’d rather cover everything than have confused or frustrated users. Who knows, you might learn something new about Now Reading in the process.

If you’ve got anything to add to the documentation, or have a query that the documentation doesn’t resolve, please join the plugin-discuss mailing list or post a comment here. Thanks!

Installation and basic usage

Installation

After downloading the zip file, extract the files and upload them to your WordPress plugins directory (wp-content/plugins/).
- Make sure that this is the only copy of Now Reading you have uploaded; there should just be one now-reading folder in the plugins directory, and not a copy of now-reading.php. If you still have such a file lying around from an old version, be sure to delete it before continuing.
In your WordPress administration panel, go to the Plugins page and activate the Now Reading plugin.
- This will take care of all the installation; you don’t have to run any sort of manual install process.
Now, you need to add the Now Reading information to your site. There are two ways to do this.
- The first—and easiest—method is to use the Now Reading widget.
  1. First of all, you’ll want to make sure you’ve got the Widgets plugin installed and activated. Head on over to this page to download the plugin and find out more.
  2. Make sure your theme is compatible with Widgets.
  3. Head on over to the Presentation → Sidebar Widgets menu, and drag the Now Reading Widget from the left pane (the pool of available widgets) to the right pane (your sidebar).
  4. Voila! All done.
- The second method requires the editing of template files, and is the method of choice for those who don’t want to or cannot install the Widgets plugin for whatever reason.
  1. Open up your theme’s sidebar.php file.
  2. Find a convenient place in the markup where you’d like the books to be displayed, and add the following code:
```
< ?php nr_display() ?>
```
    (Changing < ? to <? on the first line)
    
    Depending on your theme, you might need to add more markup surrounding the call to nr_display()—<li>s, <div>s etc.
  3. Upload your sidebar file, and that’s it.
  4. Note that with this method you lose a lot of the ease-of-use that comes with using the Widget; consider using that if you can.
If you’d like to modify the Now Reading options, header over to the Options → Now Reading tab. For most people, however, the default options will suffice.
- If you want to use nicer looking Library URLs, be sure you have mod_rewrite installed on your server (you probably do) and also have a custom WordPress permalink structure set up in the Options → Permalinks section of your admin panel.

Upgrading

You can upgrade Now Reading simply by uploading the new files; Now Reading will automatically apply any database/options changes if it needs to.
It’s also worth taking the time to look at the templates included in the distribution, to make sure your custom templates—if you use them—are up to date. Often new template functions are added which you might miss out on, or changes are made which might do strange things if your templates are highly customised.

Basic usage

First, you’ll probably want to add a book.

Head on over to the Write → Now Reading page in your admin panel to begin.
Now Reading offers two methods of searching; by ISBN and by a simple title/author keyword search.
- It’s usually much easier to use the ISBN search, since it’ll find the exact edition of the book that you’re reading.
- However, sometimes the exact edition might not be available on Amazon—particularly if it’s an international edition—and as a result your ISBN search will return nothing. In cases like this, you’ll need to use the keyword search to find a close match to your book.
Hit the Search button, and wait for your results to be fetched from Amazon.
Click the Use This Result button that corresponds to the book you want.
If you don’t find what you want, you can either add a book manually—entering details by hand—or try searching again.

Once you have a few books added, you’ll probably want some way of managing them.

Head on over to the Manage → Now Reading page in your admin panel to begin.
Here you have a nice table of all the books you’ve added to your database. You also have the ability to modify certain aspects of the data that is stored.
1. The first thing you’ll probably want to change is some of your books’ statuses. The status simply tells Now Reading what stage of the reading process the book is currently at.
  - The available statuses are: unread, for books you’re planning to read; reading, for books you’re currently reading; and read, for books you’ve finished.
2. Notice that when you change a book from its default status of unread to reading, the book’s started field is given a value.
  - This also happens to the finished field when you eventually change the book’s status from reading to read.
3. From the manage tab, you can also click a book’s Edit details/write review link to edit the book’s details or add a rating and review for the book.
  - This interface is also available from the individual books’ permalink pages, which are covered later.
  - Editing details is particularly useful when Amazon has added something you consider superfluous—such as the publisher or edition—to the title, as often happens.
  - Remember: opening new links, such as the edit/review page, will lose the changes you’ve made on the manage page! Open in a new tab/window if you don’t want to lose the changes.
Once you’ve made the changes you’d like, click the Update » button at the bottom of the page to save them.

Troubleshooting

My library pages look all broken!

Fret not, dear—this has a simple fix. Follow the instructions for creating theme-specific templates below, then edit your new template files; you’ll want to have the markup similar to your theme’s normal template files: the usual culprit is the following section of the default templates:

<div class="content">

    <div id="content" class="narrowcolumn primary now-reading">

    <div class="post">

Everything should appear clearer if you look at your theme’s template files. This problem arises because every theme is different, naturally—I just can’t account for every eventuality, so I ship a default set of templates that work with Kubrick and most of its derivatives, which is okay for most people. Once you make the changes, you should pester your theme’s author to include the Now Reading templates in the download, so other people don’t have the same problem.

Occasionally this is also necessary for your sidebar, too; if your sidebar looks all out-of-whack, just follow the steps above, but edit now-reading/templates/sidebar.php and get it to match your theme’s sidebar entries.

Advanced usage

There are a few more advanced things you can do with Now Reading beyond just the adding and managing of your books.

Templates

Now Reading controls all of its display through the use of templates. The templates are pure PHP, although you don’t need to know PHP to modify them.

All the templates are stored in the plugins/now-reading/templates directory. Here’s a quick run-down of what each file handles:

sidebar.php: sidebar.php is displayed when nr_display() is called, which is usually in the sidebar of your site.
library.php: library.php handles the display of the Library page, which displays an archive of all your books. In most instances, the templating code will be similar or identical to sidebar.php, with the only change being the added parameter of num=-1 which tells get_books to fetch all of the books for a particular status.
single.php: single.php handles the display of book permalinks, which are single pages that display more information about a single book. You can afford to be much more verbose here, since space is much less of a consideration than in the sidebar or in the Library.
search.php: search.php displays search results.
tag.php: tag.php is very similar to search.php, but displays books that are tagged with a given keyword.

All of the database fields in the Now Reading table have a corresponding template function that can be used to display that field for the current book, named book_foo() where foo is the name of the field. Examples of this are book_title(), which fetches the title of the book, and book_rating() which fetches the book’s rating.

You should be able to get to grips with the templates by viewing the default ones distributed with Now Reading. Nevertheless, here’s a quick run-down of the first section of sidebar.php to help you out:

First we check if there are any unread books:

if( have_books('status=unread') ) :

If there are, we loop through each of the books so we can display them:

    while( have_books('status=unread') ) : the_book();

Then we display the book with a link to the book’s permalink page and its title and author:

        <li><a href="< ?php book_permalink() ?>">< ?php book_title() ?></a> by < ?php book_author() ?></li>

This will display for each of our books.

Then we end the loop…

    endwhile;

…and display a message that will appear if there aren’t any unread books:

    < ?php else : ?>

        <p>None</p>

    < ?php endif; ?>

I hope that’s not too unintuitive; I’ve tried to make it as simple as possible. It’s also similar to WordPress’s theme setup, so people who are comfortable with editing WordPress themes should be right at home.

Theme-by-theme templates

Now Reading allows you to have custom template files for each theme on your site—useful if you need a different class/id on the main <div>, for example.

To use these custom themes:

Create a now-reading directory in your theme’s directory.
Copy the default template files to it—either all of them, or just the ones you want to modify.
Modify them.

Now Reading puts a priority on custom template files, and loads them before the default ones; if you want to revert back to the default, just delete your custom ones.

CSS

You can also style the various elements of Now Reading’s output by modifying your theme’s CSS file. By default, Now Reading applies a class of now-reading to the main content <div>; should you require more specific selection, you can simply edit your templates and apply your own classes and ids.

API

The have_posts() template function is really just a hidden way of calling the bread-and-butter of Now Reading: the get_books() function. This function takes a query string as a parameter, parses it, and returns the books that match that query string’s restrictions.

Valid elements of the query string are:

id: If you specify an ID, all other elements of the string become moot, as it is presumed that you just want to return a single book with the corresponding b_id.
num: The num parameter limits the amount of results returned. For instance, in the sidebar it’s probably wise to limit the amount of results displayed to five or so; in the library page, however, one should pass num=-1 in the query in order to not limit the amount of results returned at all. Defaults to 5.
status: Fetches books whose status matches this parameter. Valid values are unread, reading, or read. Defaults to reading.
orderby: Specifies the field to order the results by. Can be one of: added, started, finished, title, author, status or asin. Defaults to added.
order: Specifies whether to order the results in ascending (asc) or descending (desc) order. Defaults to asc.
search: Specifies a search string; all books will be returns whose author, title or meta values substring match this query.

So, a couple of example query strings.

This one fetches all books that are currently being read, and orders them by the time they were started in ascending order:

status=reading&orderby=started&order=asc&num=-1

This one fetches 5 finished books, ordered by the time they were finished in descending order:

status=read&orderby=finished&order=desc&num=5

This fetches the information for the book whose ID is 5:

id=5

Plugins for a plugin

Since Now Reading is quite a large project, there are points in the code in which—like the WordPress core—I’ve inserted hooks and filters, so that other plugins can extend and modify Now Reading’s behaviour.

Every piece of book metadata has a filter, the name of which is the same as the data’s corresponding template tag. So, to filter book reviews, use the following code:

add_filter('book_review', 'callback');

Where callback is the name of a function to filter the review text. For more on actions and filters, see this article on the WordPress codex.

By default, Now Reading applies a few filters to the metadata, such as running review text through wpautop and the review, title and author fields through wptexturize. You can check the default filters in now-reading/default-filters.php, and naturally remove them either from that file or by calling remove_filter from another plugin.

Roblog