view release on metacpan or  search on metacpan

lib/Gantry/Docs/Tutorial.pod  view on Meta::CPAN

        html_form_optional 1;
    }

Note that I put the label for this field in backquotes, since its name
contains a space.

We don't have to change the Address controller block, because the
only thing affected is the form.  tentmaker already specified that the form
should have all_fields_but id.  So, email will show up upon regeneration.

=head3 Birthday table

The most interesting change is adding birthdays.  In my mind, this leads
to a new table with this schema:

    CREATE SEQUENCE birth_seq;
    CREATE TABLE birth (
        id int4 PRIMARY KEY DEFAULT NEXTVAL( 'birth_seq' ),
        name varchar,
        family int4,
        birthday date
    );

To generate this sql, its model and controller we can add this
to our bigtop file (again, I'll show it a bit at a time with commentary):

    table birth {
        field id { is int4, primary_key, auto; }
        field name {
            is             varchar;
            label          Name;
            html_form_type text;
        }

This will be the name of one person in a nuclear family.

        field family {
            is                int4;
            label             Family;
            html_form_type    select;
            refers_to         address;
        }

This field becomes a foreign key pointing to the address table, since it
uses the C<refers_to> statement.  When the user enters a value for this
field, they must choose one family defined in the address table.

        field birthday {
            is                date;
            label             Birthday;
            html_form_type    date;
            date_select_text `Popup Calendar`;
        }
        foreign_display `%name`;
    }

I've chosen to store the actual date of birth (which leads to recording
women's ages, shame on me).  This is to show how date selection works
smoothly for your users.  There are three steps to this process.  The
first one is shown here: use the date_select_text statement.  Its value
becomes the link text the user clicks to popup the calendar selection
mini-window.  See, the controller below for the other two steps.

    controller Birth is AutoCRUD {
        controls_table   birth;
        rel_location     birthday;
        uses             Gantry::Plugins::Calendar;

Step two in easy dates is to use Gantry::Plugins::Calendar which provides
javascript code generation routines.

        text_description birthday;
        page_link_label  `Birth Day`;

This page will show up in site navigation with its page_link_label

        method do_main is main_listing {
            title            `Birth Day`;
            cols             name, family, birthday;
            header_options   Add;
            row_options      Edit, Delete;
        }

The main listing is just like the one for the address table, except for
the names of the displayed fields.

        method form is AutoCRUD_form {
            form_name        birthday_form;
            all_fields_but   id;
            extra_keys
                legend     => `$self->path_info =~ /edit/i ? 'Edit' : 'Add'`,
                javascript => `$self->calendar_month_js( 'birthday_form' )`;
        }
    }

Now the name of the form becomes important.  The calendar_month_js
method (mixed in by Gantry::Plugins::Calendar) generates the javascript
for the popup and its callback, which populates the date fields.
Note that we don't tell it which fields to handle.  It will work on
all fields that have date_select_text statements.

Once these changes are made, we can regenerate the application:

    bigtop docs/address.bigtop all

Execute this command while in the build directory (the one with the Changes
file in it).

For the app to work successfully, you will need to alter the existing
database so it has the new columns and birth day table.  Either throw out
the old database or alter it at your option.  Bigtop has data statements
which allow you to specify initial data for tables.  This makes discarding
a database less painful.

Again, I confess that I used tentmaker to get me started with the changes
above, then cleaned its output until it became the
L<Complete Bigtop Code Listing> below.

You can continue to edit the bigtop file with a text editor or tentmaker
and regenerate as the app matures.  We have regenerated production apps
months after deployment.

=head2 Complete Bigtop Code Listing

 config {
     engine CGI;
     template_engine TT;
     Init Std {  }
     SQL SQLite {  }
     SQL Postgres {  }
     SQL MySQL {  }
     CGI Gantry { gen_root 1; with_server 1; flex_db 1; }
     Control Gantry { dbix 1; }
     Model GantryDBIxClass {  }
     SiteLook GantryDefault {  }
 }
 app Apps::Address {
     config {
         dbconn `dbi:SQLite:dbname=app.db` => no_accessor;
         template_wrapper `genwrapper.tt` => no_accessor;
     }
     controller is base_controller {
         method do_main is base_links {
         }
         method site_links is links {
         }
     }
     table address {
         field id {
             is int4, primary_key, auto;
         }
         field name {
             is varchar;
             label Name;
             html_form_type text;
             html_form_optional 0;

lib/Gantry/Docs/Tutorial.pod  view on Meta::CPAN

             html_form_optional 1;
         }
     }
     controller Address is AutoCRUD {
         controls_table address;
         rel_location address;
         text_description address;
         page_link_label Address;
         method do_main is main_listing {
             cols name, street;
             header_options Add;
             row_options Edit, Delete;
             title Address;
         }
         method form is AutoCRUD_form {
             all_fields_but id, created, modified;
             extra_keys
                 legend => `$self->path_info =~ /edit/i ? 'Edit' : 'Add'`;
         }
     }
     table birth {
         field id {
             is int4, primary_key, auto;
         }
         field name {
             is varchar;
             label Name;
             html_form_type text;
         }
         field family {
             is int4;
             label Family;
             refers_to address;
             html_form_type select;
         }
         field birthday {
             is date;
             label Birthday;
             html_form_type text;
             date_select_text `Popup Calendar`;
         }
         foreign_display `%name`;
     }
     controller Birth is AutoCRUD {
         controls_table   birth;
         rel_location     birthday;
         uses             Gantry::Plugins::Calendar;
         text_description birthdays;
         page_link_label `Birth Days`;
         method do_main is main_listing {
             title `Birth Day`;
             cols name, family, birthday;
             header_options Add;
             row_options Edit, Delete;
         }
         method form is AutoCRUD_form {
             form_name birthday_form;
             all_fields_but id;
             extra_keys
                 legend => `$self->path_info =~ /edit/i ? 'Edit' : 'Add'`,
                 javascript => `$self->calendar_month_js( 'birthday_form' )`;
         }
     }
 }

=head1 Summary

In this document we have seen how a simple Gantry app can be written
and deployed.  While building a simple app with bigtop can take just
a few minutes, interesting parts can be fleshed out as needed.  Our
goal is to provide a framework that automates the 50-80% of most apps
which is repetitive, allowing us to focus our time on the more interesting
bits that vary from app to app.

If you want to see a more realistic app, see Bigtop::Docs::Tutorial
which builds a basic freelancer's billing app.

There are other documents you might also want to read.

=over 4

=item Gantry::Docs::FAQ

categorized questions and answers explaining how to do common tasks

=item Gantry::Docs::About

marketing document listing the features of Gantry and telling its history

=back

The modules have their own docs which is where would be gantry developers
should look for more information.

=head1 Author

Phil Crow <philcrow2000@yahoo.com>

=head1 Copyright and License

Copyright (c) 2006-7, Phil Crow.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.

=cut