Changes between Initial Version and Version 1 of TracFormsPlugin/Tutorial


Ignore:
Timestamp:
Jun 17, 2008, 1:08:35 AM (16 years ago)
Author:
Rich Harkins
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracFormsPlugin/Tutorial

    v1 v1  
     1= TracFormsPlugin Tutorial =
     2
     3Here we'll look at some usage examples for the TracFormsPlugin.  Let's work through the development of a shopping list and see how various features of the TracFormsPlugin can help...
     4
     5== Creating a Simple Shopping List ==
     6
     7Open up a wiki page called Sandbox/GroceryList and edit.
     8
     9{{{
     10{{{
     11#!TracForm
     12#! submit_label "Got 'em!"
     13
     14|| '''What''' ||
     15|| [cl:milk] || Milk ||
     16|| [cl:eggs] || Eggs ||
     17|| [cl:bread] || Bread ||
     18|| [cl:beer] || Beer ||
     19
     20}}}
     21}}}
     22
     23Once you save, you'll see your form:
     24
     25''SCREENSHOT''
     26
     27You can click on the checkboxes and when you're done, hit "Got 'em!".  Reloading the page shows you the same list again.
     28
     29== A Shopping List That Remembers When You Got Stuff ==
     30
     31Let's update the shopping list to also remember when we bought the items last:
     32
     33{{{
     34{{{
     35#!TracForm
     36#! submit_label "Got 'em!"
     37#! track_fields
     38
     39|| || '''When''' || '''What''' ||
     40|| [cl:milk] || [cl.when:milk] || Milk ||
     41|| [cl:eggs] || [cl.when:eggs] || Eggs ||
     42|| [cl:bread] || [cl.when:bread] || Bread ||
     43|| [cl:beer] || [cl.when:beer] || Beer ||
     44
     45}}}
     46}}}
     47
     48Now you see some new information:
     49
     50''SCREENSHOT''
     51
     52However, none of the dates are currently filled in.  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:
     53
     54''SCREENSHOT''
     55
     56== Remembering who got things last ==
     57
     58Sometimes, it's helpful to remember also who got the last round of beer.  That way you can get something nice for that person... like more beer!
     59
     60{{{
     61{{{
     62#!TracForm
     63#! submit_label "Got 'em!"
     64#! track_fields
     65
     66|| || '''When''' || '''Who''' || '''What''' ||
     67|| [cl:milk] || [cl.when:milk] || [cl.who:milk] || Milk ||
     68|| [cl:eggs] || [cl.when:eggs] || [cl.who:eggs] || Eggs ||
     69|| [cl:bread] || [cl.when:bread] || [cl.who:bread] || Bread ||
     70|| [cl:beer] || [cl.when:beer] || [cl.who:beer] || Beer ||
     71
     72}}}
     73}}}
     74
     75Now, you'll see yourself doing all the work of course:
     76
     77''SCREENSHOT''
     78
     79But if someone else does it last, that person will be remembered.
     80
     81== A Shopping List for Many Occassion ==
     82
     83Suppose that you need to buy the same stuff at two different weekends.  It would be a drag to have to copy the shopping list each time.  If you've installed the IncludeMacro, then it's really a snap to duplicate the shopping list multiple times.
     84
     85Edit a wiki entry for Sandbox/Groceries-Today:
     86
     87{{{
     88[[Include(Sandbox/GroceryList)]]
     89}}}
     90
     91Do the exact same thing for Sandbox/Groceries-NextWeek.
     92
     93Note 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!
     94
     95== Adding and Removing Items ==
     96
     97There 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:
     98
     99{{{
     100{{{
     101#!TracForm
     102#! submit_label "Got 'em!"
     103#! track_fields
     104
     105|| || '''When''' || '''Who''' || '''What''' ||
     106|| [cl:milk] || [cl.when:milk] || [cl.who:milk] || Milk ||
     107|| [cl:eggs] || [cl.when:eggs] || [cl.who:eggs] || Eggs ||
     108|| [cl:bread] || [cl.when:bread] || [cl.who:bread] || Bread ||
     109|| [cl:beer] || [cl.when:beer] || [cl.who:beer] || Beer ||
     110|| [cl:pasta] || [cl.when:pasta] || [cl.who:pasta] || Pasta ||
     111
     112}}}
     113}}}
     114
     115Now has Pasta as an item to get, while the other values retain the same state.
     116
     117''SCREENSHOT''
     118
     119Plus, as an added bonus note that the shopping list has changed in both Sandbox/Groceries-Today as well as Sandbox/Groceries-NextWeek.
     120
     121== Taking Notes ==
     122
     123Another field type of interest is the [tf.input] operation.  This allows for general inputting of additional information that can be stored with the form.  In the Sandbox/GroceryList, let's add a place for notes:
     124
     125{{{
     126{{{
     127#!TracForm
     128#! submit_label "Got 'em!"
     129#! track_fields
     130
     131|| || '''When''' || '''Who''' || '''What''' || '''Brand/Notes'''
     132|| [cl:milk] || [cl.when:milk] || [cl.who:milk] || Milk || [tf.input:milk_notes] ||
     133|| [cl:eggs] || [cl.when:eggs] || [cl.who:eggs] || Eggs || [tf.input:eggs_notes] ||
     134|| [cl:bread] || [cl.when:bread] || [cl.who:bread] || Bread || [tf.input:bread_notes] ||
     135|| [cl:beer] || [cl.when:beer] || [cl.who:beer] || Beer || [tf.input:beer_notes] ||
     136|| [cl:pasta] || [cl.when:pasta] || [cl.who:pasta] || Pasta || [tf.input:pasta_notes] ||
     137
     138}}}
     139}}}
     140
     141Now you can keep track what actual beer was purchased:
     142
     143''SCREENSHOT''
     144
     145== Getting the job done ==
     146
     147Instead of planning with the wiki, you can also plan with tickets.  Click "New Ticket" and make the description look like the following:
     148
     149{{{
     150[[Include(Sandbox/GroceryList)]]
     151}}}
     152
     153After submitting the ticket, you should see something like this:
     154
     155''SCREENSHOT''
     156
     157That 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.