Package pyxmpp :: Package jabber :: Module dataforms :: Class Form

[hide private]

# Class Form

source code

                     object --+
                              |
    objects.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']

Instance Methods | [hide private]

__init__(self, xmlnode_or_type=`'``form``'`, title=None, instructions=None, fields=None, reported_fields=None, items=None) Initialize a Form object. | source code

__getitem__(self, name_or_index) | source code

__contains__(self, name) | source code

__iter__(self) | source code

Field

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. | source code

Item

add_item(self, fields=None) Add and item to the form. | source code

Form

make_submit(self, keep_types=False) Make a "submit" form using data in `self`. | source code

Form

copy(self) Get a deep copy of `self`. | source code

complete_xml_element(self, xmlnode, doc) Complete the XML node with `self` content. | source code

__from_xml(self, xmlnode) Initialize a Form object from an XML element. | source code

__get_reported(self, xmlnode) Parse the <reported/> element of the form. | source code

Inherited from `objects.StanzaPayloadObject`: `as_xml` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Class Variables | [hide private]

| allowed_types = ``(``'``form``'``,` `'``submit``'``,` `'``cancel``'``,` `'``result``'``)``
: `unicode` | xml_element_name = ``'``x``'`` : name for the XML element provided by the class.
: `unicode` | xml_element_namespace = ``'``jabber:x:data``'`` : namespace URI for the XML element provided by the class.

Instance Variables | [hide private]

: `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").

Properties | [hide private]

Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, xmlnode_or_type=`'``form``'`, title=None, instructions=None, fields=None, reported_fields=None, items=None)
(Constructor)

source code

Initialize a Form object.

Parameters:
  - `xmlnode_or_type` (: `libxml2.xmlNode` or `str`) - : XML element to parse or a form title.
  - `title` (: `unicode`) - : form title.
  - `instructions` (: `unicode`) - : instructions for the form.
  - `fields` (: `list` of Field) - : form fields.
  - `reported_fields` (: `list` of Field) - : fields reported in multi-item data.
  - `items` (: `list` of Item) - : items of multi-item data.
Overrides: object.__init__

### add_field(self, name=None, values=None, field_type=None, label=None, options=None, required=False, desc=None, value=None)

source code

Add a field to the form.

Parameters:
  - `name` (: `unicode`) - : field name.
  - `values` (: `list` of `unicode`) - : raw field values. Not to be used together with `value`.
  - `field_type` (: `str`) - : field type.
  - `label` (: `unicode`) - : field label.
  - `options` (: `list` of Option) - : optional values for the field.
  - `required` (: `bool`) - : `True` if the field is required.
  - `desc` (: `unicode`) - : natural-language description of the field.
  - `value` (: `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.) - : field value or values in a field_type-specific type. May be used only if `values` parameter is not provided.
Returns: Field
  the field added.

### add_item(self, fields=None)

source code

Add and item to the form.

Parameters:
  - `fields` (: `list` of Field) - : fields of the item (they may be added later).
Returns: Item
  the item added.

### make_submit(self, keep_types=False)

source code

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` (: `bool`) - : when `True` field type information will be included in the result form. That is usually not needed.
Returns: Form
  the form created.
Raises:
  - `ValueError` - when any required field has no value.

### copy(self)

source code

Get a deep copy of `self`.

Returns: Form
  a deep copy of `self`.

### complete_xml_element(self, xmlnode, doc)

source code

Complete the XML node with `self` content.

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

### __from_xml(self, xmlnode)

source code

Initialize a Form object from an XML element.

Parameters:
  - `xmlnode` (: `libxml2.xmlNode`) - : the XML element.

### __get_reported(self, xmlnode)

source code

Parse the <reported/> element of the form.

Parameters:
  - `xmlnode` (: `libxml2.xmlNode`) - : the element to parse.