Philip Crow > Gantry-3.42 > Contact


Annotate this POD


New  9
Open  3
View/Report Bugs


Contact - the base module of this web app

#... More POD ... \end{verbatim}

To begin, it is a documentation placeholder. It explicitly uses the modules in the app -- at least the ones it knew about when it was written.

There is also a potentially useful init method provided as a comment. Uncomment it if you need to handle config info that Gantry doesn't know about. For instance, to handle an SMTP host for genuine emailing, you could use this init and accessor pair:

\begin{verbatim} sub init { my ( $self, $r ) = @_;

    # process SUPER's init code
    $self->SUPER::init( $r );

    $self->smtp_host_set( $self->fish_config( 'smtp_host' ) );

} # END init

sub smtp_host_set { my ( $self, $value ) = @_; $self->{__SMTP_HOST__} = $value; }

sub smtp_host { my ( $self ) = @_; return $self->{__SMTP_HOST__}; } \end{verbatim}

By calling \verb+fish_config+, we allow Gantry to use Gantry::Conf if the app is deployed with it, or a fall back scheme if it is not. Which fall back scheme will be determined by the engine. This is one important part of engine independence, allowing us to move easily between CGI and \verb+mod_perl+ for instance.

Again, since all other modules in the app (except the models) inherit from this package, it is a good place to locate common code.


The controller stub for the contact table looks like this:

\begin{verbatim} package Contact::Contact;

use strict;

use base 'Contact'; use Contact::GEN::Contact qw( do_main form );

use Gantry::Plugins::AutoCRUD qw( do_add do_edit do_delete form_name );

use Contact::Model::contact qw( $CONTACT );

#----------------------------------------------------------------- # $self->do_main( ) #----------------------------------------------------------------- # This method supplied by Contact::GEN::Contact

#----------------------------------------------------------------- # $self->form( $row ) #----------------------------------------------------------------- # This method supplied by Contact::GEN::Contact

#----------------------------------------------------------------- # get_model_name( ) #----------------------------------------------------------------- sub get_model_name { return $CONTACT; }

#----------------------------------------------------------------- # text_descr( ) #----------------------------------------------------------------- sub text_descr { return 'contact'; }


... POD ... \end{verbatim}

I call this a stub for the obvious reason that it starts empty, except for use statements. You might not ever have to put any code here (in which you could promote the next piece to its place). But, as with the base module for the whole app, we often need some special code for our pages. This is where it goes.

Otherwise, this is another documentation place holder. It is meant to be very easy for someone to open this file and see exactly what it does, even if there is almost no code. This is why it has so many comments and why it explicitly imports everything it uses.


The real code that manages the contact table is here:

\begin{verbatim} # NEVER EDIT this file. It was generated and will be overwritten without # notice upon regeneration of this application. You have been warned. package Contact::GEN::Contact;

use strict;

use base 'Exporter';

our @EXPORT = qw( do_main form );

use Contact::Model::contact qw( $CONTACT );

#----------------------------------------------------------------- # $self->do_main( ) #----------------------------------------------------------------- sub do_main { my ( $self ) = @_;

    $self->stash->view->template( '' );
    $self->stash->view->title( 'Contacts' );

    my $retval = {
        headings       => [
        header_options => [
                text => 'Add',
                link => $self->location() . "/add",

    my @rows = $CONTACT->get_listing();

    foreach my $row ( @rows ) {
        my $id = $row->id;
            @{ $retval->{rows} }, {
                data => [
                options => [
                        text => 'Edit',
                        link => $self->location() . "/edit/$id",
                        text => 'Delete',
                        link => $self->location() . "/delete/$id",

    $self->stash->view->data( $retval );
} # END do_main

#----------------------------------------------------------------- # $self->form( $row ) #----------------------------------------------------------------- sub form { my ( $self, $row ) = @_;

    my $selections = $CONTACT->get_form_selections();

    return {
        name       => '',
        row        => $row,
        fields     => [
                name => 'name',
                label => 'Name',
                type => 'text',
                is => 'varchar',
                name => 'phone',
                optional => 1,
                label => 'Phone',
                type => 'text',
                is => 'varchar',
                name => 'street',
                optional => 1,
                label => 'Street',
                type => 'text',
                is => 'varchar',
            # ... other similar hashes
} # END form


#... POD ... \end{verbatim}

The \verb+do_main+ method we created with tentmaker is shown in all its glory here. Its purpose is to draw data from the underlying table and feed it to the standard \ template. That template expects a hash reference with these keys: \verb+headings+, \verb+header_options+, and \verb+rows+. The headings are column labels, the header options usually just lists Add, which allows users to add rows to the table. Other options would likely be reports. The rows are the data for the table.

The rows are an array of hashes with \verb+data+ and \verb+options+ keys. The data is just an array of the values from the underlying table. The options are things that can be done to the row like Edit or Delete. Note that the urls of the options are specified (in terms of the location of the invocant).

When the data structure is ready, it is placed into the stash's view data.

The \verb+form+ method first asks the model for any foreign keys the user might be allowed to choose. They go unused here, but come in to play for the BDay controller. It requires users to choose a contact family for each birthday row.

The method builds a hash reference for use by the \ template. This allows a lot of keys, read its docs for details. Here we need these keys: row and fields. The row key contains a reference to the model object for the current row (if there is one). The fields key is an array of fields, in the order they will appear on the screen. Each array describes the field so the template knows how to gather input for it. All of the keys in the hash are taken directly from tentmaker, except that the ones beginning with \verb+html_form_+ have the prefix stripped -- so \verb+html_form_optional+ becomes simple \verb+optional+.



\section{Gantry and Its Server}

%\begin{figure} %\includegraphics[width=6in]{name} %\caption{Caption.} %\label{fig:name} %\end{figure}

syntax highlighting: