Bigtop Quick Reference

# This file is no longer maintained. See Bigtop::Docs::QuickRef

# Bigtop Quick Reference

This page is meant to show what's possible with the Bigtop web app description language. It's main feature is a table summarizing the syntax of the Bigtop language.

Each Bigtop file has the following basic structure:

        config {
        }
        app App::Name {
        }

Inside those blocks you can have simple statements and other blocks. Simple statements are a keyword followed by a number, a valid Perl identifier, or a backquoted string and terminated with a semi-colon. Sometimes the values can also be lists of single values separated by commas. In rarer cases, the values can themselves be key/value pairs. As in Perl, the keys and values are separated with the fat comma =>. See below for details.

## The Key Strangeness

One syntax feature that strikes people funny is that Bigtop uses backquotes around strings. The reason is simple. Bigtop never shells out, but it often needs to store Perl's favorite quotes in strings. Using backquotes makes it easy to embed either single or double quotes in its strings.

## A Bigger Example

Before going into the table of descriptions, it might help to see a bigger example:

    config {
        engine          MP13;
        template_engine TT;
        Init            Std      { no_gen 1; }
        SQL             Postgres {}
    }
    app Simple::Sample {
        authors               `Phil Crow`;
        set_vars              { dbconn `dbi:Pg:dbname=simple` => no_accessor; }
        sequence contacts_seq {}
        table contacts        {
            sequence contacts_seq;
            field id   { is int4, primary_key, assign_by_sequence; }
            field name {
                is              varchar;
                label          `Contact Person`;
                html_form_type text;
            }
        }
        controller Names {
            controls_table   names;
            uses             Gantry::Plugins::AutoCRUD;
            text_description `contact name`;
            method do_main is main_listing {
                title           `Contact Names`;
                cols            name;
                header_options  Add;
                row_options     Edit, Delete;
            }
            method _form is AutoCRUD_form {
                fields          name;
                extra_keys
                   legend     => `$self->>path_info =~ /edit/i ? 'Edit' : 'Add'`;
            }
        }
    }

## The Quick Reference Table

The following table tries to cover all the statements and blocks available, but keep in mind that backends can add simple statements of their own. So, the table may be incomplete.

config {...} |
engine | Your framework's engine module. Try MP13 for mod_perl 1.3.x or MP20 for mod_perl 2.0. CGI for cgi or FastCGI.
template_engine | Your framework's template engine. Try TT or Mason.
base_dir | In create mode, the directory under which the app will be built. (Defaults to the current directory.) Ignored, with a warning, outside of create mode.
app_dir | In create mode, the sub directory of base_dir where the app will be built. (Defaults in the manner of h2xs.) Ignored, with a warning, outside of create mode.
LEGAL BLOCKS | In the config section, blocks represent backend generators. Each generator has a type and a name. These translate directly to the name of the module which will do the generating. So,
     SQL Postgres {}
means use Bigtop::SQL::Postgres. Further, it means that the user of bigtop at the command line can request generation of postgres SQL by saying
    bigtop app.bigtop SQL
Finally, if the user of bigtop at the command line types:
    bigtop app.bigtop all
each generator will be called on to make its files in the order it is listed in the config section. All blocks accept no_gen. Use this statement when you no longer want the generator to do anything. But, don't omit the generator entirely. That will likely cause parse errors, since it won't be able to register it's keywords. Most blocks accept template. Use this statement to specify an alternate template for the backend. It will be used instead of the Inline::TT template hard coded in the backend. Templates define a set of BLOCKS. To see what blocks you must define and what parameters they have to work with, examine the templates hard coded in the backend(s) of interest to you. Example: SQL Postgres { template `my_postgres.tt`; }
Backend Type | Available Backends | Description
--- | --- | ---
Init | Std | Generates the things h2xs would if it used Build.PL
SQL | Postgres | Generates schema.sql in the docs directory using Postgres syntax.
HttpdConf | Gantry | Makes the conf needed for Gantry's default scheme (for mod_perl).
Control | Gantry | Makes the Controllers needed for use with Gantry.
Model | GantryCDBI | Makes the Models needed for use with Gantry.
SiteLook | GantryDefault | Makes the wrapper.tt Gantry uses for default site look. Expects a gantry_wrapper statement with a proper path to the sample_wrapper.tt provided with gantry.
app App::Name {...} |
authors | A comma separated list of the names of the authors for the AUTHORS section in generated POD. The first author is the default copyright holder.
copyright_holder | The exact text which fills in this following blank in generated POD Copyright (c) 200x, _____ Defaults to the first author.
email | The contact email address of the developers, used in generated POD.
license_text | The exact license text which follows the copyright claim in generated POD. Defaults to the language of h2xs for Perl 5.8.0, but your company might prefer `All rights reserved`.
location | The Apache location of the base module of the app (or its moral equivalent for cgi/fast cgi). Defaults to '/'.
LEGAL BLOCKS
set_vars {...} | Each statement has a PerlSetVar name, its value, and (optionally) => no_accessor. Usually the value must be backquoted. If you end the statement with => no_accessor, no accessor will be made for this set var by the controller (in which case your framework should catch it).
sequence name {} | Defines an sql sequence. There are no legal statements, leave the block empty.
table name {...} |
Defines an sql table. This might lead to generation of sql schema and/or models. Controllers also depend on tables (usually).
data | Each data statement becomes an INSERT INTO statement in the generated SQL. This allows you to populate your tables with test data or with data known in advance. Each data statement has a list of pairs where the key is a column name and the value is the value for the row.
foreign_display | What outsiders will see when they call foreign_display on a row object from this table. Like this: `%last_name, %first_name` The %field_names are replaced with values from the row object.
not_for | The value must be either SQL or Model or both in a comma separated list. It instructs those backends to skip this table.
sequence | The name of a previously defined sequence for use when auto generating primary keys.
LEGAL BLOCK: field name {...}
is | The SQL type. The keywords primary_key and assign_by_key are special. primary_key marks the field as a primary key in the generated SQL and Model. assign_by_key (a.k.a. auto) yields an auto-incrementing key based on a sequence. The table must have a valid sequence statement for this to work.
label | What the user sees as a label whenever this field appears on screen.
html_form_display_size | The width of the text input box for fields whose html_form_type is text.
html_form_cols | The number of columns for fields whose html_form_type is textarea.
html_form_options | A comma separated list of pairs whose keys are user visible labels for drop down choice lists. The values are the form values. The first item is the default. Example: html_form_options Yes => t, No => f; Required for fields of html_form_type select, unless the field refers_to another table.
html_form_optional | If true, the controller will not validate the field. (Not the same as non_essential.)
html_form_rows | The number of rows for fields whose html_form_type is textarea.
html_form_type | The html element type used when this field appears in an html form. Choose from: text, textarea, or select.
non_essential | If true, this field will not be included in the Model's essential field list. (Not the same as html_form_optional.)
not_for | The value may only be Model at the present time. It means that the model should completely ignore this field.
refers_to | Indicates that this field is a foriegn key. The value is the name of the table whose primary_key it stores.
controller name {...} |
controls_table | The name of the table this module will control.
location | The absolute path of the Apache Location for this controller or its moral equivalent.
page_link_label | Implies that this page should appear in the site navigation menu. This is the text to use in the menu (think of the grey links at the top of the page generated by sample_wrapper.tt that comes with Gantry).
rel_location | The path, relative to the app level location, of the Apache Location (or its moral equivalent) for this controller.
text_description | Used only by AutoCRUD. Fills in the blank in page titles Add ___, Edit ___, Delete ___, and the confirmation question Delete ____?
uses | A comma separated list of modules that the generated stub will use.
LEGAL BLOCK: method name is type Type must be one of these: main_listing, AutoCRUD_form, or stub
Legal statement for all method types:
extra_args | A comma separated list of extra parameters the method should accept. These will appear exactly as you type them in the comment above the sub and in the argument retrieval inside it. Remember to include the sigil. Example: extra_args `$id`, `$some_name`, `@greedy`;
Legal statements for main_listing methods:
cols | Comma separated list of columns for the main listing table, must match field names for the controlled table. The column label will be the label attribute from the field block in the table.
header_options | These appear as links in the title bar above the table. Supply a comma separate list of labels or label => value pairs. Options appear in the order you give here.
row_options | Like header_options, but appearing at the right end of each row in the listing. If you supply the url, use Perl code and remember to include $id. Options appear in the order you give here.
title | The browser window title.
Legal statements for AutoCRUD_form methods:
all_fields_but | A comma separated list of field names which should not appear on the form. All other fields in the controlled table will appear in the order they were defined in that table.
extra_keys | AutoCRUD_form methods return a hash. You can add keys to that hash with this statement. Give a comma separated list of pairs you want added to the hash. Backquote the values and make them EXACTLY like you want them to appear in the generated output, no alterations are made. Example: extra_keys legend => `$self->path_info =~ /edit/i ? 'Edit' : 'Add'`;
fields | A comma separated list of field names from the controlled table in the order the will appear on the form.
form_name | The name attribute of the html form element (note that form names are not allowed in xhtml 1.0 strict).