X-Git-Url: https://git.decadent.org.uk/gitweb/?p=maypole.git;a=blobdiff_plain;f=lib%2FMaypole%2FView%2FTT.pm;h=8759e0cba9206754a24783b7b82de80cb0e1d8f9;hp=9142f3ebe51bdbda78ffbde8f2a37e5de11f9f50;hb=0aed36464b4d092c9e32f70916fb38a1bb124ab6;hpb=5ba93a09518403ae28e8a71b5299e2458a6dfa0b diff --git a/lib/Maypole/View/TT.pm b/lib/Maypole/View/TT.pm index 9142f3e..8759e0c 100644 --- a/lib/Maypole/View/TT.pm +++ b/lib/Maypole/View/TT.pm @@ -2,22 +2,91 @@ package Maypole::View::TT; use base 'Maypole::View::Base'; use Maypole::Constants; use Template; +use File::Spec::Functions qw(catdir tmpdir); +use Template::Constants qw( :all ); + +our $error_template; +{ local $/; $error_template = ; } + +our $VERSION = '2.13'; + +my $debug_flags = DEBUG_ON; + +use strict; sub template { - my ( $self, $r ) = @_; - my $template = Template->new( { INCLUDE_PATH => [ $self->paths($r) ] } ); + my ( $self, $r ) = @_; + unless ($self->{tt}) { + my $view_options = $r->config->view_options || { POST_CHOMP=>1, PRE_CHOMP=>1, TRIM=>1 }; + if ($r->debug) { + $view_options->{DEBUG} = $debug_flags; + } + + $view_options->{POST_CHOMP} = 1 unless (exists $view_options->{POST_CHOMP}); + $self->{provider} = Template::Provider->new($view_options); + $self->{tt} = Template->new({ + %$view_options, + LOAD_TEMPLATES => [ $self->{provider} ], + }); + } + + $self->{provider}->include_path([ $self->paths($r) ]); + + my $template_file = $r->template; + + my $ext = $r->config->template_extension; + $template_file .= $ext if defined $ext; + + my $output; + my $processed_ok = eval{$self->{tt}->process($template_file, { $self->vars($r) }, \$output );}; + if ($processed_ok) { + $r->{output} = $output; + return OK; + } else { + if ($@) { + my $error = "fatal error in template '$template_file' : $@\nTT paths : " . join(', ',$self->paths($r)) . "\n"; + $r->warn($error); + $r->{error} = $error; + } else { + my $error = "TT error for template '$template_file'\n" . $self->{tt}->error . "\nTT paths : " . join(', ',$self->paths($r)) . "\n"; + $r->warn($error); + $r->{error} = $error; + } + return ERROR; + } +} + + +sub report_error { + my ($self, $r, $error, $type) = @_; my $output; - if ( $template->process( $r->template, { $self->vars($r) }, \$output ) ) { + + # Need to be very careful here. + my $tt = Template->new; + unless (ref $r->{config}) { + $r->warn("no config for this request"); + $error .= '
There was a problem finding configuration for this request'; + $r->{config} ||= {}; + } + + $r->warn("report_error - reporting error to user : $error\n"); + + if ($tt->process(\$error_template, + { err_type => $type, error => $error, + config => $r->{config}, + request => $r, + paths => [ $self->paths($r) ], + eval{$self->vars($r)} }, \$output )) { $r->{output} = $output; + if ($tt->error) { $r->{output} = "Even the error template + errored - ".$tt->error.""; } + $r->{content_type} ||= "text/html"; + $r->{document_encoding} ||= "utf-8"; return OK; } - else { - $r->{error} = $template->error; - return ERROR; - } + return ERROR; } -1; =head1 NAME @@ -25,15 +94,300 @@ Maypole::View::TT - A Template Toolkit view class for Maypole =head1 SYNOPSIS - BeerDB->config->{view} = "Maypole::View::TT"; # The default anyway + BeerDB->config->view("Maypole::View::TT"); # The default anyway + + # Set some Template Toolkit options + BeerDB->config->view_options( { + TRIM => 1, + COMPILE_DIR => '/var/tmp/mysite/templates', + } ); + + ..... + + [% PROCESS macros %] + + [% pager %] + + [% link %] + + [% maybe_link_view %] =head1 DESCRIPTION -This is the default view class for Maypole; it uses the Template Toolkit -to fill in templates with the objects produced by Maypole's model classes. -Please see the Maypole manual, and in particular, the C chapter, -for the template variables available and for a refresher on how template -components are resolved. +This is the default view class for Maypole; it uses the Template Toolkit to fill +in templates with the objects produced by Maypole's model classes. Please see +the L, and in particular, the +L chapter for the template variables available and +for a refresher on how template components are resolved. + +The underlying Template toolkit object is configured through +C<$r-Econfig-Eview_options>. See L for available +options. + +=over 4 + +=item template + +Processes the template and sets the output. See L + +=item report_error + +Reports the details of an error, current state and parameters + +=back + +=head1 TEMPLATE TOOLKIT INTRODUCTION + +The Template Toolkit uses it's own mini language described in +L. + +A simple example would be : + +=over 4 + +re:[% subject %] + +Dear [% title %] [% surname %], +Thank you for your letter dated [% your.date %]. This is to +confirm that we have received it and will respond with a more +detailed response as soon as possible. In the mean time, we +enclose more details of ... + +=back + +TT uses '[%' and '%]' (by default) to delimit directives within a template, and +the simple directives above just display the value of variable named within +those delimiters -- [% title %] will be replaced inline with the value of the +'title' variable passed in the 'stash' to the template when it is processed. + +You can access nested data through the dot ('.') operator, which will +dereference array or hash elements, but can also be used to call methods on +objects, i.e. '[% name.salutation("Dear %s,") %]'. The other main operator is +underscore ('_'), which will concatonate strings or variables. + +The value returned by a directive replaces the directive inline when the +template is processes, you can also SET a value which will not return anything, +or CALL a method or operation which will also not return anything. + +You can specify expressions using the logical (and, or, not, ?:) and mathematic +operators (+ - * / % mod div). + +Results of TT commands are interpolated in the place of the template tags, unless +using SET or CALL, i.e. [% SET foo = 1 %], [% GET foo.bar('quz'); %] + +=over 4 + +[% template.title or default.title %] + +[% score * 100 %] + +[% order.nitems ? checkout(order.total) : 'no items' %] + +=back + +TT allows you to include or re-use templates through it's INCLUDE, PROCESS and +INSERT directives, which are fairly self explainatory. You can also re-use parts +of template with the BLOCK or MACRO directives. + +Conditional and Looping constructs are simple and powerful, and TT provides an +inbuilt iterator and helper functions and classes that make life sweet. + +Conditional directives are IF, UNLESS, ELSIF, ELSE and behave as they would in +perl : + +=over 4 + +[% IF age < 10 %] + Hello [% name %], does your mother know you're using her AOL account? +[% ELSIF age < 18 %] + Sorry, you're not old enough to enter (and too dumb to lie about your age) +[% ELSE %] + Welcome [% name %]. +[% END %] + +[% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %] + +=back + +Looping directives are FOREACH, LAST and BREAK. + +FOREACH loops through a HASH or ARRAY processing the enclosed block for each +element. + +Looping through an array + + [% FOREACH i = items %] + [% i %] + [% END %] + +Looping through a hash + + [% FOREACH u IN users %] + * [% u.key %] : [% u.value %] + [% END %] + +Looping through an array of hashes + + [% FOREACH user IN userlist %] + * [% user.id %] [% user.name %] + [% END %] + +The LAST and BREAK directive can be used to exit the loop. + +The FOREACH directive is implemented using the Template::Iterator module. A +reference to the iterator object for a FOREACH directive is implicitly available +in the 'loop' variable. The loop iterator object provides a selection of methods +including size(), max(), first(), last(), count(), etc + +=over 4 + + [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%] + [%- "
    \n" IF loop.first %] +
  • [% loop.count %]/[% loop.size %]: [% item %] + [%- "
\n" IF loop.last %] + [% END %] + +=back + +See Template::Iterator for further details on looping and the Iterator. + +You might notice the minus ('-') operator in the example above, it is used to +remove a newline before or after a directive so that you can layout the Template +logic as above but the resulting output will look exactly how you require it. + +You will also frequently see comments and multi-line directives, # at the start +of a directive marks it as a comment, i.e. '[%# this is a comment %]'. A +multiline directive looks like : + + [% do.this; + do.that; + do.the_other %] + +You can see that lines are terminated with a semi-colon (';') unless the +delimter ('%]') closes the directive. + +For full details of the Template Toolkit see Template::Manual and +Template::Manual::Directives, you can also check the website, mailing list or +the Template Toolkit book published by O Reilly. + +=head1 TEMPLATE PLUGINS, FILTERS AND MACROS + +The Template Toolkit has a popular and powerful selection of Plugins and +Filters. + +TT Plugins provide additional functionality within Templates, from accessing CGI +and databases directly, handling paging or simple integration with Class::DBI +(for those rare occasions where you don't actually need Maypole). See +L. + +One plugin that is indispensible when using Maypole and the Template View is +C -- This allows you to import and use any class +installed within a template. For example : + +=over 4 + +[% USE foo = Class('Foo') %] +[% foo.bar %] + +=back + +Would do the equivilent of 'use Foo; Foo->bar;' in perl. See +L for details. + +TT Filters process strings or blocks within a template, allowing you to +truncate, format, escape or encode trivially. A useful selection is included +with Template Toolkit and they can also be found on CPAN or can be written +easily. See L. + +TT provides stderr and stdout filters, which allow you to write handy macros +like this one to output debug information to your web server log, etc : + +=over 4 + +[% MACRO debug_msg(text) + FILTER stderr; "[TT debug_msg] $text\n"; END; +%] + +=back + + +TT Macros allow you to reuse small blocks of content, directives, etc. The MACRO +directive allows you to define a directive or directive block which is then +evaluated each time the macro is called. Macros can be passed named parameters +when called. + +Once a MACRO is defined within a template or 'include'd template it can be used +as if it were a native TT directive. Maypole provides a selection of powerful +and useful macros in the templates/ directory of the package and these are used +in the beerdb and default templates. See the MACRO section of the +L documentation. + +=head1 ACCESSING MAYPOLE VALUES + +=head2 request + +You can access the request in your templates in order to see the action, table, etc as well +as parameters passed through forms : + +for example + +Hello [% request.params.forename %] [% request.params.surname %] ! + +or + +Are you want to [% request.action %] in the [% request.table %] ? + +=head2 config + +You can access your maypole application configuration through the config variable : + + + +=head2 object and objects + +Objects are passed to the request using r->objects($arrayref) and are accessed in the templates +as an array called objects. + +[% FOR objects %] [% object %] [% END %] + +=head1 MAYPOLE MACROS AND FILTERS + +Maypole provides a collection of useful and powerful macros in the templates/factory/macros + and other templates. These can be used in any template with [% PROCESS templatename %]. + +=head2 link + +This creates an to a command in the Apache::MVC system by +catenating the base URL, table, command, and any arguments. + +=head2 maybe_link_view + +C takes something returned from the database - either +some ordinary data, or an object in a related class expanded by a +has-a relationship. If it is an object, it constructs a link to the view +command for that object. Otherwise, it just displays the data. + +=head2 pager + +This is an include template rather than a macro, and it controls the pager +display at the bottom (by default) of the factory list and search views/template. +It expects a C template argument which responds to the L interface. + +This macro is in the pager template and used as : + +[% PROCESS pager %] + +Maypole provides a pager for list and search actions, otherwise you can +provide a pager in the template using Template::Plugin::Pagination. + +[% USE pager = Pagination(objects, page.current, page.rows) %] +... +[% PROCESS pager %] + +The pager will use a the request action as the action in the url unless the +pager_action variable is set, which it will use instead if available. + +=head2 other macros =head1 AUTHOR @@ -41,3 +395,64 @@ Simon Cozens =cut +1; + +__DATA__ +Maypole error page + + +

Maypole application error

+ +

This application living at [%request.config.uri_base%], +[%request.config.application_name || "which is unnamed" %], has +produced an error. The adminstrator should be able to understand +this error message and fix the problem.

+ +

Some basic facts

+ +

The error was found in the [% err_type %] stage of processing +the path "[% request.path %]". The error text returned was: +

+
+    [% error %]
+
+ +

Request details

+ + + [% FOR attribute = ["model_class", "table", "template", "path", + "content_type", "document_encoding", "action", "args", "objects"] %] + + [% END %] + + + [% FOREACH param IN request.params %] + + [% END %] +
[% attribute %] [% + request.$attribute.list.join(" , ") %]
CGI Parameters
[% param.key %] [% param.value %]
+ +

Website / Template Paths

+ + + +
Base URI [% request.config.uri_base %]
Paths [% paths %]
+ +

Application configuration

+ + + + + +
Model [% request.config.model %]
View [% request.config.view %]
Classes [% request.config.classes.list.join(" , ") %]
Tables [% request.config.display_tables.list.join(" , ") %]
+ + +