Don't perform these steps in this wiki! The Form macro isn't available in this wiki anyway. So install the Form macro in a test wiki or download FormDemo.zip, unzip it and run moin.py. The demo wiki includes all the steps described in this tutorial and an even more complicated form including a filter and a sub form.

DataBase Creation

Before we can start defining a form we need a database. Download the folowing SQLite database, which contains two fine recipes: Recipes.db.

DataBase Connection

Now we have to define a connection to this database. This is done on a dictionary page.

1. Create a page Recipes/FormsDict in your wiki. The page should contain the following lines:

   = Database Connection =
    .type:: `sqlite`
    .file:: `attachment:Recipes.db`

2. Attach the database file downloaded in the previous step to this page.

The .type attribute specifies that we use a SQLite database and the .file attribute specifies the location of the database file (here an attachment).

Form Definition

Forms are defined by their attributes and design. Form attributes are specified also on a dictionary page.

Specifying the Form Attributes

Add the following lines to the Recipes/FormsDict page:

= Form =
 .select:: `select * from Recipes order by Name`

This specifies how to retrieve the form's data.

Specifying the Form's Design

Create a new page called Recipes which contains the following lines:

<<Form(Start)>>
|| Name       || <<Form(Text, Recipes/FormsDict..Name, 30)>> ||
|| Category   || <<Form(Text, .Category, 30)>>               ||
|| Servings   || <<Form(Text, .Servings, 4)>>                ||
|| Energy     || <<Form(Text, .Energy, 4)>> Cal.             ||
|| Time       || <<Form(Text, .Time, 4)>> minutes            ||
|| Difficulty || <<Form(Text, .Difficulty, 4)>>              ||
|| Procedure  || <<Form(Textarea, .Procedure, 50, 8)>>       ||
||<-2><<Form(Navigation)>>                                   ||
<<Form(End)>>

The page should display now (almost) the following form:

Wasn't that easy? I said almost, because you won't see the Save, Delete and New buttons. Why? Why can't you edit the data? Why can't you add new data and delete hamburger from your recipes database - as you surely hate hamburger ? In the next section we will resolve this.

Tune Up the Form a Little Bit

1. Edit the Recipes/FormsDict page.

2. Add the following lines:

    .update:: `update Recipes set Name=?, Category=?, Servings=?, Energy=?, Time=?, Difficulty=?, Procedure=? where Id=?`
    .update_parameters:: `.Name, .Category, .Servings, .Energy, .Time, .Difficulty, .Procedure, .Id`
   
    .insert:: `insert into Recipes(Name, Category, Servings, Energy, Time, Difficulty, Procedure) values(?, ?, ?, ?, ?, ?, ?)`
    .insert_parameters:: `.Name, .Category, .Servings, .Energy, .Time, .Difficulty, .Procedure`
   
    .delete:: `delete from Recipes where Id=?`
    .delete_parameters:: `.Id`

   Note: If you are using MySQL, replace the '?' signs with '%s'

3. Edit the Recipes page.

4. Replace the form by the following slightly modified version:

   <<Form(Start)>>
   || Name       || <<Form(Text, Recipes/FormsDict..Name, 30)>>    ||
   || Category   || <<Form(Text, .Category, 30)>>                   ||
   || Servings   || <<Form(Text, .Servings, 4)>>                    ||
   || Energy     || <<Form(Text, .Energy, 4)>> Cal.                 ||
   || Time       || <<Form(Text, .Time, 4)>> minutes                ||
   || Difficulty || <<Form(Text, .Difficulty, 4)>>                  ||
   || Procedure  || <<Form(Textarea, .Procedure, 50, 8)>>           ||
   ||<-2><<Form(Hidden, .Id)>><<Form(Buttons)>><<Form(Navigation)>> ||
   <<Form(End)>>

Now have a look at your Recipes page. You are ready to build a database including your own favorite recipes .

Tune Up the Form Even More

The attached wiki (FormDemo.zip) contains a more compelling example based on this database. It includes a form allowing to filter the recipes and to edit the ingredients which are displayed as a sub form. See the following snapshot:

A more detailed explanation of the Form macro you can find on the ../Reference page.