Name

Bigtop::Docs::TentRef - tentmaker reference (best viewed in html)

Intro

If you haven't used tentmaker before, you probably want to start with its tutorial: "Bigtop::Docs::TentTut". If you don't know what bigtop is, read "Bigtop::Docs::About".

Unlike the tutorial, this document assumes you have started looking around tentmaker, but are wondering what all it can do. Here we will walk through it in detail. Consider this an encyclopedia of tentmaker (and don't complain too loudly if it is verbose and pedantic).

After a short section on the various ways to start tentmaker, we will turn to the tabs it offers and what they allow you to control. There you will find many screen shots to aid the discussion. If you can't see them with your current pod viewer, look them up here: http://www.usegantry.org/images/tenttut or in the docs directory of the Bigtop distribution.

Starting Tentmaker

There three ways to start tentmaker:

--new (or -n)

If you want to start an app from scratch, you should use the --new flag. It will give the best defaults. Supply at least an app name:

    tentmaker -n AppName some tables here

But, for greater effect supply "STYLE INFO".

--add (or -a)

If you have a bigtop file, but want to augment it with additional tables, use the --add flag. Supply the bigtop file name and a list of tables or "STYLE INFO":

    tentmaker -a docs/appname.bigtop more tables

If you previously built your databse, you will have to manually alter (or replace) it.

normal mode

If you just need to work with the tables and controllers which are already in the bigtop file, start in normal mode:

    tentmaker docs/appname.bigtop

No matter how you start tentmaker, remember that it is an insecure socket server, so you need to be somewhat careful of what user runs it (never use root) and where the server sits in your network topography (behind a firewall is a good place).

STYLE INFO

When in new or add modes, you can specify more than just table names. You can also control their relationships and columns. Do this by picking a style. Currently there are two styles: Kickstart and Pg8Live. See "Bigtop::ScriptHelp::Style::Kickstart" and "Bigtop::ScriptHelp::Style::Pg8Live" for details. Hint: with them you get not only tables, but can control the columns in those tables including their column names, SQL types, foreign keys, and default values.

Above the Tabs

There are three useful widgets above tentmaker's tabs. Two go together: the Save As button and its file name input box. The other button stops tentmaker. Stopping it via this button is easier on everyone's sanity. If you kill it at the command line, your web browser's caching is bound to confuse you at some point. If you press the button, tentmaker's javascript will know that the server is down and warn you when you try to work on a stale page. After you restart tentmaker, request a full refresh (press shift while you click the refresh button) before beginning work.

The Tabs in Detail

In total, there are five tabs in tentmaker:

Bigtop Config: Controls only four things: the app name, what engine will serve it, what type of templates it will use, and what plugins you want. But it also provides a snapshot of the bigtop file (concealed by default).
App Body: The heart of the matter. Allows you to define your tables and controllers.
Backends: Controls what will be generated by bigtop. For example, do you want SQLite, MySQL, or Postges SQL syntax for building your database.
App Level Statements: Allows input of general information about the app, like the app's license, who wrote it, and how to contact them.
App Config: Allows input of configuration information about the app. This usually includes things like database name, user, and password, but can include any configuration your app needs.

The following sections walk through these in detail with pictures.

Bigtop Config

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

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

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:

    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.

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:

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

There are five statements which affect a whole table:

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.
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: "%last, %first". Anything abutted to the left of a percent sign must be a column in the table. Anything else is taken literally.
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.
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.
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.

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:

    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):

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.

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.

Label

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

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

Optional

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

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.

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.

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:

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

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

Here are the statements which apply to fields:

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.

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.

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.

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.

label

What the user sees when the field is on screen.

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.

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.

html_form_optional

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

html_form_constraint

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

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

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.

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

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.

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.

html_form_onchange

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

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.

html_form_raw_html

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

non_essential

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

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

    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.

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:

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

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

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.
location: Specify an absolute location for this page from the document root of the web server.
You must specify either a location or a rel_location for each controller.
rel_location: Specify a location for this page relative to the app's base location. You should control the app's base location in the base controller.
You must specify either a location or a rel_location for each controller. The base controller is an exception. It does not allow a rel_location, since there is nothing for it to be relative to. Further, it has a default location of /.
controls_table: The name of the table controlled by this controller.
gen_uses, stub_uses, uses: List any modules you want to use in your controller modules here. Modules in the gen_uses list are used only the GEN module. Modules in the stub_uses list are used only the stub module. Modules in the uses list are used in both, but keep in mind that stub modules are not regenerated. So, adding to these lists after generation will not add use statements to the stub.
text_description: What fills in the blank in questions like 'Delete this ____?'
page_link_label: Supply this, if you want the page to appear in site navigation. The value is the link the user will have to click to come to it.
autocrud_helper: Most of the time bigtop supplies the proper ORM helper for Gantry's AutoCRUD scheme without intervention (providing you check the For use with DBIx::Class on the Control Gantry backend as appropriate). If you want to use a different helper, supply it here. See "Gantry::Plugins::AutoCRUDHelper::DBIxClass" for an example of what to do.
skip_test: Check this if you don't want a default page hit test for this controller.

In addition to the statements that affect the whole controller, there are methods in it. Methods come in seven types, shown below. There are two statements they all understand: no_gen (take a guess) and extra_args. Any extra_args -- and you can have as many as you like -- are added to the argument list in the generated routine. Be sure to include full perl variables, including sigils:

    $id
    @variadic

If you include an array, put it at the end, remember that arg handling is greedy.

Here are the method types and what's unique about them:

stub

This makes an uninteresting sub, which can save some typing. It has no special statements.

main_listing

Makes a do_main style method which displays the rows from the controlled table something like this:

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

What you see when you expand a method for editing depends on its type. You should only see the statements suitable for methods of the selected type. (If you change the type of an existing method, you will have to request a page refresh for the available statements to change.) For main listings you'll see something like this:

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

order_by

A valid SQL ORDER BY clause for a select from this table alone.

rows

The number of rows to include on each main listing page.

paged_conf

An accessor which returns the number of rows to include on each main listing page. Frequently, this is a conf variable of the same name, but that is up to you.

cols

These are the fields you want to display to the user. Refer to them by their field name in the controlled table. List as many as you want. Extra boxes will appear when you fill up the ones intially shown.

col_labels

By default each column is labeled with its field's label. If you want something different just for the main listing, specify that here. Labels are used in the order given (blank boxes are ignored) until they run out. At that point labels are taken from field definitions again.

livesearch

If your template supports it, this will add a search box to the main listing result, so users can limit which rows appear.

header_options

The most common header option is add, allowing for new row creation. These appear at the far right of the main listing box. Normally, the Label of the option is mapped to the do_* method which handles the click. The mapping is "'do_' . lc label".

If you want the user to go somewhere else for the action, specify that in the optional Location box. Whatever you put in a Location box must be valid Perl code which will generate a URL (usually a relative one).

Use as many header_options as you like. Locations are always optional, using one for an option does not force you to use one for all options.

row_options

These are like header options, except that they apply to each row and that the default URL includes the row id. If you use Locations for these, you probably want to end the URL with $id.

title

This is the browser window title while the main listing is on display.

html_template

This overrides the default results.tt with a template of your choice. Note that generation may be somewhat less than useful if your template expects data incompatable with results.tt.

limit_by

Adds an optional parameter to the generated do_main for a foreign key. If the parameter is supplied, only rows which have that foreign key value will appear in the listing. The value for this statement must be a field name which is a foreign key (has a valid refers_to value).

The other method edit boxes look similar to the one shown for main listings, so I won't include more screen shots of them. But, I will cover their special keywords.

CRUD_form and AutoCRUD_form

all_fields_but: List the fields you don't want users to enter -- think of fields like id, created or modified dates, etc.
This is not compatible with the fields statement.
fields: List fields you want users to see here.
This is not compatible with the all_fields_but statement.
extra_keys: Form methods return hashes as expected by their templates. This allows you to pump extra keys into that hash. The value must be perl code. Quoting issues are inevitable with this field. Javascript and Perl must fight over the quote operators. To be safe use q or qq quoting operators.
form_name: Becomes the name attribute of the form HTML element. tentmaker will set this when a field's SQL type becomes date or you set date_select_text for it.
See 'How can I let my users pick dates easily?' in "Gantry::Docs::FAQ" for an explanation of all the pieces needed to make date popups work. Then be glad tentmaker already knows all that.

CRUD_form

The statements are exactly the same as for AutoCRUD_forms, they differ only internally so they can respond to the slightly different APIs of AutoCRUD and CRUD.

base_links

See 'Base Controller' below.

links

See 'Base Controller' below.

SOAP

In addition to no_gen, SOAP methods have two statements. Each can take multiple values. First is expects. These are the parameters callers will provide. Type defaults to xsd:string, where xsd is the name given to the http://www.w3.org/2001/XMLSchema namespace by Gantry's wsdl.tt template.

The second statement is returns. These are the things you are giving back to the caller.

For both input and output, simple types are preferred. If you need something complex, have your caller put it in a single XML string and base 64 encode it. Then you can decode it and use XML::Simple to recover it.

Note that SOAP methods are only supported by Gantry apps running under mod_perl 2.

Base Controller

This optional special controller allows you to control the base module of the app. The base module is the one the rest of the controllers inherit from. If you don't have one of these blocks, one will be provided with minimal functionality.

Without a Base Controller, the only controls you have over the base module are the app level location and uses statements. By having a genuine Base Controller, you can use most controller level statements. For instance, if you want a one table/one controller app, you can add statements like controls_table. In any case, you can include method blocks in the Base Controller as you would for any other Controller. For a one table app, this allows you to use a regular main_listing method as your do_main. You could also explicitly create the do_main nav method normally provided by default.

There are two method types primarily of interest in base controllers:

base_links: This makes a method usually called do_main. By default its template is main.tt, but the html_template statement overrides that. That template shows links to all of the other controllers which have page_link_labels. You probably want to use the title statement to specify the browser window title and the heading for the nav links.
links: This method is usually called site_links. It is provided by the base module so that other controllers (or more likely their templates) can retrieve the nav links. Every controller with a page_link_label appears in the nav links. This method type ignores all statements.

Literal

Literal text intended for one of the backends. These allow you to augment what bigtop knows how to generate. With careful use of them, you can usually continue to regenerate the app, without fear, even after it is in production (regenerating on a dev box and testing before release is A Good Idea).

It is usually better not to give the Literal a name. If you do give it a name, it must be one of those shown below (or it will be ignored).

Once the literal block is created, you may easily change the type from the pull down menu. See "Bigtop::Docs::AutoKeywords" or "Bigtop::Docs::Syntax" for more details of where these literals put their output.

The literal types are:

SQL: Output goes directly into all docs/schema.* files. Together with tables (and sequences) these appear in the output in the order of their appearance.
Location: Output goes into the httpd.conf base level location block.
PerlTop: Output goes into the <Perl> block in httpd.conf immediately below the shebang line.
PerlBlock: Output goes into the <Perl> block in httpd.conf after the use module statements.
HttpdConf: Output goes into the httpd.conf. Together with controller's location these appear in the output in the order of their appearance.
Conf: Output goes into app.config at the top level. This only applies when Conf::Gantry or Conf::General is in use.

Join Table

If you have a many-to-many relationship between two of your tables, express that by creating a Join Table (but keep in mind that the only Model which understands it is GantryDBIxClass). Usually, the join table name has the names of the other tables in it, but the choice is yours. Here's one:

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

There are two statements, the first one is required:

joins: List the tables which share the many-to-many relationship. This is a symmetric relationship, so the order makes no difference.
names: Normally, the names of the many-to-many relationships are formed by adding a trailing 's' to the table names. If you want to control the names, enter yours here. If you supply one, you must supply the other, even if you don't mind the original default. Keep the tables in the same order, to protect everyone's sanity.

Sequence: This is an SQL sequence. If your database understands them, and you like them, make them. But you never need to. If you do make a sequence, do it first. That will also make a table and a controller to go with it.

Backends

When I originally wrote this, there were already 10 backends and the number is likely still growing. Each backend represents a generator that bigtop uses to make some part of your app. For example, backends of type SQL make schema files ready to create your database tables, etc. via your database's command line tool. Backends of type Model build code for your Object-Relational Mapper -- ORM -- (like the classic Class::DBI or the newer DBIx::Class).

This pane overflows, so you will need to use the scroll bar to see all of your options. This figure shows the top of the pane:

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

There are four columns here:

Type: This describes the category of the backend in general. For instance, CGI backends build cgi scripts, SQL backends build SQL files to create tables, etc. Normally, you may only have one backend of each type selected. The SQL backends are an exception, you can use all of those together. This makes it easier to use sqlite during initial development, then migrate to Postgres or MySQL for deployment. You can even ship them with your app, allowing eventual users to pick their favorite.
Backend: This is the name of a specific backend within a type. For instance, CGI Gantry makes CGI scripts that work with the Gantry framework.
What Does It Make?: Gives a brief summary of what this backend builds.
Config Statements: A list of things you can change about the backend. All of them have No Gen, which means that the backend will be skipped (in which case it won't build anything). The other statements are specific to the backend. For instance, checking 'Build Server' for the CGI Gantry backend results in a stand alone server for use during testing.

To change selections, check or uncheck the box in the 'Backend' column. After you select a backend, fill in any statement values you need.

Note that if you deselect a backend, then reselect it, the statements from the right column are not re-read. You'll have to respecify them. Just click in and out of the input boxes. Fixing this is a TODO item.

Now, I will walk through all of the backend choices in alphabetical order.

CGI Gantry: Selected by default.
This will build a cgi script to drive our app. It can also make a stand alone server, which is highly useful for initial development. Here are the statements it understands:

No Gen

Check this if you built the app with this in mind, but no longer want to regenerate the scripts.

FastCGI

If you will deploy your CGI to a FastCGI environment instead of regular CGI, check this box. The generated code in app.cgi will be slightly different.

Use Gantry::Conf

If you use Gantry::Conf, check this box. Then remember to use the Conf Gantry backend (see below).

Build Server

Selected by default.

Check this if you want a stand alone server called app.server.

Server Port

If you want an app.server, but the default port (8080) is not good for you, specify an alternate port here. Users of app.server can still override that at the command line.

Generate Root Path

Selected by default.

This adds 'html' to the Template Toolkit root path, which is useful during app.server development. It does so by adding a root => 'html' entry to the config section of the hash passed to the CGI engine constructor in both app.server and app.cgi. When you need to move to a different directory -- say for deployment -- simply remove this statement from the CGI Gantry backend block in the config section and add a root parameter, with the proper path to the installed location of your templates, to the app level config block.

Note that this will be ignored if you are using Gantry::Conf. But the Conf Gantry backend has the same flag.

Database Flexibility

Selected by default.

This only applies to app.server (so you must check Build Server for it to have any effect). It adds command line handling to app.server, so the user can change database connection information at the command line. The POD of the generated app.server explains the flags.

Alternate Template

Allows you to supply your own template, which controls the generation.

Conf Gantry: Produces docs/AppName.gantry.conf suitable for immediate use in the /etc/gantry.d directory of most Gantry::Conf deployments. It uses all of the information from the app and controller level config blocks. The output is in Config::General format, which is wrapped in instance tags.

No Gen: Just as for CGI Gantry.
Conf Instance: The name of the conf instance for this app. Gantry::Conf uses this to locate the config for the app. It must be unique among instances on the box.
Conf File: By default Gantry::Conf expects to begin conf searching in /etc/gantry.conf. If your master conf file is somewhere else, supply the absolute path here.
Generate Root Path: Check this if you want the backend to manufacture a 'root' config variable giving it the value 'html.' This works great for initial development with the stand alone server. You put all your templates in the html subdirectory of the build directory, the backend tells TT where to find them. But, the approach breaks down for deployment. Then you need to uncheck this box, and add a proper root variable to the conf. Its value should be an absolute path to the TT templates.
Alternate Template: Just as for CGI Gantry.

Conf General: This backend is not used much any more. It was replaced by Conf Gantry. It writes the information from your app and controller level config blocks into docs/appname.conf in Config::General format, suitable for use with Gantry::Conf, if you are using ConfigureVia statements.

No Gen: Just as for CGI Gantry.
Generate Root Path: Just as for CGI Gantry, except that the root variable is put into the Config::General file at the top level.
Alternate Template: Just as for CGI Gantry.

Control Gantry: This builds the controller modules (think C in MVC) suitable for use with Gantry. There are two modules for every project, plus the others listed under the App Body tab. The app level stub module -- where you should put your app level custom code -- is the 'Application Name' from the Bigtop Config tab. The generated module begins with the prefix GEN and ends with the application name.

No Gen

Just as for CGI Gantry.

Full Use Statement

Somewhere, you must tell Gantry to load your engine and template engine. We prefer to do that in httpd.conf or in the CGI or stand alone server script. The alternative is to check this box. Then the engine information will be put into the base module of the application. We don't like that, because it informs the code of how it will be deployed. This would require a code change to move from one engine to another, which is inconvenient since we usually start development on the stand alone server and move to mod_perl for final testing and deployment. So, we prefer to control that via config information. If you want it in the code, go ahead, check this box.

Run Tests

By default, the backend makes t/10_run.t. It sets up a little test server which hits the default action (do_main) of each controller. You need an SQLite database called app.db in the build directory for the tests to work.

If the tests work for you, great. Add your own run tests in separate files so bigtop can keep t/10_run.t up to date.

If the tests don't work for you (e.g. you don't use SQLite), allow bigtop to make t/10_run.t initially, then uncheck this box and edit the generated tests.

For use with DBIx::Class

Selected by default.

DBIx::Class normally works in a unique manner among ORMs. Namely, it uses the schema and resultset concepts. To get these properly incorporated, you should check this box.

Alternate Template

Just as for CGI Gantry.

HttpdConf Gantry: This builds docs/httpd.conf which is suitable for use in an Include statement in your system's httpd.conf. We usually put that Include statement into a virtual host for the app.

Use Gantry::Conf: Just as for CGI Gantry.
Skip Config: Does not write any PerlSetVars into the generated output. This is useful if you use the old Conf General backend. In that case, you need to add some literals to set the GantryConfInstance and GantryConfFile. The later is only needed if your master conf file is not /etc/gantry.conf.
Full Use Statement: The flip side of the same statement in Control Gantry. We religiously choose the one here when we are using or planning to use mod_perl.
Generate Root Path: Just as for CGI Gantry. Remember that if you choose to Use Gantry::Conf, you should use its 'Generate Root Path' instead of the one here.
Alternate Template: Just as for CGI Gantry.

Init Std: This is really useful, but mostly when you first build an app. It is responsible for building the directories and default distribution files (like Changes and README). After initial generation, the only thing it does is update MANIFEST. If you want to do that manually, set no_gen for the backen.

No Gen

Just as for CGI Gantry, except that only one file is ever overwritten: MANIFEST. After initial generation, turn off MANIFEST updates by checking this box. Even if you do that, you can still obtain MANIFEST updates with:

    ./Build manifest

Both approaches use the same code to update the MANIFEST.

Alternate Template

Just as for CGI Gantry.

Model Gantry: Gantry has a native ORM scheme, select this backend if you want to use it. I wrote it to focus my frustrations with other ORM schemes. Then we moved to DBIx::Class, and I've been thinking of removing this native model scheme ever since.

No Gen: Just as for CGI Gantry.
Models Inherit From: Gantry models usually inherit from Gantry::Utils::Model::Regular, this lets you change their lineage.
Alternate Template: Just as for CGI Gantry.

Model GantryCDBI: This backend builds Class::DBI subclasses for each table.

No Gen: Just as for CGI Gantry.
Models Inherit From: CDBI models usually inherit from Gantry::Utils::CDBI, this lets you change their lineage.
Alternate Template: Just as for CGI Gantry.

Model GantryDBIxClass: Selected by default.
This backend builds DBIx::Class subclasses for each table and a pair of schema modules to load them. The schema modules are unforunately called App::Model and App::GENModel. Think of them as model controllers. The first one is for you to modify. The second one just lists the current tables and is regenerated with the app.

No Gen: Just as for CGI Gantry.
Models Inherit From: CDBI models usually inherit from Gantry::Utils::DBIxClass, this lets you change their lineage.
Alternate Template: Just as for CGI Gantry.

SiteLook GantryDefault: Selected by default.
This backend copies the sample_wrapper.tt from the Gantry distribution (or actually from its installed templates location) into html/genwrapper.tt. Feel free to completely replace it. If you change the file name, change it on the App Config tab and regenerate.

No Gen: Just as for CGI Gantry.
Gantry Wrapper Path: Normally, this copies the sample_wrapper.tt which is installed with your Gantry templates. To use a different default wrapper, give a full path to it here.

SQL MySQL: This produces docs/schema.mysql with the SQL statements you need to build your app's database with MySQL.

No Gen: Just as for CGI Gantry.
Alternate Template: Just as for CGI Gantry.

SQL Postgres: This produces docs/schema.postgres with the SQL statements you need to build your app's database with Postgres.

No Gen: Just as for CGI Gantry.
Alternate Template: Just as for CGI Gantry.

SQL SQLite: Selected by default.
This produces docs/schema.sqlite with the SQL statements you need to build your app's database with SQLite.

No Gen: Just as for CGI Gantry.
Alternate Template: Just as for CGI Gantry.

???: Other backends may have appeared since this was written.

App Level Statements

On this tab you will see a table of statements which describe the app that looks like this:

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

Note that almost all the statements (all except base location) will only work during initial generation. After that, the app's base stub module will not be regenerated. Luckily for you, there are good defaults if you skip this at the outset. Then you can merely change the generated result when you need to adjust the copyright to suit you PHB.

Here's a complete list of the statements you can control on this tab:

Base Location: This is the root HTTP location for the app. Note that you should not set this if you are using Gantry's stand alone server. It has no notion of document roots and will become confused if you use this.
Authors: List those who should receive credit or blame for the app here. Email addresses are optional.
Contact Us: A blurb about how to send in bug reports and/or join the project.
Copyright Holder: Defaults to the first author. Use this if something funny is going on, like your company is the owner of your code.
Modules Used: These will be used in the base module for the app (but remember that they will be ignored after your initial bigtop build).

App Config

This is where you configure your app. Here is the table you need to fill with your info:

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

There is a row for each config parameter. Each row has four columns:

Keyword: The name of the parameter.
Value: The value to use for it.
Skip Accessor?: If your framework already knows about the keyword, it probably provides a built-in accessor for it. For instance, Gantry already provides accessors for dbconn, dbuser, dbpass, root, template_wrapper, and several others. If your frameword provides the accessor, you should check the 'Skip Accessor?' box, so bigtop does not make a duplicate accessor for the keyword in your app's base module.
Delete Buttons: If you don't need one of the config params, simple click this button to remove it.

Under the current config parameters is a 'New Config Statement' button and an input box to type the name of a new parameter. For instance, you might want to add dbpass for the database password which corresponds to your dbuser.

This concludes our exhaustive tour of tentmaker. I hope you are more excited than exhausted.

'Consult Building and Starting' in "Bigtop::Docs::TentTut" for instructions on how to build your app once you have saved the above.

Author

Phil Crow