.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Poet::Manual::Tutorial 3pm" .TH Poet::Manual::Tutorial 3pm "2014-02-26" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Poet::Manual::Tutorial \- Poet tutorial .SH "DESCRIPTION" .IX Header "DESCRIPTION" 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 \*(L"hello world\*(R" for web frameworks. :) Thanks to Dancer and Flask for the inspiration. .SH "INSTALLATION" .IX Header "INSTALLATION" First we install Poet and a few other support modules. .PP If you don't yet have cpanminus (\f(CW\*(C`cpanm\*(C'\fR), get it here . Then run .PP .Vb 1 \& cpanm \-S \-\-notest DateTime DBD::SQLite Poet Rose::DB::Object .Ve .PP Omit the \*(L"\-S\*(R" if you don't have root, in which case cpanminus will install Poet and prereqs into \f(CW\*(C`~/perl5\*(C'\fR. .PP Omit the \*(L"\-\-notest\*(R" if you want to run all the installation tests. Note that this will take about four times as long. .SH "SETUP" .IX Header "SETUP" You should now have a \f(CW\*(C`poet\*(C'\fR app installed: .PP .Vb 2 \& % which poet \& /usr/local/bin/poet .Ve .PP Run this to create the initial environment: .PP .Vb 6 \& % poet new Blog \& blog/.poet_root \& blog/bin/app.psgi \& blog/bin/get.pl \& ... \& Now run \*(Aqblog/bin/run.pl\*(Aq to start your server. .Ve .PP The name of the app, \f(CW\*(C`Blog\*(C'\fR, will be used in app-specific class names. It is also used for the default directory name (\f(CW\*(C`blog\*(C'\fR), though you can move that wherever you want. .PP Run this to start your server: .PP .Vb 1 \& % blog/bin/run.pl .Ve .PP and you should see something like .PP .Vb 3 \& Running plackup \-\-Reload ... \-\-env development \-\-port 5000 \& Watching ... for file updates. \& HTTP::Server::PSGI: Accepting connections at http://0:5000/ .Ve .PP and you should be able to hit that \s-1URL\s0 to see the Poet welcome page. .PP In Poet, your entire web site lives within a single directory hierarchy called the \fIenvironment\fR. It contains subdirectories for configuration, libraries, Mason components (templates), static files, etc. .PP From now on, every file we create in this tutorial is assumed to be under the environment root. .SH "DATA LAYER (MODEL)" .IX Header "DATA LAYER (MODEL)" For any website it's a good idea to have a well-defined, object-oriented \&\fImodel\fR 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. .PP For this demo we'll represent blog articles with a single sqlite table. Create a file \f(CW\*(C`db/schema.sql\*(C'\fR with: .PP .Vb 6 \& create table if not exists articles ( \& id integer primary key autoincrement, \& content string not null, \& create_time timestamp not null, \& title string not null \& ); .Ve .PP Then run .PP .Vb 2 \& % cd blog \& % sqlite3 \-batch data/blog.db < db/schema.sql .Ve .PP We'll use Rose::DB::Object to provide a nice object-oriented \s-1API\s0 to our data (DBIx::Class would work as well). Create a file \f(CW\*(C`lib/Blog/DB.pm\*(C'\fR to tell Rose how to connect to our database: .PP .Vb 1 \& lib/Blog/DB.pm: \& \& package Blog::DB; \& use Poet qw($poet); \& use strict; \& use warnings; \& use base qw(Rose::DB); \& \& _\|_PACKAGE_\|_\->use_private_registry; \& _\|_PACKAGE_\|_\->register_db( \& driver => \*(Aqsqlite\*(Aq, \& database => $poet\->data_path("blog.db"), \& ); \& \& 1; .Ve .PP and a file \f(CW\*(C`lib/Blog/Article.pm\*(C'\fR to represent the articles table: .PP .Vb 1 \& lib/Blog/Article.pm: \& \& package Blog::Article; \& use Blog::DB; \& use strict; \& use warnings; \& use base qw(Rose::DB::Object); \& \& _\|_PACKAGE_\|_\->meta\->setup( \& table => \*(Aqarticles\*(Aq, \& auto => 1, \& ); \& _\|_PACKAGE_\|_\->meta\->make_manager_class(\*(Aqarticles\*(Aq); \& sub init_db { Blog::DB\->new } \& \& 1; .Ve .PP Basically this gives us .IP "\(bu" 4 a \f(CW\*(C`Blog::Article\*(C'\fR class with a constructor for inserting articles and instance methods for each of the columns, and .IP "\(bu" 4 a \f(CW\*(C`Blog::Article::Manager\*(C'\fR class (autogenerated) for searching for and retrieving multiple articles .PP See Rose::DB::Object::Tutorial for more information. .SH "QUICK VARS AND UTILITIES" .IX Header "QUICK VARS AND UTILITIES" In \f(CW\*(C`lib/Blog/DB.pm\*(C'\fR above, we have .PP .Vb 1 \& use Poet qw($poet); .Ve .PP followed by .PP .Vb 1 \& database => $poet\->data_path("blog.db"), .Ve .PP \&\f(CW$poet\fR 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. .PP More generally \f(CW$poet\fR is one of several special Poet \*(L"quick vars\*(R" that can be imported into any package, just by including it on the \f(CW\*(C`use Poet\*(C'\fR line. Another important one is \f(CW$conf\fR, which gives you access to configuration: .PP .Vb 3 \& use Poet qw($conf $poet); \& ... \& my $value = $conf\->get(\*(Aqkey\*(Aq, \*(Aqdefault\*(Aq); .Ve .PP You can also import sets of utilities in the same way, e.g. ':file' for file utilities and ':web' for web-related utilities. See Poet::Import for the full list of Poet vars and utility sets. .SH "CONFIGURATION" .IX Header "CONFIGURATION" Poet configuration files are kept in the \f(CW\*(C`conf\*(C'\fR subdirectory. The files are in \&\s-1YAML\s0 form and are merged in a particular order to create a single configuration hash. .PP For this tutorial we can ignore everything but \f(CW\*(C`conf/local.cfg\*(C'\fR. It currently contains: .PP .Vb 1 \& layer: development \& \& server.port: 5000 .Ve .PP This says that you are in development mode (so that you'll see errors directly in the browser, etc.) and running on port 5000. .PP You'll need to add one more entry: .PP .Vb 2 \& server.load_modules: \& \- Blog::Article .Ve .PP This says to load \f(CW\*(C`Blog::Article\*(C'\fR, our model, on server startup. .PP See Poet::Conf for More information on configuration. .SH "MASON PAGES AND COMPONENTS" .IX Header "MASON PAGES AND COMPONENTS" Mason is the templating engine that you'll use to render pages (the \fIview\fR), and is also responsible for routing URLs to specific pieces of code (the \&\fIcontroller\fR). So it's not surprising that most of the rest of this tutorial will focus on Mason. .PP Mason's basic building block is the \fIcomponent\fR \- a file with a mix of Perl and \s-1HTML.\s0 All components lives under the subdirectory \f(CW\*(C`comps\*(C'\fR; this is known in Mason parlance as the component root. .PP Given a \s-1URL,\s0 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. .PP \&\f(CW\*(C`poet new\*(C'\fR generated a few starter components for us, but we're not going to use those, so let's clear them by running .PP .Vb 1 \& rm \-fR comps; mkdir comps .Ve .PP Now here's our first component to serve the home page, \f(CW\*(C`comps/index.mc\*(C'\fR: .PP .Vb 1 \& comps/index.mc: \& \& 1 \& 2 \& 3 \& 4 My Blog: Home \& 5 \& 6 \& 7 \& 8

Welcome to my blog.

\& 9 \& 10 <& all_articles.mi &> \& 11 \& 12 Add an article \& 13 \& 14 \& 15 .Ve .PP Any component with a \f(CW\*(C`.mc\*(C'\fR extension is considered a top-level component. \&\f(CW\*(C`index.mc\*(C'\fR is a special path \- it will match the \s-1URI\s0 of its directory, in this case '/'. (For more special paths and details on how Mason finds page components, see Mason::Manual::RequestDispatch.) .PP Most of this component contains just \s-1HTML,\s0 which will be output exactly as written. The single piece of special Mason syntax here is .PP .Vb 1 \& 10 <& all_articles.mi &> .Ve .PP This is a component call \- it invokes another component, whose output is inserted in place. .SS "%\-lines, substitution tags, <%init> blocks" .IX Subsection "%-lines, substitution tags, <%init> blocks" Next we create \f(CW\*(C`comps/all_articles.mi\*(C'\fR. Because it has an \f(CW\*(C`.mi\*(C'\fR extension rather than \f(CW\*(C`.mc\*(C'\fR, it is an internal rather than a top-level component, and cannot be reached by an external \s-1URL.\s0 It can only be reached via a component call from another component. .PP .Vb 1 \& comps/all_articles.mi \& \& 1 % if (@articles) { \& 2 Showing <% scalar(@articles) %> article<% @articles > 1 ? "s" : "" %>. \& 3
    \& 4 % foreach my $article (@articles) { \& 5
  • <& article/display.mi, article => $article &>
    • \& 6 % } \& 7
\& 8 % } \& 9 % else { \& 10

No articles yet.

\& 11 % } \& 12 \& 13 <%init> \& 14 my @articles = @{ Blog::Article::Manager\->get_articles \& 15 (sort_by => \*(Aqcreate_time DESC\*(Aq) }; \& 16 .Ve .PP Three new pieces of syntax here: .IP "Init block" 4 .IX Item "Init block" The <%init> block on lines 13\-16 specifies a block of Perl code to run first when this component is called. In this case it fetches and sorts the list of articles into a lexical variable \f(CW@articles\fR. .IP "%\-lines" 4 .IX Item "%-lines" %\-lines \- lines beginning with a single '%' \&\- are treated as Perl rather than \s-1HTML. \s0 They are especially good for loops and conditionals. .IP "Substitution tags" 4 .IX Item "Substitution tags" This line .Sp .Vb 1 \& 2 Showing <% scalar(@articles) %> article<% @articles > 1 ? "s" : "" %>. .Ve .Sp shows two substitution tags. Code within \f(CW\*(C`<%\*(C'\fR and \f(CW\*(C`%>\*(C'\fR is treated as a Perl expression, and the result of the expression is output in place. .PP We see another component call here, \f(CW\*(C`article/display.mi\*(C'\fR, 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. .SS "Attributes" .IX Subsection "Attributes" Next we create \f(CW\*(C`comps/article/display.mi\*(C'\fR. (It is in a new subdirectory, showing that you can freely organize components among different directories.) .PP .Vb 1 \& comps/article/display.mi: \& \& 1 <%class> \& 2 use Date::Format; \& 3 my $date_fmt = "%A, %B %d, %Y %I:%M %p"; \& 4 has \*(Aqarticle\*(Aq => (required => 1); \& 5 \& 6 \& 7
\& 8

<% $.article\->title %>

\& 9

<% $.article\->create_time\->strftime($date_fmt) %>

\& 10 <% $.article\->content %> \& 11
.Ve .PP 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 \&\f(CW\*(C`<%class>\*(C'\fR section. .PP On line 4 we declare a single incoming attribute, \f(CW\*(C`article\*(C'\fR. It is \&\fIrequired\fR, meaning that if \f(CW\*(C`all_articles.mi\*(C'\fR had forgotten to pass it, we'd get a fatal error. .PP Throughout this component, we refer to the article attribute via the expression .PP .Vb 1 \& $.article .Ve .PP This not-quite-valid-Perl syntax is transformed behind the scenes to .PP .Vb 1 \& $self\->article .Ve .PP 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. :) .SS "Content wrapping, autobases, inheritance, method modifiers" .IX Subsection "Content wrapping, autobases, inheritance, method modifiers" Now we have to handle the \s-1URL \s0\f(CW\*(C`/new_article\*(C'\fR, linked from the home page. We do this with our second page component, \f(CW\*(C`comps/new_article.mc\*(C'\fR. It contains only \&\s-1HTML \s0(for now). .PP .Vb 1 \& comps/new_article.mc: \& \& 1 \& 2 \& 3 \& 4 My Blog: Home \& 5 \& 6 \& 7 \& 8

Add an article

\& 9 \& 10
\& 11

Title:

\& 12

Text:

\& 13 \& 14

\& 15
\& 16 \& 17 \& 18 .Ve .PP Notice that \f(CW\*(C`comps/index.mc\*(C'\fR and \f(CW\*(C`comps/new_article.mc\*(C'\fR have the same outer \&\s-1HTML\s0 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 \f(CW\*(C`comps/index.mc\*(C'\fR and \f(CW\*(C`comps/new_article.mc\*(C'\fR and place them into a new component called \f(CW\*(C`comps/Base.mc\*(C'\fR: .PP .Vb 1 \& comps/Base.mc: \& \& 1 <%augment wrap> \& 2 \& 3 \& 4 \& 5 My Blog \& 6 \& 7 \& 8 <% inner() %> \& 9 \& 10 \& 11 .Ve .PP When any page in our hierarchy is rendered, \f(CW\*(C`comps/Base.mc\*(C'\fR 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). .PP Now, we can remove everything but the inside of the \f(CW\*(C`\*(C'\fR tag from \&\f(CW\*(C`comps/index.mc\*(C'\fR and \f(CW\*(C`comps/new_article.mc\*(C'\fR. .PP .Vb 1 \& comps/index.mc: \& \&

Welcome to my blog.

\& \& <& all_articles.mi &> \& \& Add an article \& \& comps/new_article.mc \& \&

Add an article

\& \&
\&

Title:

\&

Text:

\& \&

\&
.Ve .PP More details on how content wrapping works here. .SS "Form handling, pure-perl components" .IX Subsection "Form handling, pure-perl components" \&\f(CW\*(C`/new_article.mc\*(C'\fR posts to \f(CW\*(C`/article/publish\*(C'\fR. Let's create a component to handle that, called \f(CW\*(C`comps/article/publish.mp\*(C'\fR. It will not output anything, but will simply take action and redirect. .PP .Vb 1 \& comps/article/publish.mp: \& \& 1 has \*(Aqcontent\*(Aq; \& 2 has \*(Aqtitle\*(Aq; \& 3 \& 4 method handle () { \& 5 my $session = $m\->session; \& 6 if ( !$.content || !$.title ) { \& 7 $session\->{message} = "Content and title required."; \& 8 $session\->{form_data} = $.args; \& 9 $m\->redirect(\*(Aq/new_article\*(Aq); \& 10 } \& 11 my $article = Blog::Article\->new( \& 12 title => $.title, \& 13 content => $.content, \& 14 create_time => DateTime\->now( time_zone => \*(Aqlocal\*(Aq ) \& 15 ); \& 16 $article\->save; \& 17 $session\->{message} = sprintf( "Article \*(Aq%s\*(Aq saved.", $.title ); \& 18 $m\->redirect(\*(Aq/\*(Aq); \& 19 } .Ve .PP The \f(CW\*(C`.mp\*(C'\fR 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 \f(CW\*(C`.mc\*(C'\fR component containing a single \f(CW\*(C`<%class>\*(C'\fR block, but this is easier and more self-documenting. .PP On lines 1 and 2 we declare incoming attributes. Because this is a top-level page component, the attributes will be populated with our \s-1POST\s0 parameters. .PP On line 4 we define a \f(CW\*(C`handle\*(C'\fR method to validate the \s-1POST\s0 parameters, create the article, and redirect. \f(CW\*(C`handle\*(C'\fR is one of the structural methods that Mason calls initially on all top-level page components; the default just renders the component's \s-1HTML\s0 as we've seen before. Defining \f(CW\*(C`handle\*(C'\fR 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.) .PP The \f(CW\*(C`method\*(C'\fR keyword comes from Method::Signatures::Simple, which is imported into components by default; see Mason::Component::Moose. .PP On line 5 we grab the Plack session via \f(CW\*(C`$m\->session\*(C'\fR. This is one of a handful of web-related methods only available in Poet. .PP On lines 7 and 17, we set a message in the session that we want to display on the next page. Rather than just making this work for a specific page, let's add generic code to the template in \f(CW\*(C`Base.mc\*(C'\fR: .PP .Vb 1 \& comps/Base.mc: \& \& 7 \& => 8 % if (my $message = delete($m\->session\->{message})) { \& => 9
<% $message %>
\& => 10 % } \& 11 <% inner() %> \& 12 .Ve .PP Now, any page can place a message in the session, and it'll appear on just the next page. .PP On line 8, we place the \s-1POST\s0 data in the session so that we can repopulate the form with it \- we'll do that in the next chapter. \f(CW\*(C`$.args\*(C'\fR is a special component attribute that contains all the arguments passed to the component. .SS "Filters" .IX Subsection "Filters" We need to change \f(CW\*(C`comps/new_article.mc\*(C'\fR to repopulate the form with the submitted values when validation fails. .PP .Vb 1 \& comps/new_article.mc: \& \& 1

Add an article

\& 2 \& ==> 3 % $.FillInForm($form_data) {{ \& 4
\& 5

Title:

\& 6

Text:

\& 7 \& 8

\& 9
\& ==> 10 % }} \& 11 \& ==> 12 <%init> \& ==> 13 my $form_data = delete($m\->session\->{form_data}); \& ==> 14 .Ve .PP On lines 3 and 10 we surround the form with a \fIfilter\fR. A filter takes a content block as input and returns a new content block which is output in its place. In this case, the \f(CW\*(C`FillInForm\*(C'\fR filter uses HTML::FillInForm to fill in the form from the values in \&\f(CW$form_data\fR. .PP Mason has a few built-in filters, and others are provided in plugins; for example \f(CW\*(C`FillInForm\*(C'\fR is provided in the HTMLFilters plugin. .PP Another common filter provided by this plugin is \f(CW\*(C`HTMLEscape\*(C'\fR, or \f(CW\*(C`H\*(C'\fR for short. We ought to use this in \f(CW\*(C`/article/display.mi\*(C'\fR when displaying the article title, in case it has any HTML-unfriendly characters in it: .PP .Vb 1 \&

<% $.article\->title |H %>

.Ve .PP See Mason::Manual::Filters for more information about using, and creating, filters. .SH "POET SCRIPTS" .IX Header "POET SCRIPTS" Up til now all our code has been in Mason components. Now let's say we want to create a \fIcron script\fR 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. .PP Run this from anywhere inside your environment: .PP .Vb 2 \& % poet script purge_old_entries.pl \& ...bin/purge_old_entries.pl .Ve .PP Poet created a stub script for us inside \f(CW\*(C`bin\*(C'\fR. Let's take a look: .PP .Vb 4 \& #!/usr/local/bin/perl \& use Poet::Script qw($conf $poet); \& use strict; \& use warnings; .Ve .PP Line 2 of the script initializes the Poet environment. This means Poet does several things: .IP "\(bu" 4 Searches upwards from the script for the environment root (as marked by the \&\f(CW\*(C`.poet_root\*(C'\fR file). .IP "\(bu" 4 Reads and parses your configuration. .IP "\(bu" 4 Unshifts onto \f(CW@INC\fR the lib/ subdirectory of your environment, so that you can \&\f(CW\*(C`use\*(C'\fR your application modules. .IP "\(bu" 4 Imports the specified quick vars \- in this case \f(CW$conf\fR and \f(CW$poet\fR \- into the script namespace. See Poet::Import. .PP Poet initialization has to happen exactly once per process, before any Poet features are used. In fact, take a look at \f(CW\*(C`bin/run.pl\*(C'\fR \*(-- 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. .PP Now we can fill out our purge script: .PP .Vb 5 \& #!/usr/local/bin/perl \& use Poet::Script qw($conf); \& use Blog::Article; \& use strict; \& use warnings; \& \& my $days_to_keep = $conf\->get( \*(Aqblog.days_to_keep\*(Aq => 365 ); \& my $min_date = DateTime\->now\->subtract( days => $days_to_keep ); \& Blog::Article::Manager\->delete_articles( \& where => [ create_time => { lt => $min_date } ] ); .Ve .PP In line 2, we've eliminated the unneeded \f(CW$poet\fR. .PP In line 7, we get \f(CW$days_to_keep\fR from configuration, giving it a reasonable default if there's nothing in configuration. .PP Finally in lines 8\-10 we delete articles less than the minimum date. .SH "FILES FROM THIS TUTORIAL" .IX Header "FILES FROM THIS TUTORIAL" The final set of files for our blog demo are in the \f(CW\*(C`eg/blog\*(C'\fR directory of the Poet distribution, or you can view them at github . .SH "SEE ALSO" .IX Header "SEE ALSO" Poet .SH "AUTHOR" .IX Header "AUTHOR" Jonathan Swartz .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2012 by Jonathan Swartz. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.