/ 
Zucchini-0.0.21
River stage zero No dependents
/ Zucchini::Manual::Tutorial

NAME

Zucchini::Manual::Tutorial - simple website example

VERSION

version 0.0.21

DESCRIPTION

This tutorial will guide you through the process of setting up a simple website using Zucchini.

NAME

Zucchini::Manual::Tutorial - simple website example

ASSUMPTIONS

For the purposes of this tutorial it is assumed that you have a user on your system with the username zuke.

zuke is assumed to have never run zucchini before.

zuke should have sudo super-powers for the initial directory configuration.

SETTING UP

Local Website Source

Firstly we will create the area in which the website templates are created.

mkdir -p $HOME/sites/zuke/{templates,includes}

Local Website Output

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

Adding an apache2 virtualhost

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 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

Debian/Ubuntu users can paste the VirtualHost block above into a new file in /etc/apache2/sites-enabled/ and use a2ensite:

sudo $EDITOR /etc/apache2/sites-available/zuke
# paste in VirtualHost block
sudo a2ensite zuke
sudo /etc/init.d/apache2 restart

Configuring Zucchini

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.

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:

<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         &copy; 2006-2008 Zuke Hini. All rights reserved.
  </tags>
</zuke>

We're now ready to rock and roll!

CREATING A NEW SITE

This section takes you through the first steps in creating the source files for a new webite.

Generating the website

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.

includes/header.tt

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.

includes/footer.tt

Create a new footer file:

$EDITOR $HOME/sites/zuke/includes/footer.tt

and add the following HTML markup to it:

    <p>[% copyright %]</p>
  </body>
</html>

Save the file and exit the editor.

templates/index.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 %]

Save the file and exit the editor.

For the curious, [% PROCESS ... %] is Template::Toolkit's way of including other files into the current file.

Invoke zucchini

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.

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.

tag magic

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 %] means: insert the value we assigned to author here.

templates/about.html

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.

We'll now create the main index.html page for the site. Create the new file:

$EDITOR $HOME/sites/zuke/templates/about.html

and add the following to it:

[% 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:

zucchini --showdest --showpath

You should see the following output:

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

  • 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.

templates/images/icons/index.png

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.

mkdir -p $HOME/sites/zuke/templates/images/icons/
cp /usr/share/apache2/icons/index.png \
   $HOME/sites/zuke/templates/images/icons/

Regenerate the site:

zucchini --showdest --showpath

You should see the following output:

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:

# treat txt files as templates
template_files    \.txt\z

As with template files, unmodified files will not be processed unless they have been modified.

Regenerate everything

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.

(For various reasons altering an includes/ file will not trigger the regeneration of files in templates/ that [% PROCESS %] or [% INCLUDE %] them)

Simply use the --force option and modification inforation will be ignored:

Transferring Files

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.

Transferring via rsync

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.

You'll need to add the following inside the <zuke> ... </zuke> block in your configuration file:

<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

Transferring via fsync

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.

You'll need to add the following inside the <zuke> ... </zuke> block in your configuration file:

<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.

To transfer files after re-processing:

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.

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.

If things go terribly wrong --ftp-debug will throw even more information onto your screen.

SEE ALSO

Zucchini - the top-level project module

Template::Manual::Intro - an introduction to the templating system

AUTHOR

Chisel Wright <chiselwright@users.berlios.de>

LICENSE

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>

AUTHOR

Chisel <chisel@chizography.net>

COPYRIGHT AND LICENSE

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.