This tutorial provides a tour of Poet by showing how to build a sample web application - specifically a micro-blog,
which seems to be a popular "hello world" for web frameworks.
:) Thanks to Dancer and Flask for the inspiration.

In Poet, your entire web site lives within a single directory hierarchy called the environment. It contains subdirectories for configuration, libraries, Mason components (templates), static files, etc.

From now on, every file we create in this tutorial is assumed to be under the environment root.

For any website it's a good idea to have a well-defined, object-oriented model through which you retrieve and change data. Poet and Mason don't have much to say about how you do this, so we'll make some minimal reasonable choices here and move on.

For this demo we'll represent blog articles with a single sqlite table. Create a file db/schema.sql with:

$poet is the global Poet::Environment object, providing information about the environment and its directory paths. We use it here to get the full path to our sqlite database, without having to hardcode our environment root.

More generally $poet is one of several special Poet "quick vars" that can be imported into any package, just by including it on the use Poet line. Another important one is $conf, which gives you access to configuration:

Mason is the templating engine that you'll use to render pages (the view), and is also responsible for routing URLs to specific pieces of code (the controller). So it's not surprising that most of the rest of this tutorial will focus on Mason.

Mason's basic building block is the component - a file with a mix of Perl and HTML. All components lives under the subdirectory comps; this is known in Mason parlance as the component root.

Given a URL, Mason will dispatch to a top-level component. This component decides the overall page layout, and then may call other components to fill in the details.

poet new generated a few starter components for us, but we're not going to use those, so let's clear them by running

rm -fR comps; mkdir comps

Now here's our first component to serve the home page, comps/index.mc:

Any component with a .mc extension is considered a top-level component. index.mc is a special path - it will match the URI of its directory, in this case '/'. (For more special paths and details on how Mason finds page components, see Mason::Manual::RequestDispatch.)

Most of this component contains just HTML, which will be output exactly as written. The single piece of special Mason syntax here is

10 <& all_articles.mi &>

This is a component call - it invokes another component, whose output is inserted in place.

Next we create comps/all_articles.mi. Because it has an .mi extension rather than .mc, it is an internal rather than a top-level component, and cannot be reached by an external URL. It can only be reached via a component call from another component.

shows two substitution tags. Code within <% and %> is treated as a Perl expression, and the result of the expression is output in place.

We see another component call here, article/display.mi, which displays a single article; we pass the article object in a name/value argument pair. Components can be in different directories and component paths can be relative or absolute.

The <%class> block on lines 1-4 specifies a block of Perl code to place near the top of the generated component class, outside of any methods. This is the place to use modules, declare permanent constants/variables, declare attributes with 'has', and define helper methods. Most components of any complexity will probably have a <%class> section.

On line 4 we declare a single incoming attribute, article. It is required, meaning that if all_articles.mi had forgotten to pass it, we'd get a fatal error.

Throughout this component, we refer to the article attribute via the expression

$.article

This not-quite-valid-Perl syntax is transformed behind the scenes to

$self->article

and is one of the rare cases in Mason where we create new syntax on top of Perl, because we want attributes and method calls to be as convenient as possible. The transformation itself is performed by the DollarDot plugin, which is in the default plugins list but can be omitted if the source filtering offends you. :)

Notice that comps/index.mc and comps/new_article.mc have the same outer HTML template; other pages will as well. It's going to be tedious to repeat this everywhere. And of course, we don't have to. We take the common pieces out of the comps/index.mc and comps/new_article.mc and place them into a new component called comps/Base.mc:

When any page in our hierarchy is rendered, comps/Base.mc will get control first. It will render the upper portion of the template (lines 2-7), then call the specific page component (line 8), then render the lower portion of the template (lines 9-10).

Now, we can remove everything but the inside of the <body> tag from comps/index.mc and comps/new_article.mc.

The .mp extension indicates that this is a pure-perl component. Other than the 'package' and 'use Moose' lines that are generated by Mason, it looks just like a regular Perl class. You could accomplish the same thing with a .mc component containing a single <%class> block, but this is easier and more self-documenting.

On lines 1 and 2 we declare incoming attributes. Because this is a top-level page component, the attributes will be populated with our POST parameters.

On line 4 we define a handle method to validate the POST parameters, create the article, and redirect. handle is one of the structural methods that Mason calls initially on all top-level page components; the default just renders the component's HTML as we've seen before. Defining handle is the way to take an action without rendering anything, which is perfect for form actions. (It's always better to redirect after a form action than to display content directly.)

Now, any page can place a message in the session, and it'll appear on just the next page.

On line 8, we place the POST data in the session so that we can repopulate the form with it - we'll do that in the next chapter. $.args is a special component attribute that contains all the arguments passed to the component.

On lines 3 and 10 we surround the form with a filter. A filter takes a content block as input and returns a new content block which is output in its place. In this case, the FillInForm filter uses HTML::FillInForm to fill in the form from the values in $form_data.

Mason has a few built-in filters, and others are provided in plugins; for example FillInForm is provided in the HTMLFilters plugin.

Another common filter provided by this plugin is HTMLEscape, or H for short. We ought to use this in /article/display.mi when displaying the article title, in case it has any HTML-unfriendly characters in it:

Up til now all our code has been in Mason components. Now let's say we want to create a cron script to purge blog entries older than a configurable number of days. The script, of course, will need access to the same Poet features as our components.

Run this from anywhere inside your environment:

% poet script purge_old_entries.pl
...bin/purge_old_entries.pl

Poet created a stub script for us inside bin. Let's take a look:

#!/usr/local/bin/perl
use Poet::Script qw($conf $poet);
use strict;
use warnings;

Line 2 of the script initializes the Poet environment. This means Poet does several things:

Searches upwards from the script for the environment root (as marked by the .poet_root file).

Reads and parses your configuration.

Unshifts onto @INC the lib/ subdirectory of your environment, so that you can use your application modules.

Imports the specified quick vars - in this case $conf and $poet - into the script namespace. See Poet::Import.

Poet initialization has to happen exactly once per process, before any Poet features are used. In fact, take a look at bin/run.pl -- which was generated for you initially -- and you'll see that it does 'use Poet::Script' as well. This initializes Poet for the entire web environment.