view release on metacpan or  search on metacpan

lib/Maypole/Manual/StandardTemplates.pod  view on Meta::CPAN

Previously this was called delete, but obviously that clashes with a lot of stuff,
and that usage is now deprecated.


=head3 list

Listing, like viewing, is a matter of selecting objects for
presentation. This time, instead of a single object specified in the
URL, we want, by default, all the records in the table:

    sub list :Exported {
        my ($class, $r) = @_;
        $r->objects([ $self->retrieve_all ])
    }

However, things are slightly complicated by paging and ordering by
column; the default implementation also provides a C<Class::DBI::Pager>
object to the templates and uses that to retrieve the appropriate bit of
the data, as specified by the C<page> URL query parameter. See the
L<"pager"> template below.

=head3 search

Searching also uses paging, and creates a query from the C<POST>
parameters. It uses the F<list> template to display the objects once
they've been selected from the database.

=head2 The templates and macros

Once these actions have done their work, they hand a set of objects to
the templates; if you haven't specified your own custom template
globally or for a given class, you'll be using the factory specified
template. Let's take a look now at each of these and how they're put
together.

The beauty of the factory specified templates is that they make use of
the classes' metadata as supplied by the view class. Although you're
strongly encouraged to write your own templates, in which you don't need
to necessarily be as generic, the factory templates will always do the
right thing for any class without further modification, and as such are
useful examples of how to build Maypole templates.

=head3 Commonalities

There are certain common elements to a template, and these are extracted
out. For instance, all the templates call the F<header> template to
output a HTML header, and nearly all include the F<macros> template to
load up some common template functions. We'll look at these common
macros as we come across them.

=head3 F<view> 

template view

=head3 F<edit>

The F<edit> template is pretty much the same as F<view>, but it uses 
L<Maypole::Model::CDBI::AsForm>'s
C<to_field> method on each column of an object to return a C<HTML::Element>
object representing a form element to edit that property. These elements
are then rendered to HTML with C<as_HTML> or to XHTML with C<as_XML>.
It expects to see a list of
editing errors, if any, in the C<errors> template variable:

     FOR col = classmetadata.columns;
        NEXT IF col == "id";
        "<P>";
        "<B>"; classmetadata.colnames.$col; "</B>";
        ": ";
            item.to_field(col).as_HTML;
        "</P>";
        IF errors.$col;
            "<FONT COLOR=\"#ff0000\">"; errors.$col; "</FONT>";
        END;
    END;

=head3 F<list>

Browsing records and search results are both handled by the F<list> template.
The C<search> template argument is used to distinguish between the two cases:

    [% IF search %]
    <h2> Search results </h2>
    [% ELSE %]
    <h2> Listing of all [% classmetadata.plural %]</h2>
    [% END %]

=head3 F<pager>

The pager template controls the list of pages at the bottom (by default)
of the list and search views. It expects a C<pager> template argument
which responds to the L<Data::Page> interface.
There's a description of how it works in
L<the Template Toolkit section|Maypole::Manual::View/"The Template Toolkit">
of the View chapter.

=head3 F<macros>

The F<macros> template is included at the start of most other templates
and makes some generally-useful template macros available:

=over

=item C<link(table, command, additional, label)>

This makes an HTML link pointing to C</base/table/command/additional>
labelled by the text in I<label>. C<base> is the template variable that
contains the base URL of this application.

=item C<maybe_link_view(object)>

C<maybe_link_view> 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.

=item C<display_line(object)>

C<display_line> is used in the list template to display a row from the
database, by iterating over the columns and displaying the data for each
column. It misses out the C<id> column by default, and magically