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'