view release on metacpan or  search on metacpan

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

package Bigtop::Docs::TentTut;

=head1 Name

Bigtop::Docs::TentTut - tentmaker tutorial (best viewed in html)

=head1 Intro

If you don't know what Bigtop is, you might want to start by reading
C<Bigtop::Docs::About>.  It will give you a little background and some
advice on which other docs to read.

Bigtop is a language of simple structure, but with many keywords.  In an
effort to make it easier to use, I have written tentmaker, which is a guided
editor for building web apps.  It understands almost all the features of
bigtop syntax, allowing you to conentrate on what you want rather than
on proper bigtop spelling and punctuation.

This document is a tutorial to get you started.  It is not complete.
If you need more details consult C<Bigtop::Docs::TentRef> or
C<Bigtop::Docs::Syntax> (or even C<Bigtop::Keywords>).

Here, I will walk you through using tentmaker to generate a bigtop file.
Then, I will show how to use bigtop to turn that into a web app.  Finally,
I will return to expand the example in addtional iterations of feature
additions.  There are a couple of screen shots here.  If you don't see the
pictures in line, look for them in the docs directory of the Bigtop
distribution and/or on the web at http://www.usegantry.org/images/tenttut.

The example app I will build here is a contact database.  It will initially
store names and phone numbers.  In the second iteration I will expand it.
The ostensible purpose is to put my wife's address book on-line.

=head1 Starting tentmaker

Before using tentmaker, you must install Gantry (and the Template Toolkit).
Then you must install Bigtop, answering yes when asked if you want to
install tentmaker's templates (you must also provide a writeable directory
for them).

Once Bigtop installation is complete, you may start tentmaker
by typing:

    tentmaker

But it is better to use some command line arguments.  First, by default
tentmaker listens on port 8080.  If you want (or need) it to use
a different port supply it like so:

    tentmaker --port=8081

tentmaker is very quiet, but when it starts it will tell you something like:
C<HTTP::Server::Simple: You can connect to your server at
http://localhost:8081/>.  This is testament to my laziness as the line
reveals HTTP::Server::Simple as that actual server.  But you don't need
to think about tentmaker as a server (except to realize that it is listening
on a port, so be careful of who is allowed to talk to it, think firewall).
You need to know how to use it as an app, read on.

(Note that you may use -p instead of --port.)

If you already have a bigtop file, you can put that directly on the command
line, tentmaker will open it for editing:

    tentmaker existing.bigtop

Since you probably don't have a such a file handy (although there are some
in the examples directory of the bigtop distribution), you should start
more like this (adding the --port flag as needed):

    tentmaker --new Contact address

This is how I started tentmaker for the discussion that follows.

This will not only start tentmaker, it will generate a new bigtop file
for building the Contact application with a single table called address.
When you type this, tentmaker will start with the same message it showed
above.

The command line flags can be abbreviated with a single dash and their
first letter (e.g. --new is also -n).

You can even specify the columns and their types for tables like address:

    tentmaker --new Contact 'address(name,street,city,state,zip)'