view release on metacpan or  search on metacpan

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

=item foreign_display

This controls two things: the sort order of items from this table in its
controller's do_main method and the appearance of rows from this table when
other tables' controllers refer to them.  Suppose your table stores data
about people and you want foreign tables to summarize rows with the names
of the people.  You could use this foreign_display: C<%last, %first>.
Anything abutted to the left of a percent sign must be a column in the
table.  Anything else is taken literally.

=item refered_to_by

If other tables have foreign keys to this table, list them here.  Doing
so earns you a has_many relationship, if you use DBIx::Class as your ORM.
The has many name is optional and defaults to the name of the other table
with an 's' appended.

=item model_base_class

Most table models inherit from the default base class prefered by their
backend.  In the backend block, you can change that default for all the
tables in the app.  Sometimes one table needs a special parent.  This
statement allows you to pick such a parent on a table by table basis.

=item sequence

If you use sequences to generate your primary keys in PostgreSQL, fill in
the sequence name here.  You should get a good value by default, if you
created the sequence with tentmaker.

=back

Below the statements which apply to the whole table is the Field Quick Edit
table which was featured so heavily in the tutorial.  It looks like this:

=for html <img src='http://www.usegantry.org/images/tenttut/quickedit.png' alt='tentmaker quick edit field' />

    http://www.usegantry.org/images/tenttut/quickedit.png

There are seven columns in the quick edit table (you'll probably have to
use horizontal scrolling to see them all):

=over 4

=item Column Name

The name of the column in the database table, but also the name of the input
element when the field appears on an add/edit form.

Changing the name of the field will change all references to it in other
parts of the bigtop file.

=item SQL Type

The type of the column in SQL.  In the quick edit box you may only supply
one type phrase.  In the full edit table, you may include as many phrases
as you like.

If you change the type to date, tentmaker will do all the needed work to
make a popup calendar for easy date selection.

Note that int4 and varchar are magical.  Each database backend does something
reasonable to turn these into integers and strings respectively.  All other
types are taken literally and must be understood by the database you
actually use.

=item Label

What the user sees as a label for this field when it is on the screen.

=item Searchable

Check this box if the column should be searchable when it appears in a
main listing result table.  You must also request livesearch for the
controller's do_main method (see below).

=item Optional

Indicates that this field should be optional during add/edit form validation.

=item Constraint

Any valid Data::FormValidator constraint.  Usually this is a regex, but it
could be call to a sub which returns a regex.  See the POD for
Data::FormValidator for details.  Note that if you use the exported
subs provided by Data::FormValidator modules, you must add those modules
to the gen_uses or uses list of the controller which will display the
form for this table.

=item Default

A literal string (or number) to use as the form element's default value.  This
will be overriden by prior user input or a good value from the database row.

=back

All of the things which appear in the quick edit table appear in the more
detailed individual edit tables for each field.

If you need to edit other features of your fields, you need to choose
your field in the 'Edit Field' selection box immediately under the
Create Field(s) box.  As soon as you select a field from the pull down
list, it will open for editing like these overlapping images:

=for html <img src='http://www.usegantry.org/images/tenttut/fieldedit.png' alt='tentmaker field expanded for editing' />

    http://www.usegantry.org/images/tenttut/fieldedit.png

=for html <img src='http://www.usegantry.org/images/tenttut/fieldedit2.png' alt='tentmaker field expanded for editing' />

    http://www.usegantry.org/images/tenttut/fieldedit2.png

Here are the statements which apply to fields:

=over 4

=item not_for

Just as some tables confuse some backends, some fields do also.  If you need
to hide a troubling field from a backend or two, pick those backends here.

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

=item searchable

Check this box if your controller uses 'livesearch' in its do_main method
and you want this field to be one of the fields searched.

=item html_form_type

This is the input type of the field on html forms.  All statements
which begin html_form_ are passed directly to the template hash with
html_form_ stripped from the key prefix.

=item html_form_optional

By default, all fields on a form are required.  Check this box to make
this one optional.

=item html_form_constraint

A Data::FormValidator constraint.  See its docs for all the clever options.

=item html_form_default_value

What the form.tt template will put in the HTML input element if it can't
think of anything better to use.  Better values come from prior user
input (when the user submitted a page with errors) or from the database
row object (during edit only, obviously).

=item html_form_cols and html_form_rows

These apply only to html_form_type textarea.  They specify the cols and rows
attributes of the textarea element in HTML.

=item html_form_display_size

Applies only to html_form_type text.  Specifies the size attribute of the
input text element in HTML.  (The name is not size, because TT has a
virtual method by that name.)

=item html_form_options

Applies only to html_form_type select, and then only if the field is not
a foreign_key.  Allows you to specify the pull down labels and values
for the select menu.  Under 'Label,' enter what you want the user to see
in the pull down list.  Under 'Database Value,' enter what you want the
database to store.  Each time you add an option, a new pair of boxes
will appear.

=item html_form_foreign

Applies only to html_form_type display.  Indicates that this field is a
foreign key and the foreign_display should be used instead of the id.

=item html_form_onchange

If the field's type is select, this becomes the onchange callback for
the select input element.

=item date_select_text

Gantry provides a mechanism for user date entry via a popup calendar.
Enter the link text, which will trigger the popup, here.  If you set a
value here, several other changes will happen throughout the bigtop file,
so that the user can easily pick dates.  This will be set automatically
when any field's type becomes date.

=item html_form_raw_html

HTML to be added immediately before this field's HTML table row.  Generally
useful for hacking only.

=item non_essential

Some ORMs only fetch columns selectively, if yours does, this is how
you tell it to skip this column.

=back

Below the Edit Field table, you may add Data Statements:

=for html <img src='http://www.usegantry.org/images/tenttut/dataedit.png' alt='tentmaker controller expanded for editing' />

    http://www.usegantry.org/images/tenttut/dataedit.png

Each data statement will make one INSERT INTO statement in SQL output.
This allows you to create test data or a starting point for production data.
You may have as many data statements as you like.  The table will add columns
as needed.  You don't need to put something in every box.  It is usually
a bad idea to put anything in the id box.

Data statements considerably reduce the pain of discarding a dev database
due to model changes.

=item Controller

A code module for managing a table (usually showing rows from it on screen,
allowing updates to those rows).  You only need to make one of these if you
need one that doesn't control a table.  Otherwise, when you make the table,
tentmaker will make one for you.

A controller expanded for editing looks like this:

=for html <img src='http://www.usegantry.org/images/tenttut/controledit.png' alt='tentmaker controller expanded for editing' />

    http://www.usegantry.org/images/tenttut/controledit.png

As for tables, there are a number of statements which affect the whole
controller.  They are:

=over 4

=item no_gen

Check this box, if you no longer want to regenerate for this controller.
No new GEN files will be written for it.  Everything else here will be
ignored.

=item location

Specify an absolute location for this page from the document root of
the web server.