  ----------------------------------------------------------------------------
  BookQueue Movable Type Plugin
  http://jacob.hesch.cc/software/mt-plugins/BookQueue/
  $Id: README_bookqueue,v 1.1 2003/05/07 19:29:06 jlh Exp $
  Copyright (C) 2003 Jacob L Hesch
  ----------------------------------------------------------------------------


  About
  -----

  BookQueue is a Movable Type plugin which manages a queue  or  collection  of
  books. It allows you to store the queue in a database and later retrieve the
  items for display in your Movable Type weblog.

  For each book, BookQueue keeps track of the date it was entered, the date it
  was last modified, its status (already  read,  currently  reading,  plan  to
  read) and optionally associates  the  book  with  a  blog  entry  (for  book
  reviews, etc.). BookQueue stores each book's  ISBN  number  internally,  and
  uses the MTAmazon plugin and the Amazon API  directly  to  fetch  properties
  such as title, author and cover image from Amazon for display in the  weblog
  and in BookQueue's administrative interface, respectively.

  For rapid input of new books into the queue, BookQueue automatically decodes
  CueCat barcode scan output and  converts  Bookland  EAN  numbers  into  ISBN
  numbers. (See the ``Resources" section below for links to  more  information
  about the CueCat and ISBN.)


  Requirements
  ------------

    * Movable Type 2.6 or later
    * MTAmazon plugin (tested with version 2.22)

  MTAmazon is not strictly required; BookQueue will work without it, but would
  be quite boring.


  Installation
  ------------

  MT-DIR refers to your Movable Type directory.

    1. Unzip the BookQueue-1.X.zip archive.
    2. Move or upload bookqueue.pl into MT-DIR/plugins/.
    3. Move or upload mt-bookqueue.cgi into MT-DIR/.
    4. Move or upload BookQueue.pm into MT-DIR/extlib/MTPlugins/.

  If you  previously  installed  MTAmazon,  the  MT-DIR/extlib/MTPlugins/  and
  MT-DIR/plugins/  directories  should  already  exist.  Otherwise,  you  will
  probably have to create them.

  If you are using FTP to transfer files, make  sure  you  transfer  in  ASCII
  mode. Make sure mt-bookqueue.cgi has permissions set to 755.


  Usage
  -----

  There are two ways to interact with BookQueue.  The  first  is  through  its
  administrative interface which allows you to manage your queue of books. The
  second is from within a Movable Type template in which you  use  BookQueue's
  template tags to tell MT how to include the book information in your  blog's
  pages.

  To get started, point your browser to mt-bookqueue.cgi in  order  to  access
  BookQueue's administrative interface. For example, if  you  normally  access
  Movable Type via http://yourblog.com/mt.cgi,  the  administrative  interface
  URL would be http://yourblog.com/mt-bookqueue.cgi. You will have to  log  in
  as usual if you haven't already done so. If you have multiple blogs,  select
  the blog you want the books to be associated with at the top and  click  the
  ``change" button. Enter a book's ISBN number in the text box and hit  enter.
  When the page reloads, you should see a new  row  appear  with  your  book's
  thumbnail image at the left.

  Hint: When you are adding several new books to the queue, you can  speed  up
        the process by having BookQueue show only one entry at a time  (select
        ``1" in the drop-down menu at the bottom of the page).  This  minimize
        the time it takes to load the resulting page since the  properties  of
        only one book must be fetched from Amazon (or loaded  from  MTAmazon's
        cache).

  You can now modify properties of the book entry. If you  entered  the  wrong
  ISBN, you can change the number in the ISBN text box. You can set the status
  from the default of ``unread" to  ``reading"  or  ``read"  by  clicking  the
  appropriate radio button. To associate the  book  with  a  regular  MT  blog
  entry, type the entry's id in the ``associate entry id" field (you can leave
  out the leading zeros). You will later be able to link to that entry using a
  template tag (see examples below). The ``last  modified  on"  field  is  set
  automatically when you enter or update a book. You can specify your own last
  modified date by changing the text field and checking the  ``override"  box.
  This allows you to arbitrarily control the order by  which  your  books  are
  sorted in the template, or to keep track of  when  you  finished  reading  a
  book, for example. Check the ``delete" box to remove a book entry.

  After modifying the desired properties of a book entry, click the  ``update"
  button at the right to save the changes. Only one book entry may be  updated
  at a time.

  Whenever you add or modify a book entry, a link appears at the  top  of  the
  mt-bookqueue.cgi page which gives you the opportunity to rebuild your  site.
  This only makes sense after you have added BookQueue  tags  to  a  template.
  Read on...

  Once you have entered a few books into the queue and modified them  to  your
  liking, you can add tags to a template and rebuild to see the changes.

  See below for some examples of how to use BookQueue tags.

  For a complete reference of BookQueue template tags see:
  http://jacob.hesch.cc/software/mt-plugins/BookQueue/tagref.html


  Examples
  --------

  The following template example displays small images of the 10 most recently
  entered books marked as ``reading":

  <MTBookQueueEntries status="reading" lastn="10">
  <MTAmazon method="Asin" search="[MTBookQueueEntryISBN]">
  <img src="<MTAmazonSmallImage>" border="0">
  </MTAmazon>
  </MTBookQueueEntries>

  The next example displays, for each of the 10 most recently  modified  books
  sorted in ascending order by modified date, a  small  image  and  the  title
  linked to the corresponding amazon.com page along with the  author,  status,
  date entered, date last modified, and a link to a review in a  regular  blog
  entry (but only if a corresponding blog entry_id was entered for the book):

  <MTBookQueueEntries lastn="10" sort_order="ascend" sort_by="modified_on">
  <p>
  <MTAmazon method="Asin" search="[MTBookQueueEntryISBN]">
  <a href="<MTAmazonLink>"><img src="<MTAmazonSmallImage>" border="0"><br />
  <MTAmazonTitle></a> by <MTAmazonAuthor><br />
  status: <MTBookQueueEntryStatus><br />
  entered on <MTBookQueueEntryDate format="%e %B %Y at %H:%M"><br />
  updated on <MTBookQueueEntryModDate format="%e %B %Y at %H:%M">
  <MTBookQueueEntryIfBlogEntry><br />
  <a href="<MTBookQueueEntryBlogEntryLink>">My Review of <MTAmazonTitle></a>
  </MTBookQueueEntryIfBlogEntry>
  </MTAmazon>
  </p>
  </MTBookQueueEntries>

  Again, a complete tag reference for BookQueue is available here:
  http://jacob.hesch.cc/software/mt-plugins/BookQueue/tagref.html

  Follow the MTAmazon link below for more details on using MTAmazon.


  License
  -------

  BookQueue is released under the GPL.


  Bug Reports & Suggestions
  -------------------------

  Please send them to bookqueue@bitgig.com.


  Bugs
  ----

  Does not properly handle non-ASCII output from  the  Amazon  API.  This  can
  likely be solved with Text::Iconv which may be added in a future version.

  To Do
  -----

  Add features. Perhaps the ability  to  sort  alphabetically  by  author  and
  title? Suggestions welcomed!

  Work is underway for a plugin similar to BookQueue which handles other types
  of media such as CDs and DVDs. Stay tuned.


  Notes
  -----

  Amazon links displayed within the BookQueue administrative interface use  my
  Amazon associate id by default in order to support  plugin  development  (in
  the unlikely event that someone should actually make a purchase through  the
  interface :-). Amazon links  generated  from  BookQueue  template  tags  for
  display  in  your  blog  will  use  the  associate  id  specified  in   your
  ``.mtamazon.config" file.


  Resources
  ---------

  BookQueue:
  http://jacob.hesch.cc/software/mt-plugins/BookQueue/

  Movable Type:
  http://www.movabletype.org/

  MTAmazon:
  http://mtamazon.sourceforge.net/

  Other MT plugins:
  http://mt-plugins.org/

  CueCat:
  http://www.beau.lib.la.us/~jmorris/linux/cuecat/

  ISBN:
  http://isbntools.com/

