Yggdrasil - Generates a website from a directory tree of content and templates


NAME

Yggdrasil - Generates a website from a directory tree of content and templates


SYNOPSIS


DESCRIPTION

Configuration Variables

input_dir
Path to source directory.
    input_dir => '/home/me/site/source'
output_dir
Path to output directory.
    output_dir => '/home/me/www'
data_dir
Directory used to store title and update time caches.
    data_dir => 'data'
dir_mode
Directory create mode used by mkpath().
    dir_mode => 0755
include
Files matching one or more of the regular expressions in this array are passed to Text::Template. Files that do not match any of the regular expressions are copied to the target directory without processing. Should only match HTML files.
    include => [qw(\.html$ \.shtml$)]
exclude
Files or directories matching one or more of the regular expressions in this array are not processed or copied. These regular expressions are applied before the regular expressions in the include array.
    exclude => [qw(^_ \.tmpl$ ~$)]
skip
Directories matching one or more of the regular expressions in this array are not included in the @navigation array.
    skip => [qw(^img ^index$)]
base_url
Passed to templates.
    base_url => 'http://www.mysite.com'
base_template
Filename of base template. All parent directories of the current directory are searched.
    base_template => 'base.tmpl'
template_extension
File extension of template files.
    template_extension => '.tmpl'
template_override
A hashref containing full paths to override templates. If used there must be at least a ‘default’ override. Other overrides are matched against the current file name. E.g. an override template named ‘beta’ will be applied to all files matching /beta/.
    template_override => {beta => '/home/me/site/template.tmpl'}
timestamp_format
Format of the timestamp passed to the template.
    timestamp_format => '%a %b %e %Y (%T)',
html_indices
These filenames are removed from URL’s in the breadcrumb trail. Should match your webserver configuration.
    html_indices => [qw(index.html index.shtml)]
html_only
Set to 1 to give all HTML files (the files in include) the extension .html (this is useful when creating site versions for offline use or for webservers that can’t handle SSI).
    html_only => 0
front_page_navigation
Set to 1 to create a navigation array for the top level of the site (useful when creating site versions for offline use).
    front_page_navigation => 0
include_index
Set to 1 to include ‘index.html’ in navigation and breadcrumb trail links (useful when creating site versions for offline use).
    include_index => 0
siblings_include_index
Set to 1 to include index files in the siblings array.
    siblings_include_index => 0
home_label
Name given to the root page in the breadcrumb trail.
    home_label => 'Home'
title_tag
The tag in the source HTML document used as the document title.
    title_tag => 'h1'
default_title
Title given to files not found in the title cache.
    default_title => 'No Title'
subpages
Set to 1 to enable the numbered subpages feature (see User Guide).
    subpages => 1
pagination
Page title added to the breadcrumb trail for numbered subpages.
    pagination => 'Page '
ftp_host
URL or IP address of FTP server.
    ftp_host => 'ftp.mysite.com'
ftp_username
FTP server username.
    ftp_username => 'me'
ftp_password
FTP server password.
    ftp_password => 'secret'
ftp_path
Base path to use for remote files.
    ftp_path => '/www'
log_file_header
The first line(s) of the log file.
    log_file_header => "# Yggdrasil log file\n"
log_file_footer
The last line(s) of the log file.
    log_file_footer => '# end of log file'
log_file_format
Template for log file lines. The following variables are available: $fullname, $dirname, $filename.
    log_file_format => '{$fullname}'
release_file
Name of the file containing the last site release time. Stored in current data directory.
    release_file => '.release'
sp_command_line
Set this to the complete commandline for nsgmls if you wish to validate output files while processing. {$filename} is replaced with the current filename. You need to have the SP SGML system (http://www.jclark.com/sp/) installed in order to use this feature.
    sp_command_line => '/usr/bin/nsgmls {$filename}',
forcecache
Set to 1 to force rebuild of the document title cache.
    forcecache => 0
help
Set to 1 to display help message.
    help => 0
log_file
Name of log file.
    log_file => 'mysite.log'
update
Set to 1 to only process files added or changed since last release.
    update => 0
upload
Upload processed files via FTP.
    upload => 0
release
    release => 0
validate
    validate => 0
verbose
    verbose => 1

Public methods

go()
This method calls find() from File::Find. Depending on the configuration variables and commandline options it performs the following tasks:

Before calling find(): Open log file for writing, flush output directory, initialize progress bar.

After calling find(): Close log file, delete files from output directory, upload files via FTP, update release file.

new()
Creates a new Yggdrasil object and initializes it with values from the %Configuration hash and the configuration file if applicable.

See also: _init()

stats()
Returns a string with site processing stats.

Private methods

_pre_process(@files)
Determines which files get sent to the _process() method. Creates or updates the following arrays:

@siblings: A list of all files in the current directory, except subdirectories and HTML index files (set the configuration variable siblings_include_index to 1 to include indexes).

@trail: The path to the current directory. The title of the root page is determined by the home_label configuration variable. If the name of the current directory matches the name of the parent directory and the name of the current directory matches .*\/(\d+)$, the current page is treated as a numbered subpage and a new title is generated from the pagination configuration variable.

@navigation: A list of subpages. Contains all subpages except those matching any of the regexps in skip or those that are numbered subpages of the current page.

All the above arrays contain hashrefs with the following data:

    {
        name => 'Page Title',
        href => 'relative_path/'
    }

See also: _process()

_process()
Description of _process().
_post_process()
Removes the current directory from the breadcrumb trail and decrements $depth.
_bind_args()
Makes it possible to pass an object reference to the File::Find functions.

See also: http://perlmonks.thepen.com/109068.html

_create_directory($directory)
Creates the directory if it doesn’t exist. Uses the directory create mode defined in dir_mode.
_delete_files()
Calls $cache->sync() to get a list of the files removed from the input directory (if any). Deletes those files from the output directory.
_flush_output_directory()
Removes all content from the output directory.
_get_release()
Returns last release time from release_file. Sets release_time to 0 if release file doesn’t exist.
_html_index($filename)
Returns true if the file is an HTML index file, false otherwise.
_include($filename)
Returns true if $filename matches any of the regexps in include, false otherwise.
_init()
Description of init.
_init_stats()
Resets the counters used to gather processing statistics.
_pmt($lexicon_entry,@parameters)
Wrapper for the maketext function, prints the result from maketext() (Print MakeText).
_print_logline()
Prints formatted line to logfile.
_read_configuration_file()
Reads the configuration file specified on the commandline or the default configuration file. Settings in the configuration file override the defaults in %Configuration.

Creates cache directory if it doesn’t exist.

Initializes external postprocessing sub if present.

_rmt($lexicon_entry,@parameters)
Wrapper for the maketext function, returns the result from maketext() (Return MakeText).
_templates_in_path($directory)
Searches the current path for files with the extension template_extension. Templates in subdirectories override templates in the root directory.

The special template __base__ is set according to the configuration variable base_template.

_trail_links()
Creates relative links to the pages in the breadcrumb trail. Fixes links if the current file is not an HTML index file.

See also: _html_index()

_update_content($filename)
Prepares the content used by the templating system.
_update_release_file()
Sets the time in the release file to the current time.
_upload_files()
Upload processed files to the FTP server defined in the configuration file.
_validate_configuration()
Check configuration files for basic errors.
_validate_file($filename)
Inserts $filename in sp_command_line and executes the command.

Any error messages returned by the validator are appended to the errors string.


BUGS/CAVEATS/etc

No known bugs.


REQUIREMENTS

Yggdrasil requires the following modules:

AppConfig

Date::Format

Text::Template


AUTHOR

Morten Wulff, <wulff@psyke.org>


SEE ALSO

Text::Template


COPYRIGHT

Copyright 2002-2003, Morten Wulff

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.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

 Yggdrasil - Generates a website from a directory tree of content and templates