Package web2py :: Package gluon :: Module html :: Class FORM |
[hide private]
[frames] | no frames]

# Class FORM

source code

      object --+
               |
    XmlComponent --+
                   |
                 DIV --+
                       |
                      FORM

Known Subclasses:
  sqlhtml.SQLFORM

example:

       >>> from validators import IS_NOT_EMPTY
       >>> form=FORM(INPUT(_name="test", requires=IS_NOT_EMPTY()))
       >>> form.xml()
       '<form action="" enctype="multipart/form-data" method="post"><input name="test" type="text" /></form>'

a FORM is container for INPUT, TEXTAREA, SELECT and other helpers

form has one important method:

       form.accepts(request.vars, session)

if form is accepted (and all validators pass) form.vars contains the accepted vars, otherwise form.errors contains the errors. in case of errors the form is modified to present the errors to the user.

Instance Methods | [hide private]
__init__(self, *components, **attributes) :param *components: any components that should be nested in this element :param **attributes: any attributes you want to give to this element | source code
_postprocessing(self) Handling of attributes (normally the ones not prefixed with '_'). | source code
accepts(self, vars, session=1, formname=`'``default``'`, keepvalues=True, onvalidation=1, hideerror=True) | source code
hidden_fields(self) | source code
process(self, values=1, session=1, **args) Perform the .validate() method but returns the form Usage in controllers: # directly on return def action(): #some code here return dict(form=FORM(...).process(...)) You can use it with FORM, SQLFORM or FORM based plugins Examples: #response.flash messages def action(): form = SQLFORM(db.table).process(message_onsuccess='Sucess!') retutn dict(form=form) # callback function # callback receives True or False as first arg, and a list of args. | source code
validate(self, values=1, session=1, formname=`'``default``'`, keepvalues=True, onvalidation=1, hideerror=True, onsuccess=`'``flash``'`, onfailure=`'``flash``'`, message_onsuccess=1, message_onfailure=1) This function validates the form, you can use it instead of directly form.accepts. | source code
xml(self) generates the xml for this component. | source code
Inherited from `DIV`: `__delitem__`, `__getitem__`, `__len__`, `__nonzero__`, `__setitem__`, `__str__`, `append`, `element`, `elements`, `flatten`, `insert`, `sibling`, `siblings`, `update` Inherited from `DIV` (private): `_fixup`, `_setnode`, `_traverse`, `_validate`, `_wrap_components`, `_xml` Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`

Class Variables | [hide private]
| tag = ``'``form``'``
Inherited from `DIV`: `regex_attr`, `regex_class`, `regex_id`, `regex_tag`

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, *components, **attributes) (Constructor) | source code
:param *components: any components that should be nested in this element :param **attributes: any attributes you want to give to this element :raises SyntaxError: when a stand alone tag receives components Overrides: DIV.__init__ (inherited documentation)

### _postprocessing(self) | source code
Handling of attributes (normally the ones not prefixed with '_'). Nothing to postprocess yet. May be overridden by subclasses Overrides: DIV._postprocessing (inherited documentation)

### process(self, values=1, session=1, **args) | source code
    Perform the .validate() method but returns the form

    Usage in controllers:
    # directly on return
    def action():
        #some code here
        return dict(form=FORM(...).process(...))

    You can use it with FORM, SQLFORM or FORM based plugins

    Examples:
    #response.flash messages
    def action():
        form = SQLFORM(db.table).process(message_onsuccess='Sucess!')
        retutn dict(form=form)

    # callback function
    # callback receives True or False as first arg, and a list of args.
    def my_callback(status, msg):
       response.flash = "Success! "+msg if status else "Errors occured"

    # after argument can be 'flash' to response.flash messages
    # or a function name to use as callback or None to do nothing.
    def action():
        return dict(form=SQLFORM(db.table).process(onsuccess=my_callback)

### validate(self, values=1, session=1, formname=`'``default``'`, keepvalues=True, onvalidation=1, hideerror=True, onsuccess=`'``flash``'`, onfailure=`'``flash``'`, message_onsuccess=1, message_onfailure=1) | source code
    This function validates the form,
    you can use it instead of directly form.accepts.

    Usage:
    In controller

    def action():
        form=FORM(INPUT(_name="test", requires=IS_NOT_EMPTY()))
        form.validate() #you can pass some args here - see below
        return dict(form=form)

    This can receive a bunch of arguments

    onsuccess = 'flash' - will show message_onsuccess in response.flash
                None - will do nothing
                can be a function (lambda form: pass)
    onfailure = 'flash' - will show message_onfailure in response.flash
                None - will do nothing
                can be a function (lambda form: pass)

    values = values to test the validation - dictionary, response.vars, session or other - Default to (request.vars, session)
    message_onsuccess
    message_onfailure

### xml(self) | source code
generates the xml for this component. Overrides: DIV.xml (inherited documentation)