Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bigtop::Docs::TentRef(User Contributed Perl DocumentatBigtop::Docs::TentRef(3)

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.

       License Text
	   Defaults to the Perl	5.8.6 license text generated by	h2xs.  Use
	   this	to be meaner.  Some might even make it 'All rights reserved.'

       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.

Further	Reading
       See "Bigtop::Docs::Cookbook" for	small problems and answers,
       "Bigtop::Docs::Tutorial"	for a more complete example, with discussion,
       "Bigtop::Docs::AutoKeywords" for	a list of valid	keywords and their
       meanings, and "Bigtop::Docs::Sytnax" for	more details.  The above
       backend information is repeated in shorter form in
       "Bigtop::Docs::AutoBackends", but that document is more up to date.  If
       you need	to write your own backends, see	"Bigtop::Docs::Modules".

       All of the doc modules are described briefly in "Bigtop::Docs::TOC".

Author
       Phil Crow

perl v5.24.1			  2017-07-03	      Bigtop::Docs::TentRef(3)

Name | Intro | Starting Tentmaker | Above the Tabs | The Tabs in Detail | Bigtop Config | App Body | Backends | App Level Statements | App Config | Further Reading | Author

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bigtop::Docs::TentRef&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help