view release on metacpan or  search on metacpan

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

required.  It's up to you to make sure the syntax of your literal SQL code
is correct (including determining whether it needs a semi-colon).

If you want a trailing empty line, do this:

    literl SQL `CREATE INDEX name_ind ON some_table ( some_field );
    
    `;

All trailing whitespace is taken literally.  If you include any, no extra
new line will be added.

The order of SQL generation is the same as the order in your Bigtop file.
For example, since the index creation above must come after some_table
is defined, put the literal statement after some_table's block.

You may use literal SQL statements as a way to work around tentmaker's
inability to handle table level data statements.  Simply put your INSERT
statements into a literal SQL statement after the table's block.

=head2 How do I make a sequence?

Use a sequence block:

    sequence name_seq {}

This will generate:

    CREATE SEQUENCE name_seq;

in schema.*.  Note that blocks for sequences must currently be empty.
Eventually they should support min and max values, etc.

Most databases don't use sequences.  Of the databases supported by
bigtop, only Postgres has them.  Even for Postgres, we don't typically
use them any more.

=head1 CGI

=head2 What do CGI backends make?

CGI backends make a single CGI based dispatching script called app.cgi
directly in the build directory.  You will have to copy it to your
cgi-bin directory and make sure the copy there is executable.
If you use the with_server statement in the CGI backend block, they
will also make app.server.  You may run it as a stand alone web server,
which is especially useful during testing.

=head2 How do I specify configuration values?

This question does not represent best practice any more.  See the next
question which explains you to use Gantry::Conf.

Specify CGI configuration values with config blocks as you would for
mod_perl apps:

    app SomeApp {
        config {
            dbconn `dbi:Pg:dbname=appdb` => no_accessor;
            dbuser `someone`             => no_accessor;
            dbpass `not_tellin`          => no_accessor;
            page_size 15;
        }
    }

These become config hash members:

    my $cgi = Gantry::Engine::CGI->new(
        config => {
            dbconn => 'dbi:Pg:dbname=appdb',
            dbuser => 'someone',
            dbpass => 'not_tellin',
            page_size => 15,
        }
    );

Note: if you don't use Gantry::Conf, all config parameters for your
CGI script must be at the app level and they will only appear in the
config hash of the Gantry::Engine::CGI object.

=head2 How do I specify Gantry::Conf configuration values?

To use Gantry::Conf with CGI scripts, do two things.  First, use the Conf
Gantry backend, telling it the instance name of your app.  Second, set
gantry_conf in the CGI backend block:

    config {
        #...
        Conf Gantry { instacne `your_name`; }
        CGI  Gantry { gantry_conf 1; }
    }

The instance will be the name of the app's instance in your
/etc/gantry.conf.  If your master conf lives in a different file, use
a block like this instead:

    config {
        #...
        Conf Gantry {
            instance `your_name`;
            conffile `/etc/my_hidden_conf/master.conf`;
            gen_root 1;
        }
        CGI  Gantry {
            gantry_conf 1;
        }
    }

If you use a SiteLook backend, you probably want to set C<gen_root> in the Conf
Gantry backend, so it will manufacture a path to your wrapper and
other templates.

Many times config info varies depending on environment.  For instance,
in production you may need to connect to a different database.  Named
config blocks help with that.  Example:

    config {
        # all common config here
        rows_per_page 25;
    }
    config dev {
        dbconn `dbi:SQLite:dbname=app.db`;
    }
    config prod {
        dbconn `dbi:Pg:dbname=proddb;host=db.example.com`;
        dbuser someuser;
        dbpass `$ecr3t`;
    }

With the Conf Gantry backend, this will lead to a single config file with
three instances.  Each will begin with the instance prefix from the Conf
Gantry backend config block ('your_name' in the example above).  The unnamed