Chirpy! 0.3 API Documentation
Chirpy - Main coordination class
Chirpy! uses the UTF-8 character encoding, and because of that, Perl 5.8 is required. A lot of systems still have Perl 5.6 and, unfortunately, Chirpy! will not run there. This might change in future releases.
It also relies on a couple of Perl modules, most of which are part of standard Perl distributions. The base classes require these modules:
Carp Digest::MD5 Encode POSIX Storable
use Chirpy; chirpy(); chirpy($configuration_file, $data_manager_type); $chirpy = new Chirpy(); $chirpy->run(); $chirpy = new Chirpy($configuration_file, $data_manager_type); $chirpy->run();
This module is Chirpy!'s main coordination class and the only one that scripts that use it should access directly. Everything else is part of the inner workings of Chirpy!.
An instance of this module really represents an entire Chirpy! configuration, along with everything it uses at runtime. This means that you can have several instances of it simultaneously and exchange information between them.
There are two ways to use the class:
- Procedural Interface
The easiest way is to just run the
chirpy()procedure, which is exported by default. The code below will attempt to run Chirpy! with a configuration file located at either of the default paths src/chirpy.ini and chirpy.ini, relative to the current working directory.
That's it! Now, if you wanted to specify your own configuration file, you would just pass it as the first parameter, like so:
The path can also be relative, but make sure the working directory is correct.
- Object-Oriented Interface
As you may want to distinguish between different installations, you can have several instances of this module in the same script. Instantiating the module is a lot like invoking
chirpy(), except that it doesn't create and run the user interface instance yet.
$chirpy = new Chirpy(); $chirpy = new Chirpy('/home/joe/chirpy.ini');
If you wanted to create and run the configured user interface, you would just:
Simple as that.
In addition, you can add a second parameter to the constructor to override the data manager type specified in the configuration file, which can be useful for migration:
$chirpy_old = new Chirpy('/home/joe/chirpy.ini'); $chirpy_new = new Chirpy('/home/joe/chirpy.ini', 'MyNewDataManager');
chirpy()procedure also takes that parameter, I don't see any real use for it.
Note that if you want to use the default configuration file path, but with an alternate data manager, you just pass
undefas the first parameter:
$chirpy = new Chirpy(undef, 'MyNewDataManager');
A Chirpy! configuration file is a standard INI file, so it looks a little something like this:
[general] title=My Little QDB description=A place for my quotes locale=en-US ... [data] type=MySQL ...
Chirpy! adds a third level of parameter nesting to this format by separating the class and parameter name by a dot. For instance, the password for the MySQL data manager is stored like:
Now, let's go over the default configuration values.
general section configures ... general settings!
The local path (on the file system) where locales, templates, etc. are stored. Do not include a trailing slash.
The title of your QDB.
A brief description of the purpose of your QDB.
The code of the locale to use.
Limit the maximum number of votes per time frame using these two parameters. The former sets the maximum number, the latter sets the time period in seconds.
Since Chirpy! 0.3, quote scores, which are used to order the quotes for the Top and Bottom Quotes pages, are calculated using the following formula:
positive votes + 1 score = -------------------- negative votes + 1
This results in a fairly decent distribution. However, if you prefer the old way, based on a quote's rating, i.e.
rating = positive votes - negative votes
you can set
1. Note that the default way corresponds with a value of
0; this value may correspond with a different formula in future releases.
data section configures everything related to the data manager, or the backend, if you will.
This section only has one default parameter, namely
type. It contains the name of the data manager to use. This will be translated to
Chirpy::DataManager::Name, so that module will need to be installed.
Apart from that, there are parameters specific to the data manager of your choice. Please refer to its documentation for an explanation. If you use the default data manager, MySQL, you can find the parameters in its documentation.
ui section configures the frontend or user interface. It includes these parameters by default:
Similar to the
typeparameter under the
datasection, this one sets the name of the user interface module and will be translated to
The string that describes the format in which to display a date along with the time. This string is passed to the
strftimemethod of the POSIX module.
Similar to the above, but for dates only.
Similar to the above, but for times only.
Set this parameter to 0 if you wish to display times in local time instead of Greenwich Mean Time. For GMT, set it to 1.
The maximum number of quotes to display per page.
How many news items to display on the home page.
Set this to
1if you want to make the list of unmoderated quotes available to the public. To hide the list from everybody except moderators, set it to 0.
Set this to
1if you want to determine the tag cloud's font sizes using a logarithmic algorithm instead of a linear one. Most people will probably prefer this, as it gives better results if some of the tags are used extremely often.
Apart from that, there are parameters specific to the user interface of your choice. Please refer to its documentation for an explanation. If you use the default user interface, WebApp, you can find the parameters in its documentation.
Tim De Pauw <email@example.com>
Copyright 2005-2007 Tim De Pauw. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.