view release on metacpan or  search on metacpan

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

=head1 Bigtop Config

When you start tentmaker, this is the default tab.  It looks something
like this:

=for html <img src='http://www.usegantry.org/images/tenttut/tentopening.png' alt='tentmaker opening screen' />

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

This is where you give your app a name.  But, keep in mind that names are
very sticky once you assign them.  After you build an app, it is very
painful to change the name, even with bigtop helping.

Changing your engine or template engine is much easier.  Simply select the
new one from the pull down.  Regeneration should be enough to move you.
This is not always the case, since some choices make your code
dependent on an engine.  Some of those choices are in controller code
you wrote by hand, but others are in the backend statements (see below).

That's really all there is to see here (aside from seeing the raw
bigtop source).

=head1 App Body

The heart of tentmaker is the App Body tab.  If you have a single table
called address and a controller to go with it, should look like this:

=for html <img src='http://www.usegantry.org/images/tenttut/appbody.png' alt='tentmaker app body screen' />

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

The tutorial shows off some of the features on the tab.  Here we will
take a more systematic approach.

In addition to having tentmaker create or augment the bigtop file during
startup, you can create things within the app body tab.  You may make any
of these things in the app body: a table (which also makes its controller),
a controller, a literal, a join table, and a sequence (which also makes
its table and controller).

Once you have the App Body elements, tentmaker makes it easy to customize
them.  Here's how.

=over 4

=item Table

An SQL table, these are the heart of an app.  If you make one, tentmaker
will make a controller to go with it.  Once you have a table, click
'edit' next to the Table label.  It will expand to look something like this:

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

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

There are five statements which affect a whole table:

=over 4

=item not_for

Should you need to hide this table from your Model or SQL backend (or both),
select from the list.  Indicated backends will pass over this table
as if it were not in the bigtop file.

We use this occasionally when we want to build models for our auth tables
within the app, but actually point to an external database for the data.
Then, we select not_for SQL.

=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.

=item is

A list of items which will become phrases in the column definition in
your SQL.  Some of these are also used by AutoCRUD to sanitize the form
parameter hash prior to database changes.

You can use multiple entries for is.  That is why there are extra input boxes.
If you fill up the last box, a new one will appear as if by magic.

Normally, the first item must be a valid SQL type, where valid means anything
your database understands.  If your database is PostgreSQL and you are using
auto-incrementing without sequences, you can just put auto in the list,
the backend will assign SERIAL as the type for you.  Or, you can leave
it as int4, primary_key, and auto.  All backends handle that correctly
for an auto-incrementing integer primary key.

There are a few special bits of magic bigtop uses to keep all SQL engines
happy.  For instance, if you use int4 as the type, it will be converted by
the backend into something your database will like (it might even be
discarded, for example if you use Postgres without sequences and request
auto).

The word auto is also special.  It will instruct backends to produce SQL
so the column's value will be generated sequentially.  That will involve
actual SQL sequences only if you created a sequence for the table and
included a sequence statement.  Otherwise, the backend will tell the
databse to auto-increment without sequences.

If the column is part (or all) of the primary key, put primary_key in the list.
The Model backends also honor that.

If you use varchar, it will be converted into a suitable string even
if your database does not allow bare varchars.

Otherwise, you can put anything your database understands in a column
definition.

=item refers_to

Indicates that this column is a foreign key to another table.  The 'Table'
is the name of the other table.  The 'Column' is optional, but important.
If you omit it, the foreign key is not actually engraved into SQL,
rather the ORM treats it as a foreign key, but it is not genuine.  Adding
the name of the primary key for the other table (it must a solo primary key),
instructs the SQL backend to make a foreign key.  Note that not all databases
support foreign keys well or at all.

You must choose html_form_type select for these fields.  This will allow
users to select rows from the foreign table based on their foreign_display
output.

=item on_delete and on_update

If your database handles foreign keys and you supplied a refers_to column,
use this to fill in the dots in ON DELETE ... or ON UPDATE for this SQL column.
A frequent choice is CASCADE, but this is database specific.