pyxmpp.jabber.dataforms.Form

Package pyxmpp :: Package jabber :: Module dataforms :: Class Form |
[show private | hide private]
[frames | no frames]

## Type Form

             object --+
                      |
    StanzaPayloadObject --+
                          |
                         Form

A JEP-0004 compliant data form.

Additionally to the direct access to the contained fields via the `fields` attribute, `Form` object provides an iterator and mapping interface for field access. E.g.:

    for field in form:
        ...

or:

    field = form['field_name']

Method Summary
| ``__init__`(self, xmlnode_or_type, title, instructions, fields, reported_fields, items)` Initialize a `Form` object.
| `__contains__(self, name)`
| `__getitem__(self, name_or_index)`
| `__iter__(self)`
`Field` | ``add_field`(self, name, values, field_type, label, options, required, desc, value)` Add a field to the form.
`Item` | ``add_item`(self, fields)` Add and item to the form.
| ``complete_xml_element`(self, xmlnode, doc)` Complete the XML node with `self` content.
`Form` | ``copy`(self)` Get a deep copy of `self`.
`Form` | ``make_submit`(self, keep_types)` Make a "submit" form using data in `self`.
| ``__from_xml`(self, xmlnode)` Initialize a `Form` object from an XML element.
| ``__get_reported`(self, xmlnode)` Parse the <reported/> element of the form.
Inherited from StanzaPayloadObject
`libxml2.xmlNode` or `libxml2.xmlDoc` | ``as_xml`(self, parent, doc)` Get the XML representation of `self`.
Inherited from object
| ``__delattr__`(...)` x.__delattr__('name') <==> del x.name
| ``__getattribute__`(...)` x.__getattribute__('name') <==> x.name
| ``__hash__`(x)` x.__hash__() <==> hash(x)
| ``__new__`(T, S, ...)` T.__new__(S, ...) -> a new object with type S, a subtype of T
| ``__reduce__`(...)` helper for pickle
| ``__reduce_ex__`(...)` helper for pickle
| ``__repr__`(x)` x.__repr__() <==> repr(x)
| ``__setattr__`(...)` x.__setattr__('name', value) <==> x.name = value
| ``__str__`(x)` x.__str__() <==> str(x)

Instance Variable Summary
`list` of `Field` | `fields`: the fields in the form.
`unicode` | `instructions`: instructions for a form user.
`list` of `Item` | `items`: items in a multi-item data form.
`list` of `Field` | `reported_fields`: list of fields returned in a multi-item data form.
`unicode` | `title`: form title.
| `type`: form type ("form", "submit", "cancel" or "result").

Class Variable Summary
`tuple` | `allowed_types` = `('form', 'submit', 'cancel', 'result')`
`unicode` | `xml_element_name`: name for the XML element provided by the class.
`unicode` | `xml_element_namespace`: namespace URI for the XML element provided by the class.

Method Details

### __init__(self, xmlnode_or_type='form', title=None, instructions=None, fields=None, reported_fields=None, items=None) (Constructor) Initialize a `Form` object. Parameters: `xmlnode_or_type` - XML element to parse or a form title. (type=`libxml2.xmlNode` or `str`) `title` - form title. (type=`unicode`) `instructions` - instructions for the form. (type=`unicode`) `fields` - form fields. (type=`list` of `Field`) `reported_fields` - fields reported in multi-item data. (type=`list` of `Field`) `items` - items of multi-item data. (type=`list` of `Item`) Overrides: `__builtin__.object.__init__`

### add_field(self, name=None, values=None, field_type=None, label=None, options=None, required=False, desc=None, value=None) Add a field to the form. Parameters: `name` - field name. (type=`unicode`) `values` - raw field values. Not to be used together with `value`. (type=`list` of `unicode`) `field_type` - field type. (type=`str`) `label` - field label. (type=`unicode`) `options` - optional values for the field. (type=`list` of `Option`) `required` - `True` if the field is required. (type=`bool`) `desc` - natural-language description of the field. (type=`unicode`) `value` - field value or values in a field_type-specific type. May be used only if `values` parameter is not provided. (type=`bool` for "boolean" field, `JID` for "jid-single", `list` of `JID` for "jid-multi", `list` of `unicode` for "list-multi" and "text-multi" and `unicode` for other field types.) Returns: the field added. (type=`Field`)

### add_item(self, fields=None) Add and item to the form. Parameters: `fields` - fields of the item (they may be added later). (type=`list` of `Field`) Returns: the item added. (type=`Item`)

### complete_xml_element(self, xmlnode, doc) Complete the XML node with `self` content. Parameters: `xmlnode` - XML node with the element being built. It has already right name and namespace, but no attributes or content. (type=`libxml2.xmlNode`) `doc` - document to which the element belongs. (type=`libxml2.xmlDoc`) Overrides: `pyxmpp.objects.StanzaPayloadObject.complete_xml_element`

### copy(self) Get a deep copy of `self`. Returns: a deep copy of `self`. (type=`Form`)

### make_submit(self, keep_types=False) Make a "submit" form using data in `self`. Remove uneeded information from the form. The information removed includes: title, instructions, field labels, fixed fields etc. Parameters: `keep_types` - when `True` field type information will be included in the result form. That is usually not needed. (type=`bool`) Returns: the form created. (type=`Form`) Raises: `ValueError` - when any required field has no value.

### __from_xml(self, xmlnode) Initialize a `Form` object from an XML element. Parameters: `xmlnode` - the XML element. (type=`libxml2.xmlNode`)

### __get_reported(self, xmlnode) Parse the <reported/> element of the form. Parameters: `xmlnode` - the element to parse. (type=`libxml2.xmlNode`)

Instance Variable Details

### fields the fields in the form. Type: `list` of `Field`

### instructions instructions for a form user. Type: `unicode`

### items items in a multi-item data form. Type: `list` of `Item`

### reported_fields list of fields returned in a multi-item data form. Type: `list` of `Field`

### title form title. Type: `unicode`

### type form type ("form", "submit", "cancel" or "result").

Class Variable Details

    ### allowed_types Type: `tuple` Value:
        ('form', 'submit', 'cancel', 'result')

    ### xml_element_name name for the XML element provided by the class. Type: `unicode` Value:
        'x'

    ### xml_element_namespace namespace URI for the XML element provided by the class. Type: `unicode` Value:
        'jabber:x:data'