Zucchini::Manual::Tutorial - simple website example
version 0.0.19
This tutorial will guide you through the process of setting up a simple website using Zucchini.
For the purposes of this tutorial it is assumed that you have a user on your system with the username zuke.
zuke
zuke is assumed to have never run zucchini before.
zucchini
zuke should have sudo super-powers for the initial directory configuration.
Firstly we will create the area in which the website templates are created.
mkdir -p $HOME/sites/zuke/{templates,includes}
We also require somewhere for the generated output to live. We'll keep our (local) website sources somewhere easy to find, rather than hidden away in zuke's home directory.
sudo mkdir -p /var/www/zuke/{html,log} sudo chown -R zuke:www-data /var/www/zuke
This step is optional, but provides a convenient way to view and verify the site before uploading it to the remote (live) server.
Configuring apache2 is beyond the scope of this tutorial. In a nutshell, make sure you are configured to use <VirtualHost>s and add the following block to your configuration:
<VirtualHost>
<VirtualHost www_zuke.private.somedomain.co.uk> ServerAdmin zuke@localhost ServerName www_zuke.private.somedomain.co.uk DocumentRoot /var/www/zuke/html ErrorLog /var/www/log/error_log CustomLog /var/www/log/access_log common <Directory /var/www/zuke/html> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory> </VirtualHost>
You'll also require a tweak to your local hosts file to recognise the hostname used:
sudo sh -c \ 'echo "127.0.1.77 www_zuke.private.somedomain.co.uk www_zuke" \ >> /etc/hosts'
You should now restart apache2 for the changes to take effect.
Debian/Ubuntu users can paste the VirtualHost block above into a new file in /etc/apache2/sites-enabled/ and use a2ensite:
a2ensite
sudo $EDITOR /etc/apache2/sites-available/zuke # paste in VirtualHost block sudo a2ensite zuke sudo /etc/init.d/apache2 restart
It's possible to build a .zucchini configuration file from scratch. Most people find it easier to have a working example to copy and modify.
.zucchini
We'll start by creating a default configuration file, and ammend it to process the new site we're building.
zucchini --create-config
If all goes well, you will see no output on your screen. A new file should have been written to your home directory:
$ ls -l $HOME/.zucchini -rw-r--r-- 1 zuke zuke 1956 2008-05-20 08:39 /home/zuke/.zucchini
Running zucchini now will result in errors about a missing site configuration and the script will terminate.
We'll add a new section for our new site.
$EDITOR $HOME/.zucchini
Alter
default_site default
to read
default_site zuke
Also, after the <site> opening tag add:
<site>
<zuke> source_dir /home/zuke/sites/zuke/templates includes_dir /home/zuke/sites/zuke/includes output_dir /var/www/zuke/html template_files \.html\z ignore_dirs CVS ignore_dirs \.svn ignore_files \.swp\z <tags> author Zuke Hini copyright © 2006-2008 Zuke Hini. All rights reserved. </tags> </zuke>
We're now ready to rock and roll!
This section takes you through the first steps in creating the source files for a new webite.
zucchini is configured for our new site. There's one slight problem; we don't have anything to generate the site from.
Time to rectify this oversight!
Let's start by creating a shared header and footer for all of the pages we will create.
Create a new header file:
$EDITOR $HOME/sites/zuke/includes/header.tt
and add the following HTML markup to it:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>[% author %]'s Site</title> </head> <body>
Save the file and exit the editor.
Create a new footer file:
$EDITOR $HOME/sites/zuke/includes/footer.tt
<p>[% copyright %]</p> </body> </html>
We'll now create the main index.html page for the site. Create the new file:
$EDITOR $HOME/sites/zuke/templates/index.html
and add the following to it:
[% PROCESS header.tt %] <h1>[% author %]'s Main Page</h1> <p>It's simple, but it works</p> [% PROCESS footer.tt %]
For the curious, [% PROCESS ... %] is Template::Toolkit's way of including other files into the current file.
[% PROCESS ... %]
Now that we have some source files we can ask zucchini to work its magic for us.
As this is our first time with it, we'll ask it to tell us more about what it's doing.
Run the following command in your terminal:
zucchini --showdest --showpath
You should see the following output:
templating: index.html --> /var/www/zuke/html/index.html
If you look at /var/www/zuke/html/index.html you'll see that our three files have been glued together into one HTML file.
/var/www/zuke/html/index.html
Assuming you've set up your webserver as described earlier in the tutorial you can also visit http://www_zuke/ in your browser to view the page.
Some of you may already have noticed that we snuck some voodoo into two of the files we created for the site source:
<title>[% author %]'s Site</title>
and <h1>[% author %]'s Main Mage</h1>
and also
<p>[% copyright %]</p>
As a rule, anything of the form [% ... %] is Template::Toolkit markup. At the most basic level, it's used to include other files, and to insert user-defined variables into documents.
[% ... %]
author and copyright are both defined in the <tags> section of the configuration block for our site.
author
copyright
<tags>
[% author %] means: insert the value we assigned to author here.
[% author %]
A one-page site is pretty easy to maintain without Zucchini, so we'll add a second page to the site to demonstrate Zuchini further.
$EDITOR $HOME/sites/zuke/templates/about.html
[% PROCESS header.tt %] <h1>About [% author %]'s Site</h1> <p>This site was created with the help of Zucchini</p> <p>Head back to the <a href="/">main page</a></p> [% PROCESS footer.tt %]
Regenerate the site:
templating: about.html --> /var/www/zuke/html/about.html
Visit http://www_zuke/about.html in your browser to view the page.
A couple of things that you should note here:
only the newly added page was processed
This is intentional. There's rarely any need to re-process unchanged templates. If you do need to regenerate the entire site use --force
--force
the URL for the main page was absolute not relative
There's nothing stopping you from using relative URLs. It's nearly always easier, and clearer, to use absolute URLs.
We'll add an image to the site to demonstrate to non-template files.
We'll create a directory for icons to live in, and then copy an apache2 icon into the directory.
If /usr/share/apache2/icons/index.png doesn't exist, please replace it with the path to any image of your choosing.
/usr/share/apache2/icons/index.png
mkdir -p $HOME/sites/zuke/templates/images/icons/ cp /usr/share/apache2/icons/index.png \ $HOME/sites/zuke/templates/images/icons/
output directory '/var/www/zuke/html/images' does not exist created: /var/www/zuke/html/images output directory '/var/www/zuke/html/images/icons' does not exist created: /var/www/zuke/html/images/icons Copying: images/icons/index.png --> /var/www/zuke/html/images/icons/index.png
Zucchini automatically creates required directories in the output location, then copies the non-template file into the correct location.
Zucchini treats all non-template files in this manner. If you would like more files to be treated as templates, edit your .zucchini configuration file and add more template_files options:
template_files
# treat txt files as templates template_files \.txt\z
As with template files, unmodified files will not be processed unless they have been modified.
There are times when you may wish to re-process the entire site. Often this is because you have edited a file in the includes/ directory and wish the modification to be applied across the site.
includes/
(For various reasons altering an includes/ file will not trigger the regeneration of files in templates/ that [% PROCESS %] or [% INCLUDE %] them)
templates/
[% PROCESS %]
[% INCLUDE %]
Simply use the --force option and modification inforation will be ignored:
There are two methods available for transferring files to your remote web server: rsync and ftp.
Before using either method please ensure that you have a working backup of your site. Both methods have been extensively used by the author but he's always worried that he's overlooked something important that does bad things during the upload phase.
If you're really lucky you'll have ssh access to your server. If you do, you can use the --rsync option to transfer your site to the remote server.
--rsync
You'll need to add the following inside the <zuke> ... </zuke> block in your configuration file:
<zuke> ... </zuke>
<rsync> hostname localhost path /home/zuke/rsync-test </rsync>
You should change the values to match your own situation.
To transfer files after re-processing:
zucchini --showdest --showpath --rsync
Most of the time you will be limited to ftp for transferring files to your server. Because transferring the entire site would be boring, time-consuming and wasteful of bandwidth Zucchini implements a form of poor-man's rsync.
fsync uses files in the local output directory and on the remote server to track files and whether or not they have been modified. (digest.md5)
It will only transfer files that exist locally and appear to have changed since the last transfer using fsync.
<ftp> hostname localhost username zucchini password courgette passive 1 path /zuke </ftp>
Once again, change the values to match your own situation - transferring files via FTP to the machine you are transferring files from is almost definitely not the behaviour you require.
passive and path are both optional values, but it's better to be explicit.
zucchini --showdest --showpath --fsync --verbose
Which should result in the following output:
No remote digest checking remote directories... MKDIR /zuke/images MKDIR /zuke/images/icons transferring files... PUT about.html about.html PUT index.html index.html PUT images/icons/index.png images/icons/index.png PUT digest.md5
The first time you use --fsync for a site it will always transfer all files; the remote file it uses for comparison won't yet exist.
--fsync
Once you're happy that --fsync is Doing The Right Thing you can omit the --verbose option. As ftp is a frustrating protocol to use, it's often better to use --verbose and keep an eye on it.
--verbose
If things go terribly wrong --ftp-debug will throw even more information onto your screen.
--ftp-debug
Zucchini - the top-level project module
Template::Manual::Intro - an introduction to the templating system
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>
Chisel <chisel@chizography.net>
This software is copyright (c) 2012 by Chisel Wright.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
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.