<<TableOfContents(2)>>

/!\ 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 [[attachment: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: [[attachment: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`
 }}}
 1. 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:

{{attachment:RecipesDemo.png}}

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.
 1. 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`
 }}}
 {i} Note: If you are using MySQL, replace the '?' signs with '%s'
 1. Edit the `Recipes` page.
 1. Replace the form by the following slightly modified version:
 {{{
<<Form(Start)>>
|| Name       || <<Form(Text, Recipes2/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 ([[attachment: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:

{{attachment:RecipesComplexDemo.png}}


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