From: Simon Cozens Date: Thu, 1 Apr 2004 16:19:26 +0000 (+0000) Subject: Most of the view documentation. X-Git-Tag: 2.10~259 X-Git-Url: https://git.decadent.org.uk/gitweb/?a=commitdiff_plain;h=f3b1f00e41ae64fabb974d3ac073298f936457be;p=maypole.git Most of the view documentation. git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@103 48953598-375a-da11-a14b-00016c27c3ee --- diff --git a/doc/View.pod b/doc/View.pod index a5bade0..7ce7af3 100644 --- a/doc/View.pod +++ b/doc/View.pod @@ -1,9 +1,339 @@ =head1 Maypole View Classes +In a large application, you will almost certainly want to customize the +layout and design of the output pages. This task may even be the purview +of a separate team of HTML designers rather than the programmers. Since +a typical programmer will try to avoid touching HTML as much as possible +and a typical designer will try to avoid touching Perl code, programmers +have evolved a system of templating to separate the concerns of +programming and designing. + +One of the core concepts in Maypole is the I, and this is +responsible for routing the data produced in the model class into the +templates produced by the designers. Of course, there are a great many +possible templating systems and styles, and so there can be a great many +possible Maypole view classes. Each view class will take the data from +the controller, locate a template to be processed, and hand the whole +lot to its preferred templating module, which will then do the hard work +of filling in the template and coming up with the output. + +You can choose whatever Maypole view class you want, but the default +view class is C, and it feeds its data and templates +to a module called the Template Toolkit. + =head2 The Template Toolkit -=head2 Maypole::View::TT +The Template Toolkit, written by Andy Wardley, is a very powerful and +generic templating system. It provides its own little formatting language +which supports loops, conditionals, hash and array dereferences and +method calls, macro processing and a plug-in system to connect it to +external Perl modules. There are several good introductions to the +Template Toolkit available: you should have one installed as +L; there's one at +L, and of course +there's the "Badger Book" - I, by Andy et al. + +We'll present a brief introduction here by deconstructing some of the +templates used by Maypole applications. For more deconstruction, see +L, which is an entire chapter dealing with the +factory supplied templates. + +Here's the template which is called for the front page of the standard +beer database application, C. + + [% INCLUDE header %] + +

The beer database

+ + + [% FOR table = config.display_tables %] + + + + [% END %] +
+ List by [%table %] +
+ +The first thing to note about this is that everything outside of the +Template Toolkit tags (C<[%> and C<%]>) is output verbatim. That is, +you're guaranteed to see + +

The beer database

+ + + +in the output somewhere. Inside the tags, magic happens. The first piece +of magic is the C<[% INCLUDE header %]> directive. This goes away and +finds a file called F
- don't worry about how it finds that yet, +we'll come to that later on - and processes the file's contents as +though they were right there in the template. Our F
file happens +not to contain any C<[% %]> tags, but if it did, they would be processed +in the same way as the ones in F. + +The next piece of magic is this line: + + [% FOR table = config.display_tables %] + +We're seeing a lot of things here at once. C is where we should +start looking. This is a template variable, which is what templates are +all about - templating means getting data from somewhere outside and +presenting it to the user in a useful way, and the C hash is a +prime example of data that we want to use. It's actually the hash of +configuration parameters for this Maypole application, and one of the +keys in that hash is C, the database tables that we're +allowed to play with. In the application, we probably said something +like + + BeerDB->config->{display_tables} = [qw[beer brewery pub style]]; + +This stores the four values - C, C, C and C