Note: I no longer use Chronicler myself and will not be updating the code any more. You may want to look at more advanced and flexible tools such as Movable Type and Blogger.

Chronicler Read Me (v1.2)

This file contains instructions for installation, usage and customisation of Chronicler. If you are already using the previous version of Chronicler, you may wish to jump straight down to the upgrade instructions or version history. Feel free to distribute Chronicler, but keep the files (chronicler.cgi, config.txt, readme.html and those in the templates directory) together. If you have suggestions, questions or improvements, please email me. Phil Gyford, 25th June 2001.

Introduction
Installing Chronicler
Using Chronicler
Customising Chronicler
Chronicler Announcement Mailing List
Upgrading From v1.1
Version History

Introduction

With Chronicler it's simple to create, update and maintain your own archive of web pages such as a personal diary or journal, or even a daily magazine. All entries, articles or stories are entered using a web-based form and existing entries can be modified or deleted online - no hassles with uploading pages and manually updating links to new material! All material is stored on your own site, so there's no need to entrust your carefully-crafted words to the safekeeping of a dot.com's servers. Using simple templates the layout of your pages is fully customisable and changes can be made to the entire site at the press of a button.

To use Chronicler you must be able to run Perl CGI scripts on your site (if you have a 'cgi-bin' directory you're probably all set), but no knowledge of programming is necessary. You may need to know how to change the permissions of files on your server in order to run the script. Basic knowledge of HTML is useful, especially if you want to customise your page layouts.

Chronicler allows you to create a new article or entry every day, with each stored at its own URL (eg http://www.gyford.com/phil/writing/2001/03/18/). Each entry is stored within its directory as an XML file (entry.xml) which is used to generate its HTML page based on a simple template. An alternative template can also be used to automatically create printable versions of the same entries (printable.html). Index pages will be generated listing links to all your entries using a third template and the front page of your site can contain the most recent entry, the most recent index or something else entirely.

Installing Chronicler

Installation is extremely easy, consisting of only five simple steps. As well as this Read Me file you should have a number of other files:
chronicler.cgi - The script that does all the work.
config.txt - A text file used to customise features of Chronicler.
templates - This is a directory containing three further files, template.html, printable.html and index.html. These are the templates upon which the different types of pages are based.

  1. First you need to make two changes to chronicler.cgi. Open the file in a text editor. Near the top of the file are two lines:
    my $root = "/home/httpd/html/";
    my $path = "phil/writing/";
    You need to change these values to reflect your own server. The first, $root, indicates where the top level of your website is to be found. The second, $path, is the path to where you want your front page to be on your site. It is currently set so that visitors to, say, http://www.gyford.com/phil/writing/ see the front page. If you want your writing to be at the top level of your site (eg, if I wanted my writing to be at http://www.gyford.com/) then change the $path value to "/".
    You may also need to change the very first line of chronicler.cgi, the one that reads:
    #!/usr/bin/perl
    This points to the location on your server where Perl is to be found. Chances are it will work as it is, although a common alternative is #!/usr/local/bin/perl.
    These are the only changes you will have to make to chronicler.cgi.
     
  2. You can now upload chronicler.cgi to the cgi-bin directory on your server. You should, however, change its name to increase security. If you leave the name as it is someone could guess you are using Chronicler and attempt to send commands to the script. Change the name to something no one else will be able to guess. For the purposes of these instructions, however, we'll still refer to it as chronicler.cgi. You may also wish to password protect the script using a .htaccess file.
    You may have to change the file permissions of chronicler.cgi to make it executable. Do this using your FTP application or via a telnet command line (chmod +x chronicler.cgi).
     
  3. Open config.txt. This file contains a number of tokens which you can change, as detailed in Customisation, below. Right now there is only one line that you must change:
    first_date=2001-01-31
    You should change this date to the date of your first entry (probably today!) in the format yyyy-mm-dd, and save the file.
     
  4. Now upload config.txt and the templates directory, with its contents, to the location where you want your front page to be. This might be the top level of your website or, in our example above, /phil/writing/. Depending on the set-up of your server you may need to alter the permissions of this directory to allow the script to write to it. You're now ready to go!

Using Chronicler

If you point your browser at the location of your chronicler.cgi (eg, http://www.gyford.com/cgi-bin/chronicler.cgi) you will see the admin interface. Remember that you should have changed the name of the script already! You can now Add, Modify or Delete entries, or Build the pages.

After Adding, Modifying or Deleting any entry you will have to Build the pages before the changes appear on your site.

Add Entry

The first page you should see is for Add Entry. All you have to do is enter the date (this defaults to the current date, but you can change it to whatever suits you), title of the entry for that day, the meta description and keywords, and the body of the entry. The description and keywords are not essential but help search engines direct relevant queries to your articles, so making them relevant to the article you're about to enter could generate extra traffic. You may prefer to write the body of your entries in your favourite text editor and paste them into the form - not only is a text editor more suited to typing but you can save what you're doing. You don't want to lose your nearly-finished article if your browser crashes!

Titles, description and keywords are limited to 255 characters. You do not have to use the titles on your pages, but they are used for the index pages - lists of all the articles available.

The body of the text can contain HTML and in fact it probably should! Whatever you enter here will appear the same in your rendered HTML pages, so if you wish to start new lines you will have to use <br> or <p> tags to indicate this. All other tags should also function as you'd expect them to.

Modify Entry

To make changes to an existing entry you need to know its date. Enter this and you will be presented with the title, description, keywords and body of the entry. Make your changes and hit the 'Submit Changes' button (don't forget to Build the pages to see your changes on the site!).

Delete Entry

Enter the date of the entry you wish to delete. You will then be shown the title of the piece so you can confirm this is the correct one to delete. Clicking the 'Delete' button will erase the entry permanently.

Building Pages

To see any changes or new additions you make you will have to build the pages. There are two options: Build All and Build New. From day to day, if you add new entries in chronological order, you can just use Build New - this rebuilds the most recent three entries and the front page (if it is set to contain the most recent entry). When you have a large number of entries this may be quicker than Build All which rebuilds every page - use this if you Modify or Delete an old entry, Add an entry for a date in the past, or make changes to any of the templates or config.txt.

Customising Chronicler

You can customise the appearance of your pages using both config.txt and the templates.

Config.txt

This file contains various preferences used by the Chronicler script:

first_date - You should set this to the earliest date for which you have an entry.

file_extension - If you want your pages to be marked as something other than .html (eg, .php3 or .asp) you can set this here. If you change this, be sure to also change the extension of each of the templates to the same.

front_page - This can be one of article, index or none. The first option means the front page of your site will contain the most recent article published. The second means the front page will be the most recent index of articles. The final option means chronicler.cgi will not touch your front page, so you can do what you like with it (perhaps including the latest_articles.txt file - see below).

max_latest_articles - When you build your articles a file called latest_articles.txt is generated in a directory called includes. This lists the most recent few articles you've written - kind of a mini index page. The value of max_latest_articles determines how many are listed in the file, assuming you've written that many of course.

latest_line - You can alter the format of the articles listed in latest_articles.txt using this value. It should contain either **date**, **title or both tokens. These will be replaced with the appropriate date or title for each article. You can include other html to format the listing, although it must all be on one unbroken line of text.

index_line - This is exactly the same as latest_line, above, except it controls the format of the listings on the index pages.

printable_link - Chronicler can automatically create printable versions of your articles, using the printable.html template (see the next section on templates). If you wish to take advantage of this feature, you will need to create links on your pages to the printable versions. Whatever you use for this value will appear as the link on each page to its printable version. If you leave the value blank the printable pages will not be created.

bookmark - The front page of your site may contain the most recent of your entries (you can choose whether it does or not with the front_page token above). If people wish to link to your article, however, they need a permanent URL where they can find it when the front page changes. Therefore the front page contains a link to the article's permanent URL. This 'bookmark' value contains the text that will make up the link. It can contain HTML, or leave it blank if you don't want it to appear.

next/prev/index_on/off - These values are used for the links to next/previous entries on each page and to link to the front index page. The 'off' next/prev values only appear on the very first and last pages, where there is no previous or next page to link to. The 'off' index value only appears on the front index page itself. These values can contain HTML so you could make them images.

page_date, index_date - These enable you to customise the format of the dates used on your pages. page_date replaces the token **date** used in template.html and printable.html, and is thus seen on all article pages. index_date is only used in the index listings of entries. The date format is specified using a series of letters to indicate the sequence and style of date elements:

For example, "W, ds N, Y." would appear something like this: "Sunday, 31st December, 2000."

admin colours - If you're writing a lot of entries you'll be seeing a lot of the Admin screens, so if the default blue theme isn't to your taste you can change the colour values here!

Templates

Unless you have an obsession with the minimal, you're bound to want to customise the look of your pages. The files in the templates folder are read by chronicler.cgi whenever it builds pages and changing these files can alter how all your pages apear. There are three files in the directory:

template.html - The template for all of the normal pages containing your articles.
printable.html - The template used for printable versions of your articles, but only if you have set a value for printable_link in config.txt.
index.html - The template used to generate the index pages, listing links to all your articles. The index pages each list the articles written for one calendar year. The front index page (in a directory called 'index', eg, /phil/writing/index/) lists the entries for the current or most recent year. Each previous years' index pages are stored in directories below this (eg, /phil/writing/index/2000/).
Each template is a standard HTML page containing a number of tokens to indicate the position of various dynamic elements. Each of these is surrounded by four asterisks (therefore you should not use "**" in your page or any of your entries). Each token can be used more than once, and none are strictly required.

**date** - In template.html and printable.html this will be replaced by the date of the article, in the format set by the page_date value in config.txt. In index.html it will be replaced by the index_date value.

**title** - This will be replaced by the title of the page's article.

**meta_description** and **meta_keywords** - These two tokens will be replaced with the Description or Keywords entered for the article and are designed to be used in the meta tags of the page (see the example template.html). Of course, you could also use them elsewhere on the page, perhaps using the Description as a subheading, for example.

**body** - This will, you guessed it, be replaced by the article itself, or, on index pages, the listing of articles.

**next** and **previous** - These will be replaced by links to the next/previous article, or next/previous index page, using the text or html specified in config.txt.

**index** - This will be replaced by a link to the front index page, using the text or html specified in config.txt. This only needs to be used in template.html.

**printable_link** - If you choose to create printable pages, and have set the printable_link value in config.txt, then this will be turned into a link to the printable version of the article. This only needs to be used in template.html.

**bookmark** - If you have set the front page of your site to feature the most recent article, this will be replaced by a link to the permanent URL for that entry, using the text or HTML specified in config.txt. This only needs to be used in template.html and does nothing on pages other than the front one.

If you wish to have all your pages as something other than straight HTML (thus giving you more options for customisation) you must change the file_extension value in config.txt and the file extension of each of the three templates.

Chronicler Announcement Mailing List

The Chronicler Annoucement mailing list is the best way to keep in touch with new versions and other important news. If you use Chronicler you definitely should subscribe. If you're merely interested, then feel free to join too. Only the moderator may post messages, and these will be rare. The list is hosted at Yahoo! Groups. Subscribe using this form:
 

Upgrading From v1.1

There are a number of improvements in v1.2, listed below in the Version History. To use v1.2 and take advantage of the improvements you will need to make a few simple changes to your set-up (you may find it useful to look at the new default files included with this version):
  1. There are five new tokens to be added to config.txt. These are listed below and you can copy and paste them straight into your copy of config.txt. 
    # What will be on the front page of your site: "article", "index" or "none".
front_page=article

# The number of links to include in the latest_articles.txt file (which you don't have to use).
max_latest_articles=3

# The HTML for each line on an index page or in latest_articles.txt.
# Each should include either **date** or **title** tokens, or both.
latest_line=**date** - **title**<br>
index_line=<tr><td>**date**</td><td>**title**</td></tr>

# The text used on each page to link to the printable version of the page.
# Leaving this value blank will mean no printable pages are built.
printable_link=
    The settings used here will not make any visible changes to your current site.
     
  2. Templates are now stored in a directory called templates. Create this in the same place as your config.txt file, and move your template.html (or template.php3 or whatever else it is called) into it. The default set-up now has two other templates in the directory too, printable.html and index.html. These templates are used for the printable pages and the index pages respectively. If you wish to use this functionality you must create these two files in the templates directory. To create a link on each of your article pages to the printable version you must set the printable_link token in config.txt to the text you want to appear as the link, and put **printable_link** in your template.html where you want the link to appear.
     
  3. Replace your old copy of chronicler.cgi (or whatever it is now called) with the new version (renaming it and changing file permissions if necessary).
     
  4. You should now do a 'Build All' to update all your pages with any changes made.
     
  5. Assuming all has gone to plan you will find, alongside your templates directory, an includes directory containing latest_articles.txt. You can include this on any page on your site if, for example, you're using PHP or shtml. You can set the number of links to recent articles appearing here by setting the max_latest_articles token in config.txt. Similarly, altering the latest_line token will alter the format of the html. latest_articles.txt will be rebuilt every time you 'Build All' or 'Build New'.
     
  6. You may wish to make a separate template for your index pages. This will be called index.html (depending on the file extension you're using) and should be placed in the templates directory. The listing of articles will appear where the **body** token is in this template and you can change the html used for the listing by changing the index_line token in config.txt. Note that if you use the index_line given in step 1 you should place opening and closing html table tags around **body** in your index template.
     
  7. The final change will be noticeable when you add or modify an entry; you can now set a description and keywords for each entry. You do not have to use them, but any text in these fields will replace **meta_description** and **meta_keywords** tokens in your template.html. See the example template for an example of how you might use these in the meta tags of an html page.
     

If you have any problems with the upgrade process, feel free to email me.

Version History

v1.2 (2001-06-25)
  • The front page of a site no longer has to be the latest entry. The most recent index page can appear there instead, or it can be left untouched by chronicler.cgi.
  • As well as the index pages, a small file is created listing a handful of the most recent articles. This is suitable for use as a server side include, perhaps in a sidebar, or elsewhere (eg, I list my most recent few articles at www.gyford.com using this method.
  • The format of the listings on index pages (and the list of recent articles just mentioned) is now customisable.
  • Printable versions of pages can be created and linked to automatically. These use a separate template and another template can be used to customise index pages.
  • Every entry can use its own description and keywords in its meta tags, entered when you enter the article.
  • A bug was fixed where links to the most recent index page, from other index pages, were broken.
  • A superfluous part of the JavaScript was removed.
v1.1 (2000-01-30)
  • Added index_on/index_off in config.txt.
  • Added date formatting: page_date, index_date in config.txt.
  • Changed file permissions for created files from 0777 to 0666.
  • Changed die() calls to use report_error() function for more useful feedback on errors.
  • Escaped <title> and <body> elements in XML files as CDATA so < and & characters do not need to be escaped individually.
v1.0 (2000-01-24)
  • Non-public pre-release.
Back to top