view release on metacpan or  search on metacpan

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

Everything shown below is inside the app block, but we will update
things according to our billing app spec.  The name is the package
name of the base controller and is also a prefix for all other modules.

    config {
        dbconn `dbi:SQLite:dbname=app.db` => no_accessor;
        template_wrapper `genwrapper.tt` => no_accessor;
    }

You can include any config parameters you like in the app level config block.
The backends will move them into the proper place for app configuration.
For example, the CGI Gantry backend will put them into a hash in the
CGI script (and stand alone server).  The HttpdConf Gantry backend would
instead make them PerlSetVars.  Later we will see how to use Gantry::Conf,
then the Config General backend will put them into a flat file readable
by Config::General.

Normally, an accessor will be generated for each one in the base controller
module.  But, if you mark them no_accessor, as bigtop did above,
that accessor will not be generated.  Presumbably your framework will provide
accessors for them in that case, as Gantry does for the ones shown.

These config variables are of two types: database and app navigation.

Within Gantry, database connection is handled with dbconn, dbuser, and
dbpass.  dbconn is a full DBI connection string.  (SQLite doesn't use
dbuser or dbpass, so bigtop doesn't generate them.)  Note that if dbuser
or dbpass include any characters Perl wouldn't like in a variable name,
you must backquote the string, as in:

    dbpass `s!m0n` => no_accessor;

The other parameter is the name of the generated TT wrapper.  It lives
in the html directory.

=head3 Encoding the data model

After the environmental setup is described, there are two remaining
pieces: the data model and the controllers which manage it.

We'll start with the data model.

For this app there is one basic block that describe that model: table.

Table blocks take this form:

    table name { ... }

Inside the braces, you can include either statements or field blocks.  There
are three legal statements.  One of them was supplied for us: foreign_display.
It comes after the gernated fields.

    table my_companies {
        # ... generated fields
        foriegn_display `%ident`;

We want to change this from C<`%ident`> to C<`%name`>.

This controls what is displayed when other tables refer to this one.  In
this case, they will see the name of the company.  If there were people
in a table, foreign_display might be C<`%last, %first`>.  So, percent followed
by a column name will be replaced with the value of that column for each
row.  Note that the percent sign in the value requires us to surround
all foreign_display values with backquotes.

We'll use the data statement in the status table below.  The third statement
is useful only if you want to use Postgres sequences.

The rest of the customers table is a set of field blocks.  Like other blocks,
field blocks have this form:

    field name { ... }

Inside is a list of statements.  Some of those shown below
are specific to Gantry, in particular, many depend on its default
templates.

        field id {
            is int4, primary_key, auto;
        }

All fields must have an C<is> statement.  This fully specifies their
SQL properties.  Mostly, you want to list a valid SQL type (where valid
means your database understands it).  You can provide a single keyword,
a list of keywords, a backquoted string, or a comma separated combination
of those.  Back quoted strings are taken literally.

You may use the C<int4> type even if your database doesn't understand
it.  Then the backend for your database will convert it into a reasonable
integer type.  You may always choose to be explicit instead of relying
on that magic.

You should use the bare C<primary_key> as one attribute of the id column.
This not only generates 'PRIMARY KEY' in the SQL output, but
marks the column as primary for the ORM.

There is a special keyword you may use to fill in the primary key by
default: C<auto>.  The SQL for this request varies by database, but
all three supported databases work properly.

Note that primary_key and auto must be bare (not inside
quotes).  Remember: backquoted strings are taken literally.

Since ids rarely appear on screen, they usually only have an is statement.
Other fields are shown to the user and thus have other statements.
When bigtop makes a new app from a list of tables, it puts five columns in
each table: id, ident, description, created, and modified.  If you included
ASCII art table relationships, other fields will be generated to represent
them.  We talked about id above, and we don't need to change it.  The other
fields are too generic for our billing app.  So, we finally have a bit of
work to do (other than changing the foreign_display).

Here is what the generated ident field block looks like:

        field ident {
            is varchar;
            label Ident;
            html_form_type text;
        }

The description field looks just like it with the name changed.  The created
and modified fields are more like this: