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']

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

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)
  add_field(self, name, values, field_type, label, options, required, desc, value)
Add a field to the form.
  add_item(self, fields)
Add and item to the form.
  complete_xml_element(self, xmlnode, doc)
Complete the XML node with `self` content.
  copy(self)
Get a deep copy of `self`.
  make_submit(self, keep_types)
Make a "submit" form using data in `self`.
    Inherited from StanzaPayloadObject
  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)

Class Variable Summary
tuple allowed_types = ('form', 'submit', 'cancel', 'result')
str xml_element_name = 'x'
str xml_element_namespace = 'jabber:x:data'

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.
    - `title`: form title.
    - `instructions`: instructions for the form.
    - `fields`: form fields.
    - `reported_fields`: fields reported in multi-item data.
    - `items`: items of multi-item data.
:Types:
    - `xmlnode_or_type`: `libxml2.xmlNode` or `str`
    - `title`: `unicode`
    - `instructions`: `unicode`
    - `fields`: `list` of `Field`
    - `reported_fields`: `list` of `Field`
    - `items`: `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.
    - `values`: raw field values. Not to be used together with `value`.
    - `field_type`: field type.
    - `label`: field label.
    - `options`: optional values for the field.
    - `required`: `True` if the field is required.
    - `desc`: natural-language description of the field.
    - `value`: field value or values in a field_type-specific type. May be used only
      if `values` parameter is not provided.
:Types:
    - `name`: `unicode`
    - `values`: `list` of `unicode`
    - `field_type`: `str`
    - `label`: `unicode`
    - `options`: `list` of `Option`
    - `required`: `bool`
    - `desc`: `unicode`
    - `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.

:return: the field added.
:returntype: `Field`

add_item(self, fields=None)

Add and item to the form.

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

:return: the item added.
:returntype: `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.
    - `doc`: document to which the element belongs.
:Types:
    - `xmlnode`: `libxml2.xmlNode`
    - `doc`: `libxml2.xmlDoc`
Overrides:
pyxmpp.objects.StanzaPayloadObject.complete_xml_element

copy(self)

Get a deep copy of `self`.

:return: a deep copy of `self`.
:returntype: `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.

:raise ValueError: when any required field has no value.

:Parameters:
    - `keep_types`: when `True` field type information will be included
      in the result form. That is usually not needed.
:Types:
    - `keep_types`: `bool`

:return: the form created.
:returntype: `Form`

Class Variable Details

allowed_types

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

xml_element_name

Type:
str
Value:
'x'                                                                    

xml_element_namespace

Type:
str
Value:
'jabber:x:data'                                                        

Generated by Epydoc 2.1 on Wed May 31 22:36:57 2006 http://epydoc.sf.net