oreilly.comSafari Books Online.Conferences.


A Holiday Gantry Web Application
Pages: 1, 2

With coat on my lap I sat down once again, stopped app.server and typed:

    bigtop --add docs/grandkids.bigtop 'gift(name,occassion,year:int4)->child'

In the new gift table I asked for a gift 'name,' its 'occasion' and 'year,' the later an 'int4.'

To amend my db, I asked to see:

    cat docs/schema.sqlite
  name varchar,
  description varchar,
  created datetime,
  modified datetime,        
  child INTEGER,
  occasion varchar,
  year INTEGER

Which I fed in by click of my wonderful mouse:

    sqlite3 app.db
    sqlite> CREATE TABLE gift (
       ...> ...
    sqlite> .q

Then restarted the server to show off my change:


At that smiling moment our pizza appeared. So, I joined in the feast as we talked of grandkids. With the slices all gone and the box in the trash, the boss said, "It still needs reports, which can wait 'til next year. Head on home, with great thanks from me and my wife."

I fled with no need to twice be excused. The boss heard faintly as I flew from his sight, "Merry Christmas to all and too all a good afternoon."


Bigtop is a language for describing web applications. While you can follow the approach of the story above to add tables, you can do much more by editing the Bigtop file. You could do that with a text editor. That is not always easy enough, so we wrote tentmaker.

Tentmaker is a Bigtop source file editor delivered via a web browser like Firefox or Safari. With it you can safely edit the Bigtop file, without having to worry about typing the syntax correctly. Now, let me explain what Bigtop built for my little story above.

The code generated during the story is a complete CRUD only application for managing the family, child, and gift tables. The base URLs listed by app.server show lists of all the items in the tables. From those pages, you can add more items, as shown in the story. Each row listed also has edit and delete links.

If you want variations on basic CRUD, you can get them using tentmaker. This would include things like: removing the delete links, adjusting which columns appear in the main listings, controlling which fields appear on input forms, how those field are validated, etc.

For more sophisticated changes, you might have to write some code. The next section gives a quick tour of the generated files and shows where to put modifications.

Touring generated files

Gantry and Bigtop may be installed from CPAN. Once you install them (and their dependencies, of course) you can follow the example from the short story. If you do that, these are the files and subdirectories you will see in your build directory:

    Build.PL      MANIFEST.SKIP app.db        html
    Changes       README        app.server    lib
    MANIFEST      app.cgi       docs          t

Some of these are familiar to anyone who has built a distribution for CPAN: Changes, MANIFEST, MANIFEST.SKIP, and README. Build.PL is the Module::Build replacement for Makefile.PL. The t directory has the tests. The generated tests check compilation of each module in the application, POD and POD coverage, and perform a hit on the default page of each controller. We'll see the controllers shortly.

The html directory has a templates subdirectory which contains a Template Toolkit wrapper called It has basic styling, and is meant for development use. The rest of the templates you need for a CRUD application come with Gantry. We use them, as they ship, in our production environment, albeit with different stylesheets.

Both app.cgi and app.server are Perl scripts. In the story, the narrator used app.server for his development server. It is based on HTTP::Server::Simple, so it is persistent and fast, but not meant for production use. The app.cgi script could be used in a CGI environment, so long as you place the SQLite database carefully (where your web server can write to it and to its directory). Alternatively, you could change to another database, like PostgreSQL or MySQL, by changing the connection string in app.cgi. As we're about to see, Bigtop has already made the SQL statements for those two databases. Switching to mod_perl is not difficult, but is beyond our scope here.

In the docs directory there are four files. One of those is the Bigtop file, which describes the whole application in the Bigtop language. In the story, the narrator worked on this file exclusively through the Bigtop script. That is not usually enough. Normally, you need to edit it with tentmaker or your favorite text editor.

The other three files in the docs directory hold the SQL commands, which can be fed directly to the command line tools for MySQL, PostgreSQL, and SQLite. All of these are kept up to date by Bigtop as the model changes.

That brings us to the lib directory, where the code lives. Gantry generally operates in MVC fashion (though it doesn't force that fashion on you). So the code modules are of two types: models and controllers. Views are Template Toolkit templates, not code modules.

In addition to dividing models and controllers, Bigtop introduces another dichotomy: generated and stub. Stub modules are made once, either when the app is initially built or when you regenerate after adding to the Bigtop description. Generated modules are overwritten each time you regenerate the application, by running bigtop. This distinction gives you a safe place to put custom code, without having to worry about whether it will be overwritten. There is no way to get Bigtop to overwrite a stub, short of deleting or renaming it.

Now that you know what to expect, here is a listing of the two files and one directory in the lib directory:    GrandKids

Files which include GEN in their name or path are generated and will be regenerated (there are ways to turn off generation, but they usually make life more difficult in the end). So the stub for the base module of our app is, while the generated module is The rest of the modules are in the GrandKids subdirectory, as usual.

Let's descend into the GrandKids directory to see the more interesting code modules. In it there are again files and directories:   GEN Model

The modules here are stubs. There is not much useful code in them. Their main purpose is to provide a place for custom code. As a fundamental principle, stubs inherit from GEN modules whenever possible. This allows you to override GEN methods at will, simply by coding a replacement in the stub. You can use SUPER to call the GEN version, then modify its effects as needed. There is even a utility module to help you modify forms made by GEN modules.

The interesting code is in the GEN modules. Which are in the GEN directory. Listing its contents we see:

Even though the code in these generated modules is more interesting, and does the real work for CRUD, editing them is a mistake. Bigtop controls everything in them, so editing the Bigtop file and regenerating is the right choice.

The Model directory is less interesting, but not less useful. It contains stub and GEN modules for each table in the data model. These all descend from DBIx::Class.

That's what you get from a few minutes work with Bigtop at the command line.


Gantry and Bigtop have a home on the web: Go there to join in the fun of our mailing list, watch screen casts of example sessions like the one in the short story above, check out the latest sources, and much more.

There is now a Gantry book available from The code from the book is available from, which also has another link to the book on

Phil Crow

Return to

Sponsored by: