Zucchini::Config - manage configuration file loading
# get a new config object my $zcfg = Zucchini::Config->new(); # get the parsed config data my $stuff = $zcfg->get_data();
This module uses Config::Any to attempt to load .zucchini in the user's home directory.
.zucchini
The preferred format is Config::General, but any format supported by Config::Any can be used.
All examples will assume the user is using the Config::General format.
The .zucchini configuration file is the governing force for the behaviour of the various Zucchini components.
The file takes the following general form:
# the site section to use if none specified default_site 'sitelabel1' # site section definitions <site> <sitelabel1> ... </sitelabel1> <sitelabel2> ... </sitelabel2> </site>
The <sitelabelX> section contains information to configure the behaviour for a single website. This section takes the following general form:
<sitelabelX>
<sitelabel> source_dir /path/to/tt_templates includes_dir /path/to/tt_includes output_dir /var/www/default_site/html template_files \.html\z ignore_dirs CVS ignore_dirs .svn ignore_files \.swp\z ignore_files \.tmp\z <tags> variable1 value1 variable2 value2 </tags> <rsync> hostname remote.hosting.site path /home/username/default_site/www </rsync> <ftp> hostname remote.ftp.site username joe.bloggs password SecretWord passive 1 path /htdocs </ftp> <tt_options> PRE_PROCESS my_header POST_PROCESS my_footer # ... etc </sitelabel>
These are the blocks and variables that make up a .zucchini configuration file:
The <site> tag is a top-level element to hold the various configuration blocks for each site.
Each site specific configuration block is contained in a <sitelabel>...</sitelabel> block. "sitelabel" should be replaced with a meaningful label. For example, a configuration block for the site "www.herlpacker.co.uk" might look like this:
<sitelabel>...</sitelabel>
<site> <herlpacker> # site configuration here </herlpacker> </site>
To configure more than one site, simply add a new "sitelabel" block for each site:
<site> <herlpacker> # site configuration here </herlpacker> <chizography> # site configuration here </chizography> </site>
Found in a "sitelabel" block, this is the path to the root directory of the templated version of the site.
This is the directory that contains the files that will be processed and copied to the output_dir.
# e.g. source_dir /home/zucchini/sites/MYSITE/tt_templates
Found in a "sitelabel" block, this is the path to the directory containing blocks of Template Toolkit magic that are INCLUDEd or PROCESSed by the files in source_dir.
Examples of files you might expect to find as includes are header.tt and footer.tt - the common parts before and after the varying body content.
# e.g. source_dir /home/zucchini/sites/MYSITE/tt_includes
Found in a "sitelabel" block, this is the path to the directory where processed templates will be written to.
Also, files that are not ignored as a result of ignore_dirs or ignore_files will be copied to the appropriate location under this specified directory.
Quite often this will match the DocumentRoot location for a locally configured VirtualHost in apache2.
# e.g. output_dir /var/www/mysite
Found in a "sitelabel" block, this is the URL for the live site. It's primarily used by the Zucchini::Fsync functionality to retrieve the digest.md5 file it uses for local-remote file comparison.
# e.g. website http://www.mysite.com/
Found in a "sitelabel" block, this option specifies which files should be treated as templates.
Most of the time you will only need one entry, to specify files with the ".html" extension.
# .html files should be treated as templates template_files '\.html\z'
To indicate that other filetypes should also be treated as templates, add a new row for each filetype you require.
# .html files should be treated as templates template_files '\.html\z' # .txt files also require template processing template_files '\.txt\z'
The value used should be a perl regexp that can be applied to a filename. If in doubt, copy an existing rule and modify the '.html'.
Found in a "sitelabel" block, this option is used to specify directories which should not be processed during site templating.
This is mostly useful if your templates are managed with a version control system (e.g. CVS, or subversion) and you don't want the repository management directories to be copied as part of the live site source.
One ignore_dirs statement is required for each directory to be ignored.
# ignore CVS and subversion directories ignore_dirs 'CVS' ignore_dirs '.svn'
Found in a "sitelabel" block, this option is used to specify files which should not be processed during site templating.
This is useful to prevent, for example, editor swap files from being copied into the output_dir as part of the processed site source.
One ignore_files statement is required for each file to be ignored.
# ignore vim swap files ignore_files '\.swp\z'
Found in a "sitelabel" block, this option enables HTML error checking. While not as thorough as a full W3C validator, this option should alert you to commons errors.
# check for HTML errors lint_check 1
This block, found in a "sitelabel" block, is used to set variables that will be available in the template as a [% ... %] style variable.
[% ... %]
For example, defining:
<tags> author Joe Bloggs copyright © 2008 Joe Bloggs. All rights reserved. </tags>
will allow you to do the following in your templates (or footer.tt):
<p>Site Designed by [%author%]</p> <p>[%copyright%]</p>
This block, found in a "sitelabel" block, defines the conection details used when using the rsync options to transfer the generated site to the remote server.
<rsync> # options go here </rsync>
This block, found in a "sitelabel" block, defines the conection details used when using the fsync options to transfer the generated site to the remote server.
<ftp> # options go here </ftp>
Found in an "rsync" or "ftp" block, this is the destination server for the generated website.
# e.g. <rsync> hostname some.remote.server # ... </rsync>
In an "rsync" block you may prepend the value with the username:
# e.g. <rsync> hostname someuser@some.remote.server # ... </rsync>
Found in an "rsync" or "ftp" block, this is the path on the remote server where the generated site will be copied to.
Note: You don't usually require a trailing '-' for the "path" value inside an "rsync" block.
# e.g. <rsync> # ... path /home/someuser/MYSITE/www </rsync>
Found in an "ftp" block, this is the username used during the FTP log-in phase of the remote transfer.
# e.g. <ftp> # ... username joebloggs </ftp>
Found in an "ftp" block, this is the password used during the FTP log-in phase of the remote transfer.
# e.g. <ftp> # ... password SekritWurd </ftp>
Note: This password is stored unencrypted. Please be strict with the file permissions of your .zucchini file, preferably making the file only readable to yourself:
# stop people peeking at our FTP credentials chmod 0600 ~/.zucchini
This block allows you to set or override configuration options for the Template object that's created to process the templates.
No validation is performed by Zucchini. You can explore the available options by reading Template::Manual::Config's manual.
# e.g. <tt_options> PRE_PROCESS my_header POST_PROCESS my_footer EVAL_PERL 1 </tt_options> =back
Sometimes it can be tedious adding the same command-line switches to calls to zucchini.
You can preset commonly used options in the cli_defaults section of your .zucchini file:
<cli_defaults> verbose 1 showdest 1 showpath 1 </cli_defaults>
Any options specified on the command-line will take precedence over the defaults in the .zucchini file.
# we don't really want to see the destination zucchini --no-showdest
Zucchini, Zucchini::Fsync, Zucchini::Rsync, Config::Any, Config::General
Chisel Wright <chiselwright@users.berlios.de>
<chiselwright@users.berlios.de>
Copyright 2008-2009 by Chisel Wright
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See <http://www.perl.com/perl/misc/Artistic.html>
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install Zucchini, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Zucchini
CPAN shell
perl -MCPAN -e shell install Zucchini
For more information on module installation, please visit the detailed CPAN module installation guide.