Package twisted :: Package web :: Module widgets :: Class Form

[show private | hide private]
[frames | no frames]

## Class Form

    Widget --+
             |
            Form

Known Subclasses:
  `CollectionForm`, `ConfigForm`, `ImmutableCollectionForm`, `ImmutableCollectionDeleteForm`, `PluginLoader`, `FunkyForm`, `NewIdentityForm`, `NewPerspectiveForm`, `RemoveIdentityForm`, `RemovePerspectiveForm`, `ChangePasswordForm`, `AuthForm`, `AccountCreationWidget`

I am a web form.

In order to use me, you probably want to set self.formFields (or override 'getFormFields') and override 'process'. In order to demonstrate how this is done, here is a small sample Form subclass:

     |  from twisted.web import widgets
     |  class HelloForm(widgets.Form):
     |      formFields = [
     |          ['string', 'Who to greet?', 'whoToGreet', 'World',
     |            'This is for choosing who to greet.'],
     |          ['menu', 'How to greet?', 'how', [('cheerfully', 'with a smile'),
     |                                            ('sullenly', 'without enthusiasm'),
     |                                            ('spontaneously', 'on the spur of the moment')]]
     |            'This is for choosing how to greet them.']
     |      def process(self, write, request, submit, whoToGreet, how):
     |          write('The web wakes up and %s says, "Hello, %s!"' % (how, whoToGreet))

If you load this widget, you will see that it displays a form with 2 inputs derived from data in formFields. Note the argument names to 'process': after 'write' and 'request', they are the same as the 3rd elements ('Input Name' parameters) of the formFields list.

Method Summary
| ``display`(self, request)` Display the form.
| ``format`(self, form, write, request)` I display an HTML FORM according to the result of self.getFormFields.
| ``formatError`(self, error)` Format an error message.
| ``getFormFields`(self, request, fieldSet)` I return a list of lists describing this form, or a Deferred.
| ``getFormID`(self)` Override me: I disambiguate between multiple forms of the same type.
| `getTitle(self, request)` (inherited from `Widget`)
| ``process`(self, write, request, submit, **kw)` Override me: I process a form.
| `shouldProcess(self, request)`
| ``tryAgain`(self, err, req)` Utility method for re-drawing the form with an error message.
| `_displayFormat(self, request, form)`
| `_displayProcess(self, request, form)`
| ``_doProcess`(self, form, write, request)` (internal) Prepare arguments for self.process.

Class Variable Summary
`str` | `actionURI`
`int` | `formAcceptExtraArgs`
`list` | `formFields`
`dict` | `formGen`
`dict` | `formParse`
`list` | `submitNames`

Method Details

### display(self, request)

Display the form.

### format(self, form, write, request)

I display an HTML FORM according to the result of self.getFormFields.

### formatError(self, error)

Format an error message.

By default, this will make the message appear in red, bold italics.

### getFormFields(self, request, fieldSet=None)

I return a list of lists describing this form, or a Deferred.

This information is used both to display the form and to process it. The list is in the following format:

     | [['Input Type',   'Display Name',   'Input Name',   'Input Value', 'Description'],
     |  ['Input Type 2', 'Display Name 2', 'Input Name 2', 'Input Value 2', 'Description 2']
     |  ...]

Valid values for 'Input Type' are:

- 'hidden': a hidden field that contains a string that the user won't change
- 'string': a short string
- 'int': an integer, e.g. 1, 0, 25 or -23
- 'float': a float, e.g. 1.0, 2, -3.45, or 28.4324231
- 'text': a longer text field, suitable for entering paragraphs
- 'menu': an HTML SELECT input, a list of choices
- 'multimenu': an HTML SELECT input allowing multiple choices
- 'checkgroup': a group of checkboxes
- 'radio': a group of radio buttons
- 'password': a 'string' field where the contents are not visible as the user types
- 'file': a file-upload form (EXPERIMENTAL)

'Display Name' is a descriptive string that will be used to identify the field to the user.

The 'Input Name' must be a legal Python identifier that describes both the value's name on the HTML form and the name of an argument to 'self.process()'.

The 'Input Value' is usually a string, but its value can depend on the 'Input Type'. 'int' it is an integer, 'menu' it is a list of pairs of strings, representing (value, name) pairs for the menu options. Input value for 'checkgroup' and 'radio' should be a list of ('inputName', 'Display Name', 'checked') triplets.

The 'Description' field is an (optional) string which describes the form item to the user.

If this result is statically determined for your Form subclass, you can assign it to FormSubclass.formFields; if you need to determine it dynamically, you can override this method.

Note: In many cases it is desirable to use user input for defaults in the form rather than those supplied by your calculations, which is what this method will do to self.formFields. If this is the case for you, but you still need to dynamically calculate some fields, pass your results back through this method by doing:

     |  def getFormFields(self, request):
     |      myFormFields = [self.myFieldCalculator()]
     |      return widgets.Form.getFormFields(self, request, myFormFields)

### getFormID(self)

Override me: I disambiguate between multiple forms of the same type.

In order to determine which form an HTTP POST request is for, you must have some unique identifier which distinguishes your form from other forms of the same class. An example of such a unique identifier would be: on a page with multiple FrobConf forms, each FrobConf form refers to a particular Frobnitz instance, which has a unique id(). The FrobConf form's getFormID would probably look like this:

     |  def getFormID(self):
     |      return str(id(self.frobnitz))

By default, this method will return None, since distinct Form instances may be identical as far as the application is concerned.

### process(self, write, request, submit, **kw)

Override me: I process a form.

I will only be called when the correct form input data to process this form has been received.

I take a variable number of arguments, beginning with 'write', 'request', and 'submit'. 'write' is a callable object that will append a string to the response, 'request' is a twisted.web.request.Request instance, and 'submit' is the name of the submit action taken.

The remainder of my arguments must be correctly named. They will each be named after one of the

### tryAgain(self, err, req)

Utility method for re-drawing the form with an error message.

This is handy in forms that process Deferred results. Normally you can just raise a FormInputError() and this will happen by default.

### _doProcess(self, form, write, request)

(internal) Prepare arguments for self.process.

Class Variable Details

### actionURI

  Type:
    `str`
  Value:

        ''

### formAcceptExtraArgs

  Type:
    `int`
  Value:

        0

### formFields

  Type:
    `list`
  Value:

        []

### formGen

  Type:
    `dict`
  Value:

        {'checkbox': <function htmlFor_checkbox at 0x8393b6c>,
         'checkgroup': <function htmlFor_checkgroup at 0x839b924>,
         'file': <function htmlFor_file at 0x83a5764>,
         'float': <function htmlFor_string at 0x83a579c>,
         'hidden': <function htmlFor_hidden at 0x838990c>,
         'int': <function htmlFor_string at 0x83a579c>,
         'menu': <function htmlFor_menu at 0x8393afc>,
         'multimenu': <function htmlFor_multimenu at 0x8393b34>,
        ...

### formParse

  Type:
    `dict`
  Value:

        {'int': <type 'int'>, 'float': <type 'float'>}

### submitNames

  Type:
    `list`
  Value:

        ['Submit']

Generated by Epydoc 1.1 on Thu May 8 13:19:10 2003 | http://epydoc.sf.net