/ 
Posy-0.10
/ Posy::Core

NAME

Posy::Core - the core methods for the Posy generator

VERSION

This describes version 0.10 of Posy.

SYNOPSIS

require Posy;

Posy->import(@plugins);
Posy->run(%args);

DESCRIPTION

This is a simple website content management system / blog inspired by the design of blosxom. The filesystem is the database, there are flavour templates, and plugins. However, this system doesn't require one to write one's entry files in a particular format; one can choose from pure HTML, plain text, or blosxom format. And other formats can be dealt with if one writes a plugin to deal with them.

CLASS METHODS

run

Posy->run(%args);

run is the only methods you should need to use from outside this module; other methods are called internally by this one.

This method orchestrates all the work; it creates a new object, and applies all the actions.

Arguments include:

actions

The actions that should be performed by the Posy engine. If none are given, then the default sequence will be used.

entry_actions

The actions which should be performed on each entry. If none are given, then the default sequence will be used.

data_dir

The directory where the data is.

state_dir

The directory where the state-related data is (what used to be "plugins/state" in blosxom).

OBJECT METHODS

Documentation for developers and those wishing to write plugins.

new

Make a new object.

init

Do some initialization of the object after it's created. Set up defaults for things which haven't been defined.

do_actions

$self->do_actions();

Do all the actions in the actions list. (Called from "run").

Flow Action Methods

Methods implementing actions.

set_config

$self->set_config($flow_state);

Set $self->{config} from the config files. Takes into account the path, but no chunk information; useful for setting global parameters.

init_params

Parse the global parameters. Creates a CGI object in $self->{cgi} and checks whether we are in a CGI environment (dynamic) or not (static) and sets $self->{dynamic} and $self->{static} accordingly.

Note that "static" does not mean the same thing as with blosxom2; what actions are performed depend entirely on the $self->{actions} array; it won't be trying to generate all the files just because we aren't in CGI mode.

Sets $self->{url} if it isn't already set.

When this is not in dynamic mode, the parameters can be set by passing them through the $self->{params} hash (by setting params=>{...} when calling "new" or "run".

index_entries

Find the entries files, the "other" files, and the categories. This uses caching by default.

Expects $self->{path} and $self->{config} to be set.

Sets $self->{reindex} if reindexing has been done.

parse_path

Parse the PATH_INFO (or 'path' parameter) to get the parts of the path and figure out what the path-type is, and the flavour. If the path is undefined, uses DOCUMENT_URI or REDIRECT_URL.

The path-type can be one of: entry, top_entry (an entry which is in the top directory), file (a file which is not an input entry file), category, top (the root page), or chrono.

Sets $self->{path} hash.

Expects parameters to have been initialized (so that it can check $self->param('path') as well as PATH_INFO).

If it fails to parse the path, sets $self->{path}->{error} to true. This can be used by later actions.

stop_if_not_found

If there was an error parsing the path ($self->{path}->{error} is true) then flag the actions to stop.

Also sends a 404 error if we are in dynamic mode; this assumes that if it can't parse the path, it can't find the file.

This is done as a separate action method so that it makes it easier to change this behaviour.

select_by_path

$self->select_by_path(\%flow_state);

Select entries by looking at the path information. Assumes that no entries have been selected before. Sets $flow_state->{entries}. Assumes it hasn't already been set.

filter_by_date

$self->filter_by_date(\%flow_state);

Select entries by looking at the date-time information in $self->{path}. Assumes that $flow_state->{entries} has already been populated; updates it.

sort_entries

$self->select_entries(\%flow_state);

Sort the selected entries (that is, $flow_state->{entries}) Checks $self->{config}->{sort_type} to determine the sort order. The possible types are: time, time_reversed, name, name_reversed, path, path_reversed (default: time_reversed)

content_type

$self->content_type(\%flow_state);

Set the content_type content in $flow_state->{content_type}

head_template

$self->head_template(\%flow_state);

Set the head template in $flow_state->{head_template} This also sets the $self->{config} for head.

head_render

$self->head_render(\%flow_state);

Interpolate the head template into the head content; Set the head content in $flow_state->{head}

foot_template

$self->foot_template(\%flow_state);

Set the foot template in $flow_state->{foot_template} This also sets the $self->{config} for foot.

foot_render

$self->foot_render(\%flow_state);

Interpolate the foot template into the foot content; Set the foot content in $flow_state->{foot}

do_entry_actions

$self->do_entry_actions(\%flow_state);

Process the entry-action list. This method is passed flow_actions state hash, which it can test and alter.

render_page

$self->render_page(\%flow_state);

Put the page together by pasting together its parts in the flow_state hash and print it (either to a file, or to STDOUT). If printing to a file, don't print content_type

Entry Action Methods

Methods implementing per-entry actions.

count_or_stop

$self->count_or_stop(\%flow_state, \%current_entry, \%entry_state)

Increment the entry-count and stop the processing of this entry if it goes beyond the required number.

$self->header(\%flow_state, \%current_entry, \%entry_state)

Sets the entry date vars for this entry.

Set the header content in $flow_state->{header} and add the header to @{$flow_state->{page_body}} if it is different to the previous header.

read_entry

$self->read_entry(\%flow_state, \%current_entry, \%entry_state)

Reads in the current entry file. Sets $current_entry->{raw} with the contents.

parse_entry

$self->parse_entry(\%flow_state, \%current_entry, \%entry_state)

Parses $current_entry->{raw} into $current_entry->{title} and $current_entry->{body}

entry_template

$self->entry_template(\%flow_state, \%current_entry, \%entry_state)

Set the entry template in $entry_state->{entry_template} This also sets the $self->{config} for entry.

render_entry

$self->render_entry(\%flow_state, \%current_entry, \%entry_state)

Interpolate the current entry, setting $entry_state->{body}.

append_entry

$self->append_entry(\%flow_state, \%current_entry, \%entry_state)

Add $entry_state->{body} to @{$flow_state->{page_body}} (This is done as a separate step so that plugins can alter the entry before it's added to the page).

Helper Methods

Methods which can be called from within other methods.

param

my $value = $self->param($name);

Return or set global parameters.

This passes the arguments on to $self->{cgi}->param();

set_vars

my %vars = $self->set_vars(\%flow_state);
my %vars = $self->set_vars(\%flow_state, \%current_entry, \%entry_state);

Sets variable hashes to be used in interpolation of templates.

This can be called from a flow action or from an entry action, and will use the given state hashes accordingly.

This sets the variable hash as follows:

$self->{name} where it is a simple value (eg 'url') -> $name $self->{path}->{name} -> $path_name $self->param('name') -> $param_<name> $self->{config}->{name} -> $config_<name> $flow_state->{name} -> $flow_<name> $current_entry->{name} -> $entry_<name> $entry_state->{name} -> $es_<name>

get_template

my $template = $self->get_template($chunk);

Get the template file for this state, taking into account $self->{path}->{dir} $self->{path}->{type} $self->{path}->{flavour} and of course $chunk

Returns (a copy of) the found template. This is so that the following actions can alter the template as they see fit.

Possible chunks are "content_type", "head", "header", "entry", "foot". The "header" and "entry" chunks are used during entry processing.

Possible path types are "category", "chrono", "top", "entry" and "top_entry".

get_config

my %config = $self->get_config($chunk);

Get the config settings for this state, taking into account $self->{path}->{dir} $self->{path}->{type} and $chunk

Possible chunks are nothing, "content_type", "head", "header", "entry", "foot".

Possible path types are "category", "chrono", "top", "entry" and "top_entry".

The config files are called $path_type.$chunk.config $path_type.config $chunk.config or config

Returns a hash of cumulative config settings.

read_config_file

$self->read_config_file($filename);

Read the given config file, and return a hash of config settings from it. The $filename is the full name of the file to read.

The config file is made up of name:value pairs of data.

interpolate

$content = $self->interpolate($chunk, $template, \%vars);

Interpolate the contents of the vars hash with the template and return the result. (This is passed the chunk name just in case one wishes to do something different depending on what chunk type it is.)

debug

Print a debug message (for debugging) Checks $self->{'debug_level'}

Private Methods

Methods which may or may not be here in future.

whowasi

For debugging: say who called this

_find_file_and_ext

($fullname, $ext) = $self->_find_file_and_ext($path_and_filebase);

Returns the full path file and the extentsion of the given path-plus-basename-of-file; if no matching entry file exists under the data directory, the returned values are empty strings.

_wanted

$self->_wanted();

This is a method called from a wrapper 'wanted' function inside the call to File::Find::find inside the index_entries method. This does all the work in indexing the entries.

_init_caching

Initialize the caching stuff used by index_entries

_read_caches

Reads the cached information used by index_entries

_save_caches

Saved the information gathered by index_entries to caches.

extract_date

Given a unixtime (in seconds since whenever it was) will return an array containing the 4-digit year, the month (1-12) and the day of the month.

nice_date_time

Given a unixtime (in seconds since whenever it was) will return a hash containing the portions of the date-time:

sec

The second.

min

The minute.

hour

The hour (24-hour time).

year

The 4-digit year.

mnum

The number of the month (1-12).

da

The day of the month.

wday

The day of the week (number).

dw

The day of the week (name).

month

The month name.

_url

Figure out the full url.

_protocol

Figure out the protocol. (taken from CGI::Simple)

_script_name

_server_name

_server_port

_server_protocol

REQUIRES

File::Spec
File::stat

File::Find
Storable
CGI

Test::More

INSTALLATION

To install this module, run the following commands:

perl Build.PL
./Build
./Build test
./Build install

Or, if you're on a platform (like DOS or Windows) that doesn't like the "./" notation, you can do this:

perl Build.PL
perl Build
perl Build test
perl Build install

In order to install somewhere other than the default, such as in a directory under your home directory, like "/home/fred/perl" go

perl Build.PL --install_base /home/fred/perl

as the first step instead.

This will install the files underneath /home/fred/perl.

You will then need to make sure that you alter the PERL5LIB variable to find the modules, and the PATH variable to find the script.

Therefore you will need to change: your path, to include /home/fred/perl/script (where the script will be)

PATH=/home/fred/perl/script:${PATH}

the PERL5LIB variable to add /home/fred/perl/lib

PERL5LIB=/home/fred/perl/lib:${PERL5LIB}

SEE ALSO

perl(1).

BUGS

Please report any bugs or feature requests to the author.

AUTHOR

Kathryn Andersen (RUBYKAT)
perlkat AT katspace dot com
http://www.katspace.com

COPYRIGHT AND LICENCE

Copyright (c) 2004 by Kathryn Andersen

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.