From c1f02d5a40b94afa2bc1aa54e44b10cde37fccbd Mon Sep 17 00:00:00 2001 From: Simon Cozens Date: Fri, 2 Apr 2004 12:22:47 +0000 Subject: [PATCH] Another section done. git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@110 48953598-375a-da11-a14b-00016c27c3ee --- doc/View.pod | 146 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 117 insertions(+), 29 deletions(-) diff --git a/doc/View.pod b/doc/View.pod index 7ce7af3..d2fda75 100644 --- a/doc/View.pod +++ b/doc/View.pod @@ -220,33 +220,11 @@ In our case, it'll be filled in like so: Where C will actually be the name of the current table, and C will be replaced by the appropriate URL for -this application. But where do these values, C and C, -come from, and what else can we do with them? +this application. -=head2 What Maypole provides to a template - -XXX - -=head2 Maypole::View::TT and other view classes +=head2 Locating Templates -Please note that these template variables, C, C, -C and its user-friendly alias, as well as the rest of themm are -a function of one particular view class, the default -C class. Other view classes may need to present an -entirely different set of template variables, since the default ones -might not make sense. The templates may look wildly different in other -view class implementations. But that's OK, because you couldn't -necessarily use the same templates with a different templating system -anyway. - -For instance, in really dumb templating languages which can't handle -dereferencing hashes or arrays - no wait, that's most of them - passing -in a hash reference like C won't help you since you can't -get at any of its elements. So you'll need to take a look at the -documentation for the appropriate view class to see what template -variables it provides. - -Another feture of C which may not be present in +Another feature of C which may not be present in alternate view class implementations - although they are strongly encouraged to provide it - is the way that templates are located. (Remember, I B say I'd tell you about that later.) Template Toolkit @@ -302,9 +280,119 @@ template. It should be obvious that you probably want to provide all of F, F, F, F and any other combination of classes and actions that you can think of. -Again, this only goes for C. If, for some perverse -reason, the Template Toolkit just isn't good enough for you, then you -can set your own view class while configuring your application: +=head2 What Maypole provides to a template + +C provides quite a variety of template variables to +the template. As these are the building blocks of your pages, it's worth +looking at precisely what variables are available. + +The most important variable is called C, and is a list of all +the objects that this page is going to deal with. For instance, +in the template F, C will contain the C +object for the 23rd item in the database, while F will +fill C will all the breweries; or at least, all the breweries +on the current page. + +This variable is so important that to help design templates with it, +C provides a helpful alias to it depending on +context. For instance, if you're writing your own F +template, the data in C is also available in a template +variable called C. If you're working on F, +though, it's available in C, since there's only one brewery to +be displayed. + +Additionally, you can get the base URL for the application from the +C template variable; this allows you to construct links, as we +saw earlier: + + Edit this brewery + +You can also get at the rest of the configuration for the site with the +C variable as we saw above, and the entire request object in +C, should you really need to poke at it. (I've only found this +useful when working with authentication modules which stash a current user +object in C.) + +To allow the construction of the "generic" templates which live in +F, Maypole also passes in a hash called C, +which contains all sorts of useful information about the class under +examination: + +=over 3 + +=item C + +This is the name of the table that is represented by the class. + +=item C + +This is the Perl's idea of the class; you don't need this unless you're +doing really tricky things. + +=item C + +This is a more human-readable version of the table name, that can be +used for display. + +=item C + +The same, but a correctly-formed plural. For instance, "breweries". + +=item C + +The list of columns for display; see the section "Customizing Generic +CRUD Applications" in L. + +=item C + +This is a hash mapping the database's name for a column to a more +human-readable name. Again, see "Customizing Generic CRUD Applications>. + +=item C + +This is a slightly trickier one. It is a hash mapping column names to +a C suitable for entering data into a new instance of +that class. That is, for the C table, C +should be a C object containing a drop-down list of +beer styles. This is explained in L. + +=item C + +This is the human-readable description provided by a class. + +=item C + +This is a list of accessors which can be called on an object to get +lists of other things that this object "has". For instance, on a +brewery, it would return C, since calling C would +give you a list of beers produced by the brewery. Note that this only +caters for accessors defining one-to-many relationships, not the +ordinary one-to-one relationships, such as C