/ 
Posy-Plugin-Info-0.04
/ Posy::Plugin::Info

NAME

Posy::Plugin::Info - Posy plugin which gives supplementary entry information.

VERSION

This describes version 0.04 of Posy::Plugin::Info.

SYNOPSIS

    @plugins = qw(Posy::Core
	Posy::Plugin::YamlConfig
	...
	Posy::Plugin::Info
	...);

DESCRIPTION

This plugin enables the user to provide supplementary information about each entry in .info files (in Field:Value format), which are parsed and will set $info_* flavour variables which can be used in flavour templates. This plugin can also be used to sort entries by the .info information fields.

This enables one to create useful summaries of entry contents for use in category or chrono listings when one does not want to display the whole entry. While Posy::Plugin::ShortBody enables one to display just the first sentence in an entry, the usefulness of that can vary widely depending on what the first sentence is. With Posy::Plugin::Info one has much more control over the summary information.

Even more powerful, the sort-by-info ability enables one to sort entries on much more significant information than just the date or the filename. What the information actually is is entirely up to you.

This plugin requires Posy::Plugin::YamlConfig in order to set the type information in the info fields.

This plugin replaces the 'sort_entries' action, the 'set_vars' action, and provides an 'info' method for returning the info, if any, related to an entry.

Configuration

This expects configuration settings in the $self->{config} hash, which, in the default Posy setup, can be defined in the main "config" file in the data directory.

info_sort

If true, enable sorting on .info information. (default: false)

info_type_spec

Define the info-fields and their types.

    info_type_spec:
      Title:
        type: title
      Order:
        type: number
      Rating:
	type: limited
	values:
	  - G
	  - PG
	  - PG13
	  - R
      Author:
	type: string
      Summary:
	type: text

This gives a list of all the fields, and their types, with possible options. This is used for both sorting and for other plugins which depend on this one. The types are used to determine the kind of comparison or presentation of the particular field.

string

A short string, which needs normal string comparison. The default.

text

A multi-line string, which also uses normal string comparison, but may need to be presented differently (needing a textarea in a form, for example).

number

Compare as a number.

title

The field is a title; compare as if any leading "The" or "A" was not there.

limited

A short string which is only allowed a limited number of values. The "values" part of the definition gives those values. This is not actually enforced, but can be useful when desiring to present selectable options.

info_sort_spec

Define the default order by which the entries will be sorted.

info_sort_spec:
  order:
    - Author
    - Title
    - Order
  reverse_order:
    Title: 1

The 'order' part of the spec is the order the fields are to be sorted by. The 'reverse_order' part of the spec defines which fields should be sorted in reverse order; if the field name is there, with a value of 1/true/on, then that field is to be sorted in reverse.

If after sorting by the fields, there is still no difference, this will fall back to sorting by time, name or path, depending on what the value of the config variable 'sort_type' is.

info_sort_param

Defining this parameter enables sorting to be specified with a parameter in the URL. (default: '')

posy.cgi?info_sort=Author;info_sort=Title
info_sort_param_reverse

If info_sort_param is defined, this defines the parameter which specifies what fields are sorted in reverse order.

posy.cgi?info_sort_reverse=Date

OBJECT METHODS

Documentation for developers and those wishing to write plugins.

init

Do some initialization; make sure that default config values are set.

Flow Action Methods

Methods implementing actions. All such methods expect a reference to a flow-state hash, and generally will update either that hash or the object itself, or both in the course of their running.

sort_entries

$self->sort_entries($flow_state);

Sort the selected entries (that is, $flow_state->{entries}) If $self->{config}->{info_sort} is true, sorts by .info information given in $self->{config}->{info_sort_spec}. Otherwise calls the parent sort method.

Helper Methods

Methods which can be called from within other methods.

set_vars

my %vars = $self->set_vars($flow_state);

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

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

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 per the parent set_vars method, with the addition of setting the .info fields (if any) as:

$self->info($entry_id, field=>$name) -> $info_<name>

info

my %vars = $self->info($entry_id);

Gets the .info fields related to the given entry.

my $val = $self->info($entry_id, field=>$name);

Get the value of the given .info field for this entry.

read_info_file

my %info = $self->read_info_file($filename);

Parse a .info file.

Expects the fields to be in a Field:Value format, with overflow to the next line(s).

INSTALLATION

Installation needs will vary depending on the particular setup a person has.

Administrator, Automatic

If you are the administrator of the system, then the dead simple method of installing the modules is to use the CPAN or CPANPLUS system.

cpanp -i Posy::Plugin::Info

This will install this plugin in the usual places where modules get installed when one is using CPAN(PLUS).

Administrator, By Hand

If you are the administrator of the system, but don't wish to use the CPAN(PLUS) method, then this is for you. Take the *.tar.gz file and untar it in a suitable directory.

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

User With Shell Access

If you are a user on a system, and don't have root/administrator access, you need to install Posy somewhere other than the default place (since you don't have access to it). However, if you have shell access to the system, then you can install it in your home directory.

Say your home directory is "/home/fred", and you want to install the modules into a subdirectory called "perl".

Download the *.tar.gz file and untar it in a suitable directory.

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

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.

Therefore you will need to change the PERL5LIB variable to add /home/fred/perl/lib

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

REQUIRES

Posy
Posy::Core
Posy::Plugin::YamlConfig

Test::More

SEE ALSO

perl(1). Posy

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) 2005 by Kathryn Andersen

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