TracFormsPlugin Tutorial

Here we'll look at some usage examples for the TracFormsPlugin. Let's work through the development of a shopping list and see how the features of the plugin can help.

Creating a simple shopping list

Open up a wiki page called Sandbox/GroceryList and edit:

{{{
#!TracForm
#! submit_label "Got 'em!"

|| '''What''' ||
|| [tf:milk] || Milk ||
|| [tf:eggs] || Eggs ||
|| [tf:bread] || Bread ||
|| [tf:beer] || Beer ||

}}}

Once you save, you'll see your form:

You can click on the checkboxes and when you're done, hit "Got 'em!". Reloading the page shows you the same list again.

A shopping list that remembers inventory

Let's update the shopping list to also remember when we bought the items last:

{{{
#!TracForm
#! submit_label "Got 'em!"
#! track_fields

|| || '''When''' || '''What''' ||
|| [tf:milk] || [tf.when:milk] || Milk ||
|| [tf:eggs] || [tf.when:eggs] || Eggs ||
|| [tf:bread] || [tf.when:bread] || Bread ||
|| [tf:beer] || [tf.when:beer] || Beer ||

}}}

Now you see some new information:

However, none of the dates are currently filled in correctly. This is because the default scenario for forms is not to track the fields, which is why we added the "#! track_fields" command. Now once you update the form you'll see something like this:

Remembering who got things last

Sometimes, it's helpful to remember also who got the last round of beer.

{{{
#!TracForm
#! submit_label "Got 'em!"
#! track_fields

|| || '''When''' || '''Who''' || '''What''' ||
|| [tf:milk] || [tf.when:milk] || [tf.who:milk] || Milk ||
|| [tf:eggs] || [tf.when:eggs] || [tf.who:eggs] || Eggs ||
|| [tf:bread] || [tf.when:bread] || [tf.who:bread] || Bread ||
|| [tf:beer] || [tf.when:beer] || [tf.who:beer] || Beer ||

}}}

Now, you'll see yourself doing all the work of course:

But if someone else does it last, that person will be remembered.

A shopping list for any occasion

Suppose that you need to buy the same stuff at two different weekends. It would be onerous to have to copy the shopping list each time. If you've installed the IncludeMacro, then it is straightforward to duplicate the shopping list.

Edit a wiki entry for Sandbox/Groceries-Today:

[[Include(Sandbox/GroceryList)]]

Do the exact same thing for Sandbox/Groceries-NextWeek.

Note that two different and independent lists are now available. This is because the default context for a TracForm is whatever page it is being viewed from, regardless of inclusion!

Adding and Removing Items

There is no penalty to add or remove items, although no memory will persist in the dropped values. Values that have the same name won't be affected. For example, back to Sandbox/GroceryList:

{{{
#!TracForm
#! submit_label "Got 'em!"
#! track_fields

|| || '''When''' || '''Who''' || '''What''' ||
|| [tf:milk] || [tf.when:milk] || [tf.who:milk] || Milk ||
|| [tf:eggs] || [tf.when:eggs] || [tf.who:eggs] || Eggs ||
|| [tf:bread] || [tf.when:bread] || [tf.who:bread] || Bread ||
|| [tf:beer] || [tf.when:beer] || [tf.who:beer] || Beer ||
|| [tf:pasta] || [tf.when:pasta] || [tf.who:pasta] || Pasta ||

}}}

Now has Pasta as an item to get, while the other values retain the same state.

Plus, as an added bonus note that the shopping list has changed in both Sandbox/Groceries-Today as well as Sandbox/Groceries-NextWeek.

Taking Notes

Another field type of interest is the [tf.input] operation. This allows for additional information that can be stored with the form. In the Sandbox/GroceryList, let's add a place for notes:

{{{
#!TracForm
#! submit_label "Got 'em!"
#! track_fields

|| || '''When''' || '''Who''' || '''What''' || '''Brand/Notes'''
|| [tf:milk] || [tf.when:milk] || [tf.who:milk] || Milk || [tf.input:milk_notes] ||
|| [tf:eggs] || [tf.when:eggs] || [tf.who:eggs] || Eggs || [tf.input:eggs_notes] ||
|| [tf:bread] || [tf.when:bread] || [tf.who:bread] || Bread || [tf.input:bread_notes] ||
|| [tf:beer] || [tf.when:beer] || [tf.who:beer] || Beer || [tf.input:beer_notes] ||
|| [tf:pasta] || [tf.when:pasta] || [tf.who:pasta] || Pasta || [tf.input:pasta_notes] ||

}}}

Now you can keep track what actual beer was purchased:

Getting the job done

Instead of planning with the wiki, you can also plan with tickets. Click "New Ticket" and make the description look like the following:

[[Include(Sandbox/GroceryList)]]

After submitting the ticket, you should see something like this:

That means that tickets can now include the checklists too, each having an independent state. This makes it much easier to generate recurring lists of activities that can be processed later.

---

There is another tutorial taking a different approach on TracForms with more examples.