home     documentation     download

The form tag library is aliased as "spy" by default.

This library simplifies the generation and handling of forms by automating away repetitive tasks. Let's take a look at a simple example:

<spy:parent title="Form tag intro" />

<f:form>

<div class="simpleform">
  <f:text name="text1" label="Text input" default="change me" size=10 maxlength=30 />
  <f:text name="text2" label="Text input 2" value="change me" size=10 maxlength=30 />
</div>

<fieldset style="clear: both">
  <legend>One or two?  Or both?</legend>
  <f:checkboxlist class="radio" name="checkboxlist" data="[(1, 'one'), (2, 'two')]" />
</fieldset>

<div style="clear: both"><f:submit /></div>

</f:form>

This demonstrates several properties of Spyce form tags:

• Most tags take an optional label parameter; this is turned into an HTML label tag associated with the form element itself.
• If you View Source in your browser while running this sample, you can see that Spyce generates an id with the same value as the name parameter. (You can override this by explicitly specifying a different id parameter, if you need.)
• You can pass arbitrary parameters (such as the class parameter for <f:form>) to a Spyce form tag; parameters that do not have special meaning to Spyce will be passed through to the HTML output.
• Try changing the form values and submitting. By default, Spyce automatically remembers the user input for you, unless you give a tag a value parameter (or selected for collection elements), which has highest precedence. Note the different behavior of text1 and text2 in this example.
• Spyce provides some higher-level tags such as checkboxlist that result in multiple elements at the HTML level. For these tags, a "data" parameter is expected, which is always interpreted as a Python expression. Any iterable may be used as data, including generators and generator expressions for those with recent Python versions. Typically data would come from the database; here we're just using a literal list.

Active Handlers allow you to "attach" python functions to form submissions. They are described in the Active Handlers manual page.

Reference

First, some general rules:

The text displayed by a text-centric tag can come from one of three places. In order of decreasing priority, these are

• the value parameter
• the value submitted by the user is used
• the default parameter

For determining whether option, radio, and checkbox tags are checked or selected, a similar process is followed, with selected and checked parameters as the highest-priority source. The same parameters are used for select, radiolist, and checkboxlist tags; the only difference is for the collection tags, you can also specify multiple values in a Python list (or other iterable) in either the selected/checked or default parameters.

All tags except form and submit can be given names that tell Spyce how to treat their submitted values when passing to an Active Handler function. Adding ":int", ":float", ":bool", or ":list" is allowed. The first three tell Spyce what kind of Python value to convert the submission to; ":list" may be combined with these, or used separately, and tells Spyce to pass a list of all values submitted instead of a single one. (An example is given in the Active Handlers page.) Finally, here is the list of tags:

• <form [method=exprstring] [action=exprstring] ...> </form>
  Begin a new form. The method parameter defaults to 'POST'. The action parameter defaults to the current page.
• <submit [handler=exprstring] [value=exprstring] ... />
  Create a submit button. The value parameter is emitted as the button text. If handler is given, Spyce will call the function(s) it represents at the beginning of the page load after this button is clicked. (Multiple function names may be separated with commas.)

  If the handler is in a different [python] module, Spyce will automatically import it before use.

  A handler may take zero or more arguments. For the first non-self argument (if present), Spyce always passes a moduleFinder corresponding to the current spyceWrapper object; it is customary to call this argument "api." moduleFinder provides __getitem__ access to loaded modules; thus, "api.request" would be the current request module. If a requested module is not found, it is loaded.

  (You can also directly access the wrapper with api._wrapper, providing access to anything module authors have, but you will rarely if ever need to do this.)

  For other handler function parameters, Spyce will pass the values for the corresponding form input, or None if nothing was found in the GET or POST variables.

  See also the Active Handlers language section for a higher-level overview.

  Limitation: currently, Active Handlers require resubmitting to the same spyce page; of course, the handler method may perform an internal or external redirect.

• <hidden name=exprstring [value=exprstring] [default=exprstring] .../>
  Create a hidden form field. The name parameter is evaluated and emitted.
• <text name=exprstring [value=exprstring] [default=exprstring]  .../>
  Create a form text field. The name parameter is evaluated and emitted.
• <date name=exprstring [value=exprstring] [default=exprstring] [size=exprstring] [format=exprstring] .../>
  Create a form text field with a javascript date picker. Format defaults to MM/DD/YYYY. Maxlength is always len(format); this is also the default size, but size may be overridden for aesthetics.
• <password name=exprstring [value=exprstring] [default=exprstring] [size=exprstring] [maxlength=exprstring] .../>
  Create a form password field. Parameters are the same as for text fields, explained above.
• <textarea name=exprstring [value=exprstring] [rows=exprstring] [cols=exprstring] ...>default</textarea>
  Create a form textarea field. The name parameter is evaluated and emitted. The value optional parameter is evaluated. A default may be provided in the body of the tag. The value emitted is, in order of decreasing priority: local tag value, value in submitted request dictionary, local tag default. We search this list for the first non-None value. The rows and cols optional parameters are evaluated and emitted.
• <radio name=exprstring value=exprstring [checked] [default] .../>
  Create a form radio-box. The name and value parameters are evaluated and emitted. A checked and default flags affect whether this box is checked. The box is checked based on the following values, in decreasing order of priority: tag value, value in submitted request dictionary, tag default. We search this list for the first non-None value.
• <checkbox name=exprstring value=exprstring [checked] [default] .../>
  Create a form check-box. Parameters are the same as for radio fields, explained above.
• <select name=exprstring [selected=exprstring] [default=exprstring] [data=expr] ...>...</select>
  Create a form select block. The name parameter is evaluated and emitted. The optional data should be an iterable of (description, value) pairs.
• <option [text=exprstring] [value=exprstring] [selected] [default] .../>
  <option [value=exprstring] [selected] [default] ...>text</option>
  Create a form selection option. This tag must be nested within a select tag. The text optional parameter is evaluated and emitted in the body of the tag. It can also be provided in the body of the tag, as you might be used to seeing in HTML.
• <radiolist name=exprstring data=expr [checked=exprstring] [default=exprstring] ...>...</select>
  Create multiple radio buttons from data, which should be an iterable of (description, value) pairs.
• <checkboxlist name=exprstring data=expr [checked=exprstring] [default=exprstring] ...>...</select>
  Create multiple checkboxes from data, which should be an iterable of (description, value) pairs.

Here is an example of all of these tags in use:

<spy:parent title="Form tag example" />

<f:form>

<h2>Primitive controls</h2>

<div class="simpleform">
  <f:text name="mytext" label="Text" default="some text" size=10 maxlength=30 />

  <f:password name="mypass" label="Password" default="secret" />

  <f:textarea name="mytextarea" label="Textarea" default="rimon" rows=2 cols=50></f:textarea>

  <label for="mycheck">Checkbox</label><f:checkbox name=mycheck value=check1 />

  <label for="myradio1">Radio option 1</label><f:radio name=myradio value=option1 />
  <label for="myradio2">Radio option 2</label><f:radio name=myradio value=option2 />
</div>

<div style="clear: both">
  <h2 style="padding-top: 1em;">Compound controls</h2>
  [[-- a simple data source for the compound controls -- in practice
	     this would probably come from the database --]]
  [[ L = [('option %d' %i, str(i)) for i in range(5)] ]]

  <fieldset>
    <legend>Radiolist</legend>
    <f:radiolist class=radio name=radiolist data="L" default="3" />
  </fieldset>

  <fieldset>
    <legend>Checkboxlist</legend>
    <f:checkboxlist class=radio name=checkboxlist data="L" default="=['0', '1']" />
  </fieldset>

  <fieldset>
    <legend>Select</legend>
    <f:select name=myselect multiple size=5 data="L" default="2" />
  </fieldset>

  <fieldset>
    <legend>Date</legend>
    <f:date name=mydate />
  </fieldset>

  <h2 style="clear:both; padding-top: 1em;">Test it!</h2>
  <input type="submit" name="foo" value="Submit!">

</f:form>