tReadingList Version 0.03 Beta README
Copyright 2001 Stephen G. Walizer aka Technomancer all rights reserved.
License

This software is licensed under the GNU GPL. See the included file GPL for license details.

Bug Reports

Send bug reports or questions to sgw@node777.net

About

tReadingList is a set of PHP4 scripts designed to provide a list of books read, with commentary, for websites. The system uses HTML based templates to specify formatting of the reading list pages, providing complete control of page appearance to the webmaster. The system's backend is provided by a MySQL database, and support is included for generation of both a list of recent books read and a list of older books. Reading list HTML pages are only regenerated when changes are made to books, so end users suffer no delays caused by database access or parsing of scripting code.

The most current version of tReadingList is available at http://node777.net/treadinglist.php.

Requirements

tReadingList requires a PHP version >= 4.03 and MySQL.

Installation

Installation of tReadingList consists of the following steps:

  1. Move the files contained in the tReadingList package to a directory that allows execution of PHP scripts. It is recommended that this directory be secured as anyone with access to this directory can change your reading list.
  2. Check permissions on your files and make sure PHP has permission to write to the following:
    • trl_config.inc
    • The web page that will display your reading list
    • The web page that will display your old reading list
    • The directory that will contain your category icons, if you choose to use them
  3. Load index.html in the treadinglist directory in your favorite web browser and select Edit Configuration from the menu. Detailed information on the configuration options can be found in the Configuration section of this document.
  4. Create the template files for generation of your reading list and old reading list HTML pages. Example template files are included as readinglist.tmpl and oldreadinglist.tmpl and the more information about the contents of template files is included in the Template Files section of this document.
  5. Select Build DB Tables from the tReadingList menu. This page executes a set of MySql commands that build the table to hold your books.
  6. Select Add Subject from the tReadingList menu and add any subjects you wish to use.
  7. Select Add Book from the tReadingList menu and start adding books.
Configuration

tReadingList is configured through an html-based configuration tool accessed from the Edit Configuration link in the tReadingList menu. The editor supports the following configuration options:

MySql Settings

Database Host
The host variable contains the host for the MySql server to connect to. This is usually localhost if the database server resides on the same machine as the web server.
Database Login
The user name to connect to use when connectiong to the MySql server.
Database Password
The password to use when connecting to the MySql server.
Database Password Verification
Enter the same value as Database Password. This field protects against typos when entering a password.
Database Name
The name of the database to use when connecting to the MySql server.
Reading List Table Name
The table name in the MySql database where reading list data will be stored.
Subject Table Name
The table name in the MySql database where subjects will be stored.

Template/Output Files

Reading List Template File
The location and name of the template file used to generate the reading list display page pointed to in $listfile. For more information on template files see the Template Files section of this document.
Reading List Output File
The location and name of the HTML file to be generated containing the reading list. Be sure the webserver has permission to write to this file.
Old Reading List Template File
The location and name of the template file used to generate the old reading list display page pointed to in $oldlistfile. For more information on template files see the Template Files section of this document.
Old Reading List Output File
The location and name of the HTML file to be generated containing old books. Be sure the webserver has permission to write to this file.

Subjects Configuration

Full Path to Subject Icons Directory
The full path relative to the file system root of the directory to store subject icons.
Relative Server Path to Subject Icons
The path relative to the web server root of the directory for subject icons. This path is used in the img tag for subject icons.

Reading List Configuration

Maximum Reading List Items
The maximum number of books to be displayed on the main reading list HTML page. Books over this number will be automatically moved to the old reading list HTML page when a new book is added. If this value is set to 0 books will never be marked old based on the number of books.
Maximum Reading List Age
The maximum age in days for books on the main reading list HTML page. Books older than this will be moved to the old reading list HTML page when a new book is added. If this value is set to 0 or a negative number books will not be moved to the old reading list page based on age.
Maximum Book Rating
This is the maximum rating a book can be given. Rating values will be between 1 and Maximum Book Rating.
Path to Rating Image
This is the path, relative to the web server root, of the rating image. This path should include the file name of the image, for example /images/star.gif. The image will be repeated once for each rating 'point' when creating the data for the <ratingimage> tag.
Escape Special Characters
This field controls the escaping of special characters in books. Most installations of PHP3/4 automatically escape special characters, so by default Escape Special Characters is not checked. If you have problems adding book entries containing apostrophes, check this field.
Data Import/Export

tReadingList allows you to export your data for import into another tReadingList installation. To export your data make sure PHP has write permissions for the directory tReadingList is installed in. Once this is done simply click the Export DB Table Data link in the tReadingList menu. This will generate a script called trl_import.php which contains your database data and code to insert it into an existing tReadingList installation.

To import your data into a new or existing tReadingList installation simply copy the trl_import.php file into the tReadingList install directory and click the Import DB Table Data link in the tReadingList menu. (If you are importing data into a new installation, be sure you have built your database tables using the Build DB Tables link in the tReadingList menu before trying to import.)

Usage

tReadingList is very easy to use. Simply load index.html in the treadinglist directory in a web browser and select the desired function. The main web page contains options to add books, edit existing books, mark books deleted, undelete deleted books, and purge deleted books. The only option that is not really self explanatory is purging deleted books. Deleted books are simply marked as deleted and left in the database, allowing them to be undeleted later. Selecting purge permanently removes all deleted books from the database.

Generation of reading list and old reading list HTML files are performed automatically, as are moving books from new to old reading lists once the reading list page contains more than max_list_items set in trl_config.inc. For more information on trl_config.inc and on configuring tReadingList, see the Installation section of this document.

A shortcut function for creating urls in reading list items is included. The function to do this has two formats, one with a target and one without:

url(url,name,target);
url(url,name);

When using these functions they must be entered exactly as above. Do not place spaces between the arguments.

To give a concrete example:

This is a link to url(http://slashdot.org,Slashdot,_blank);, a linux news site.

would be converted to

This is a link to Slashdot, a linux news site.

when the reading list page is created.

In addition quotes can be used to include commas in url(); parameters. This is particularly useful when linking to sites like Wired, whose article urls include commas.

For example:

This is a link to a story on Wired: url("http://www.wired.com/news/politics/0,1283,45879,00.html",Story,_blank);

would be converted to

This is a link to a story on Wired: Story

when the reading list page is created.

Template Files

Template files provide complete control of reading list generation. A tReadingList template is simply an HTML file which includes some custom tags. These custom tags are as follows:

<listloop> </listloop>
The listloop tag specifies that all HTML within the tags should be repeated once for each book present. The listloop tag is removed completely from the generated HTML file.
<day>
The day tag is replaced by the 2 digit day of the month the book was finished. Values will be between 01 and 31.
<month>
The month tag is replaced by the 2 digit month of the year the book was finished. Values will be between 01 and 12.
<year>
The year tag is replaced by the 4 digit year the book was finished.
<title>
The title tag will be replace by the title entered when the book was created.
<author>
The author tag will be replace by the author entered when the book was created.
<subject>
The subject tag will be replace by the text name of the subject the book belongs to. If the book has no subject, the subject tag will simply be removed from the output file.
<subjecticon>
The subject icon tag will be replace by an img tag containing the icon of the subject the book belongs to. If the book has no subject or a subject without an icon, the subject icon tag will simply be removed from the output file.
<rating>
The rating tag will be replaced with the numerical rating entered when the book was added.
<ratingimage>
The ratingimage tag will be replaced with a repeating sequence of the image specified in the Path to Rating Image configuration option. For example, on a rating of five the image would be repeated five times.
<comment>
The comment tag will be replaced by the comment entered when the book was created.

The tReadingList package includes an example template file as readinglist.tmpl.