view release on metacpan or  search on metacpan

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

            html_form_constraint `qr{^\w\w\w-\d+$}`;
        }
        field status_id {
            is                 int4;
            label              Status;
            refers_to          status;
            html_form_type     select;
        }
        field paid {
            is                 date;
            label              `Paid On`;
            date_select_text   `Popup Calendar`;
            html_form_type     text;
            html_form_optional 1;
        }
        field customer_id {
            is                 int4;
            label              Customer;
            refers_to          customers;
            html_form_type     select;
        }
        field has_good_default {
            is                       varchar;
            label                    `Replace as Desired`;
            html_form_type           text;
            html_form_default_value `avalue`;
        }
        field notes {
            is                 text;
            label              `Notes to Customer`;
            html_form_type     textarea;
            html_form_optional 1;
            html_form_rows     4;
            html_form_cols     50;
        }
    }

Note that int4 will be converted into a reasonable integer type for
your database, even if it doesn't use that as a keyword.
    
The foreign_display statement controls how rows from this table
appear when other tables refer to them.  This is available through
the model's foreign_display method:

    my $show_to_user = $invoice_row_object->foreign_display();

Each field that might appear on the screen should have a label which
the user will see above or next to the values.  It becomes the column
label when the field appears in a table.  It appears next to the entry
field when the user is entering or updating it.

Including the refers_to statement implies that the field is a foreign
key.  Whether this generates SQL indicating that is up to the backend.
None of the current backends (Bigtop::SQL::Postgres, Bigtop::SQL::MySQL,
or Bigtop::SQL::SQLite) generate foreign key SQL.  But, using refers_to
always affects the model.  For instance, Bigtop::Model::DBIxClass generates
a belongs_to call for each field with a refers_to statement.  Other Model
backends do the analogous things.

The date_select_text is shown by Gantry templates as the text for
a popup calendar link.  See the discussion of the LineItem controller in
Bigtop::Docs::Tutorial for details.  You might also want to check 'How can I
let my users pick dates easily?' in Gantry::Docs::FAQ to see
what bigtop generates.

All of the statements which begin with html_form_ are passed through
to the template (with html_form_ stripped).  Consult your template
for details.  The Gantry template is form.tt.  Note that html_form_constraint
is actually used by Gantry plugins which rely on Gantry::Utils::CRUDHelp.
This includes at least Gantry::Plugins::AutoCRUD and Gantry::Plugins::CRUD.
These constraints are enforced by Data::FormValidator.

Use html_form_default_value if you want a default when the user and the
database row haven't provided one.

=head2 How can I include initial data in a table?

Sometimes it's useful to put some data into the database during creation.
Two types that spring to mind are test data and standard constants.
To include such data add data statements to the table block:

    table status_code {
        #...
        data name => `Begun`,  descr => `work in progress`;
        data name => `Billed`, descr => `invoice sent to customer`;
        data name => `Paid`,   descr => `payment received`;
    }

Notes: (1) you should not set the id if your table has a sequence or is
auto-incrementing the primary key (and it should one do or the other).
(2) remember to surround the values with backquotes if they
have any characters Perl wouldn't like in a variable name (it's always
safe to have backquotes around values, even if they aren't strictly needed,
think of them like the comma after the last item in a Perl list). (3) you
can use as many data statments as you like, each one makes an SQL statement:

    INSERT INTO status_code ( name, descr )
        VALUES ( 'begun', 'work in progress' );

Note that tentmaker cannot insert, update, or delete data statements.  But,
if you have them in your file, it will not harm them.  To get around this
tentmaker limitation, you need to create literal SQL blocks with INSERT
statements in them.  See the next question, for a discussion of literal
SQL blocks.

=head2 How do I put extra things into schema.*?

At any point in the app section, you may include a literal SQL statement:

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

There are a couple of things to notice here.  First, enclose all of your
literal content in backquotes.  It will only be modified in one way.  If
it doesn't end in whitespace, one new line will be added to it.  Otherwise,
you are on your own.

Second, there are two semi-colons here.  The one inside the backquotes is
for SQL, the one outside is for Bigtop.  The later semi-colon is always
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).