|Bigtop Config||We just walked through this. It 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.|
|App Body||The heart of the matter. This pane allows you to define and edit your tables and controllers. More on this below.|
|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 apps 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.|
Click on the App Body link. What you see depends on how you started tentmaker. If you did what I did (tentmaker --new Contact address), you will something like this:
This shows that tentmaker has graciously created an address table and a corresponding Address controller. Thats what we asked for. Lets fix them so they will really work for an address book.
The main problem with tentmakers efforts is the column names. We told it the table name, so it used that to infer a variety of other names like the controller name. But we didnt give any hints about the columns. To fix that click edit or hide at the top of the address tables box. This will expand to show all the editable features of the table. To collapse the box, click edit or hide again.
Scroll down until you see the Field Quick Edit table. There will be four fields at the outset. (There is also a unique integer primary key called cleverly enough id, but it doesnt appear in the quick edit box. I rarely want to change it, and it is more complex than the other fields.) The last two default fields are created and modified dates. Those can all stay as they are. But we need to change ident and description to something more meaningful for our address book example. Lets use name and number.
Click into the name box for the ident field and change it to name. Then do the same to change description to number. Almost all changes in tentmaker take effect as soon as you click outside the input box. But, if it makes you feel better, you may click the Apply Quick Edit button.
As an optional extra, this would be a good time to create some additional fields. For Lisas address book we need street, city, state, zip, and country. It might also be nice to add cell_phone and email. Lisa also insists on the importance of tracking relationship. Feel free to put some or all of those in.
Note that you can make all the new fields in one shot by typing their names with separating spaces in the the Name(s) box under Create Field.
Their labels will be set to their names split on underscore with the first letter of each word capitalized.
Now scroll to the top of the page, enter a file name in the save as box and press the button. You should see a short message below the button which reads, Saved contact.bigtop presuming you called your contact.bigtop. If anything goes wrong with the saving, the error will be reported instead. At this point we are ready to build and start the app. This is a good time to press the Stop tentmaker button (presuming the saving went well).
To create the app, type (assuming you saved the file as contact.bigtop):
Change to the Contact directory. There you will see many familiar things that h2xs would build for you, with some additions and a few twists. For instance, Bigtop apps use Module::Build instead of MakeMaker.
We need to build the database. If you use sqlite (as I will for the examples in this document), it as simple as:
sqlite app.db < docs/schema.sqlite
This step is so simple, bigtop tries to do it for you. The message it prints will tell you whether or not it worked.
If you use PostgreSQL or MySQL, youll need to create the database first, then use your command line tool to populate it. Note that there are three schema files in the docs directory, pick the one that ends with your database name.
Finally, start the server:
./app.server [ -d Pg|mysql -u dbuser -p dbpassword ] [ port ]
By default app.server runs on port 8080 and uses the sqlite app.db database. To change the port, type the number directly on the command line (note that this is different from how you specify it for tentmaker):
To change the database engine and/or supply user and password information, either edit the script, or use the command line options as shown above in brackets. Using command line options is preferable. That way you can let bigtop keep recreating the app.server script as the data model and controller collection grows.
Upon start up, app.server will print a list of the URLs it can serve. Point your browser to them to play with the application.
Now that we have built the app, the inevitable change requests have arrived. While our user likes the basic data we are collecting, she doesnt always have enough of it to completely satisfy our form. Sometimes she has only a phone number or email address. Other times, her friends dont even have email. We need to make most of the fields optional.
Looking a little closer at the existing address book, I noticed that there are some random birth dates scribbled on the end papers. Perhaps we should add a birthday table to better track little nieces and nephews who might periodically receive gifts.
As with the --new flag, --add allows you to define columns for the new tables. Existing tables will receive new foreign keys as specified, but cant be modified in other ways from the command line. See Bigtop::ScriptHelp::Style::Kickstart for how to specify columns, their types and a few other things from the command line. Note that both tentmaker and bigtop share command line handling code, so all examples for bigtop work equally well for tentmaker.
Provide a port if you need it (with --port).
We could have said:
Now there are two main things we want to do: make most of the address table fields optional and pick better names for the generated bday table. Both of these could also be acheived by careful command line column specifications when we built the tables above, see Bigtop::ScriptHelp::Style::Kickstart.
Even if you do supply better names during initial table generation, this section still offers good advice should ever need to make changes to what you specified on the command line. Further, tentmaker allows you to edit far more than you can control from the command line.
Ask your browser for a full page refresh (hold shift and press the refresh button. Then, click on the App Body tab. Then click on edit for the address table. Go back to the Field Quick Edit box and begin checking the optional box for all the fields which should be optional. Or, as a better alternative in this case, click the optional box in title row of the quick edit table. This will make all the fields optional. Then, uncheck the required fields. In our case, that should only be name.
The other changes are reminscent of the field name changes and additions we did earlier. To make them, edit the new bday table. Then change the names of the ident and description fields to name and bdate. Make sure that bdates SQL type is date.
Now press Save As: (the name should already be correct). Then, at a command line in the build directory (the one with Build.PL) type:
Now we have a bit of work to do on the actual database. We have two choices: (1) destroy the original database or (2) alter the original database to match the new model. In this case, Ill opt for number 1 since we havent put any real data into the database yet. This is convenient, since Bigtop does not help with table alterations and my version of SQLite doesnt support them.
These are the steps for sqlite:
rm contact sqlite contact < docs/schema.sqlite
For PostgreSQL or MySQL it takes a bit more work:
remove the old contact database create a new contact database use the database command line tool to populate the database
Once the database is ready, you can restart the server:
Go to the address page and click on Add and see that most fields are now optional. Then go to the bday page and Add a birthday. Note the pull down list of families we could associate with this birthday person. Also note the Date Select link which pops up a calendar for easy date picking.
You can continue to develop and regenerate as the model changes. The only piece that is difficult to manage is the database once it is built.
See Bigtop::Docs::TentRef for more details on what tentmaker can control. For more command line options, including firing up tentmaker to build an app based on an existing PostgreSQL 8 database, see Bigtop::ScriptHelp::Style::Pg8Live. Try Bigtop::Docs::Cookbook for small problems and answers, Bigtop::Docs::Tutorial for a more complete example, with discussion, Bigtop::Docs::AutoKeywords for details on all bigtop keywords and Bigtop::Docs::Sytnax for an explanation of bigtop file structure. If you need to write your own backends, see Bigtop::Docs::Modules.
All of the doc modules are described briefly in Bigtop::Docs::TOC.
|perl v5.20.3||BIGTOP::DOCS::TENTTUT (3)||2016-04-03|