view release on metacpan or  search on metacpan

lib/App/Followme/Module.pm  view on Meta::CPAN

App::Followme::Module - Base class for modules invoked from configuration

=head1 SYNOPSIS

    use Cwd;
    use App::Followme::Module;
    my $obj = App::Followme::Module->new();
    my $directory = getcwd();
    $obj->run($directory);

=head1 DESCRIPTION

This module serves as the basis of all the computations
performed by App::Followme, and thus is used as the base class for all its
modules. It contains a few methods used by the modules and is not meant to
be invoked itself.

=head1 METHODS

Packages loaded as modules get a consistent behavior by subclassing
App::Followme:Module. It is not invoked directly. It provides methods for i/o,
handling templates and prototypes.

A template is a file containing commands and variables for making a web page.
First, the template is compiled into a subroutine and then the subroutine is
called with a metadata object as an argument to fill in the variables and
produce a web page. A prototype is the most recently modified web page in a
directory. It is combined with the template so that the web page has the same
look as the other pages in the directory.

=over 4

=item $flag = $self->check_error($error, $folder);

Provides common error formatting and checking for modules. It generates a
warning message if $error is set. $folder is the name of the file or folder
that the operation that generated the error was invoked on. The return value
is Perl true  if $error was set.

=item $filename = $self->find_prototype($directory, $uplevel);

Return the name of the most recently modified web page in a directory. If
$uplevel is defined, search that many directory levels up from the directory
passed as the first argument.

=item $filename = $self->get_template_name($template_file);

Searches in the standard places for a template file and returns the full
filename if it is found. Throws an error if the template is not found.

=item %configuration = $self->read_configuration($filename, %configuration);

Update the configuraion parameters by reading the contents of a configuration
file.

=item $page = $self->reformat_file(@files);

Reformat a file using one or more prototypes. The first file is the
prototype, the second, the subprototype, and the last file is the file to
be updated.

=item $page = $self->render_file($template_file, $file);

Render a file as html using a template. The data subpackage is used to
retrieve the data from the file.

=item $file = $self->to_file($file);

A convenience method that converts a folder name to an index file name,
otherwise pass the file name unchanged.

=back

=head1 CONFIGURATION

The following fields in the configuration file are used in this class and every
class based on it:

=over 4

=item template_file

The name of the template file used by this module.

=item exclude_index

Do not include index file when searching for the file most recently changed
in a directory.

=item web_extension

The extension used by web files. The default value is 'html'.

=item configuration_file

The name of the file containing the configuration. The default value is
'followme.cfg'.

=item template_directory

The name of the directory containing the template files. The name is relative
to the top directory of the web site. The default value is '_templates'.

=item data_pkg

The name of the Perl module that generates data to be put into the template.
It should be a subclass of App::Followme::BaseData. The default value is
'App::Followme::WebData'.

=item template_pkg

The name of the Perl Module used to generate web pages from templates.
The default value is 'App::Followme::Template'.

=back

=head1 LICENSE

Copyright (C) Bernie Simon.