Chirpy - Chirpy! 0.3 API Documentation

Chirpy! 0.3 API Documentation

<<
Chirpy

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

Additionally, the default data manager and user interface classes have their own requirements. Before using them, please consult the data manager's requirements and the user interface's requirements.

SYNOPSIS

 use Chirpy;
 
 chirpy();

 chirpy($configuration_file, $data_manager_type);
 
 $chirpy = new Chirpy();
 $chirpy->run();

 $chirpy = new Chirpy($configuration_file, $data_manager_type);
 $chirpy->run();

DESCRIPTION

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.

USAGE

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.

 chirpy;

That's it! Now, if you wanted to specify your own configuration file, you would just pass it as the first parameter, like so:

 chirpy('/home/joe/chirpy.ini');

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:

 $chirpy->run();

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');

While the 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 undef as the first parameter:

 $chirpy = new Chirpy(undef, 'MyNewDataManager');

CONFIGURATION FILE

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:

 [data]
 mysql.password=mypassword

Now, let's go over the default configuration values.

General Section

The general section configures ... general settings!

base_path

The local path (on the file system) where locales, templates, etc. are stored. Do not include a trailing slash.

title

The title of your QDB.

description

A brief description of the purpose of your QDB.

locale

The code of the locale to use.

rating_limit_count

rating_limit_time

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.

quote_score_calculation_mode

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 quote_score_calculation_mode to 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

The 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

The ui section configures the frontend or user interface. It includes these parameters by default:

type: Similar to the type parameter under the data section, this one sets the name of the user interface module and will be translated to Chirpy::UI::Name.
date_time_format: The string that describes the format in which to display a date along with the time. This string is passed to the strftime method of the POSIX module.
date_format: Similar to the above, but for dates only.
time_format: Similar to the above, but for times only.
use_gmt: 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.
quotes_per_page: The maximum number of quotes to display per page.
recent_news_items: How many news items to display on the home page.
moderation_queue_public: Set this to 1 if 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.
tag_cloud_logarithmic: Set this to 1 if 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.

AUTHOR

Tim De Pauw <ceetee@users.sourceforge.net>

COPYRIGHT

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.

Chirpy!

Chirpy! 0.3 API Documentation

<<
Chirpy

NAME

REQUIREMENTS

SYNOPSIS

DESCRIPTION

USAGE

CONFIGURATION FILE

General Section

Data Section

UI Section

AUTHOR

SEE ALSO

COPYRIGHT

Chirpy! 0.3 API Documentation

<<Chirpy

<<
Chirpy