w20e.forms 1.0.0a

Core concepts

The core concepts are as follows (so you can quickly decide whether you like this approach or not):

A form is a container for/composition of four things:

1. data

2. model

3. view

4. submission

This clearly separates the data, the data’s properties (datatype, whether something is required or not, etc.) and the renderable part of the form. This is also the main difference between this API and other solutions (afaik…). Where the usual approach is to define a form based on a Schema or other data-centered notion, like so:

foo = String("id", "label", validator=somefunction)

the approach of w20e.forms is to define:

foo = Field("fid")
props = FieldProperties("pid", ["fid"], required=True, datatype=int)
ctrl = Input("cid", "label", bind="fid")

where the properties and control are bound to the variable. This enables controls in your form that are not bound to any data you wish to collect, sharing of properties, etc.

Another important difference is that the API provides a structured way of defining properties for data, instead of having to define your own validation. See section 1.2 for details.

Basic use

Ok, enough theory, let’s do something for real.

A form is produced by hand, or by using a factory: this should take care of producing a form holding the necessary stuff.

Let’s get the imports over with…

>>> import sys
>>> from interfaces import *
>>> from zope.interface import implements
>>> from formdata import FormData
>>> from formview import FormView
>>> from formmodel import FormModel
>>> from data.field import Field
>>> from model.fieldproperties import FieldProperties
>>> from rendering.control import Input, Select, Option
>>> from rendering.group import FlowGroup
>>> from form import Form, FormValidationError
>>> from rendering.html.renderer import HTMLRenderer
>>> from submission.attrstorage import AttrStorage

Beyond the basics

Well, this is all very simple, and it is quite likely that you would wish for something a bit more usefull. All parts of the form are there to be extended. Take for instance the FormView. A developer (or end user) should be able to:

• create a full HTML form;

• use a generated HTML form (this is wat the base implementation does);

• create a PDF form.

The factory is also an important part of the form process. A factory can be imagined to be one of the following:

• produced from a Schema (content type);

• produced from an XML definition, for example an XForms instance from OpenOffice.

Forms in general should be:

• submitable to a range of handlers, like email, database storage, content type storage;

• easy to validate ‘live;

• enable multi-page.

More detailed tests:

We’d like to check whether lookup of a control by bind works, so as to be able to process values into lexical values. This is especially interesting when using selects: we’d expect to see the label not the value in lexical space.

>>> data = FormData()
>>> data.addField(Field("f0", "opt0"))
>>> view = FormView()
>>> opts = [Option("opt0", "Option 0"), Option("opt1", "Option 1")]
>>> view.addRenderable(Select("sel0", "Select 0", bind="f0", options=opts))
>>> ctl = view.getRenderableByBind("f0")
>>> ctl.lexVal("opt0")
'Option 0'

Can we use variable substitution in labels and hints? Yes, we can!

>>> data = FormData()
>>> data.addField(Field("f0", "Pipo"))
>>> data.addField(Field("f1"))
>>> view = FormView()
>>> view.addRenderable(Input("in0", "First name", bind="f0"))
>>> view.addRenderable(Input("in1", "Last name for ${f0}", bind="f1"))
>>> model = FormModel()
>>> form = Form("test", data, model, view, None)
>>> renderer = HTMLRenderer()
>>> field = form.view.getRenderable('in1')
>>> renderer.render(form, field, sys.stdout)
<div id="in1" class="control input relevant">
<label for="input-in1">Last name for Pipo</label>
<div class="alert"></div>
<div class="hint"></div>
<input id="input-in1" type="text" name="in1" value="" size="20"/>
</div>

Let’s delve into input processing a bit… A simple input should just return it’s own value

>>> data = {'pipo': 'lala'}
>>> ctl = Input("pipo", "f0", "Some input")
>>> ctl.processInput(data)
'lala'

Registering your own stuff

w20e.forms is not a complete library for forms, and it will never be this, since most people have very specific needs, like a specific widget, a custom version of an input field, etc. The API facilitates in this by using a global registry to register extensions.

The global registry is available like so:

>>> from w20e.forms.registry import Registry

and offers a number of class methods to register stuff.

Let’s for exampe register a new renderer for an input:

>>> def make_vocab():
...   return [Option('0', 'Opt 0'), Option('1', 'Opt 1')]
... Registry.register_vocab('foovocab', make_vocab)
... sel = Select("select0", "Select me!", vocab=make_vocab,
...   bind="field2", with_empty=True))

>>> registry.register_expr_context('mycontext', obj)
... model.addFieldProperties(FieldProperties("req", ["foo"],
...   relevant="mycontext.some_method())

XML

The xml namespace of the w20e.forms package provides an XML based implementation of the w20e.forms API. This enables definition from and serialization to XML files. Provided is the DTD used for defining the w20e.forms as XML. This is quite similar to xForms.

Using XML as definition of forms provides a more declarative way of creating forms, not unlike the way you create a form in HTML. Also, XML is a format that is easily stored and transported.

Start using the XML factory

>>> from factory import XMLFormFactory

Now let us create a factory class

>>> xml = """
... <form id="test">
...
...   <!-- The data part, a.k.a. the variables you wish to collect -->
...   <data>
...     <foo/>
...     <bar value="666"/>
...   </data>
...
...   <model>
...     <properties id="required">
...       <bind>foo</bind>
...       <bind>bar</bind>
...       <required>True</required>
...     </properties>
...     <properties id="int">
...       <bind>bar</bind>
...       <datatype>int</datatype>
...     </properties>
...   </model>
...
...   <view>
...     <input id="fooctl" bind="foo">
...       <label>Foo?</label>
...       <hint>Well, foo or no?</hint>
...     </input>
...     <select id="barctl" bind="bar">
...       <property name="multiple">False</property>
...       <label>Bar</label>
...       <option value="1">One</option>
...       <option value="2">Two</option>
...     </select>
...     <select bind="bar" id="barctl2">
...       <label>Bar2</label>
...       <option value="3">Three</option>
...       <option value="4">Four</option>
...     </select>
...     <select bind="bar" id="barctl3">
...       <property name="vocab">some_vocab</property>
...       <label>Bar3</label>
...     </select>
...     <group layout="flow" id="groupie">
...       <label>GruppoSportivo</label>
...       <text id="txt">Moi</text>
...     </group>
...   </view>
...
...   <submission type="none">
...     <property name="action">@@save</property>
...   </submission>
...
... </form>"""

We are using a vocab in the xml, so register it… >>> from w20e.forms.registry import Registry … def some_vocab(): … return [Option(0, 0), Option(1, 1)] … Registry.register_vocab(‘some_vocab’, some_vocab)

>>> xmlff = XMLFormFactory(xml)
>>> form = xmlff.create_form()
>>> print len(form.data.getFields())
2

>>> print form.data.getField("foo").id
foo

>>> print form.data.getField("bar").value
666

Set the value

>>> form.data.getField("bar").value = 777
>>> print form.data.getField("bar").value
777

Okido, so far so good. Now let’s see what properties we have.

>>> props = form.model.getFieldProperties("bar")
>>> len(props)
2

>>> intprop = [prop for prop in props if prop.id == "int"][0]
>>> reqprop = [prop for prop in props if prop.id == "required"][0]
>>> reqprop.getRequired()
'True'

>>> intprop.getDatatype()
'int'

Finally, check the viewable part, or the controls >>> ctrl = form.view.getRenderable(“fooctl”) >>> ctrl.label ‘Foo?’

>>> ctrl.__class__.__name__
'Input'

>>> ctrl.hint
'Well, foo or no?'

>>> ctrl.id
'fooctl'

>>> ctrl.bind
'foo'

>>> ctrl = form.view.getRenderable("barctl")
>>> ctrl.multiple
'False'

>>> len(ctrl.options)
2

Do we get the nested stuff?

>>> ctrl = form.view.getRenderable("txt")
>>> ctrl.id
'txt'

Pyramid

The pyramid package provides a simple means of using w20e.forms for pyramid apps. The package provides a specific ‘file’ field for pyramid, to enable extracting filename and contents from a file in a POST/GET request, and a base view.

Would you wish to use w20e.forms, then:

• add w20e.forms to the eggs dependencies of your app (duh…)

• for the view that you wish to show the actual form, override w20e.forms.pyramid.pyramidformview. Let’s do some imports first. Please note that it is more convenient to use the XML implementation, as shown later on. Also, if you insist on using the Pythonic implementation, it is better to make a factory create the form, so you can just call the factory from your view. Anyway, let’s go for the not-so-smart way:

  >>> from w20e.forms.form import Form
  >>> from w20e.forms.formdata import FormData
  >>> from w20e.forms.formmodel import FormModel
  >>> from w20e.forms.formview import FormView
  >>> from w20e.forms.submission.attrstorage import AttrStorage
  >>> from w20e.forms.data.field import Field
  >>> from w20e.forms.rendering.control import Input
  >>> from w20e.forms.pyramid.formview import formview as pyramidformview
  

  Phew, that was a load of imports. Now do the actual view class. It’s a pretty simple form, but you should get the picture.

  >>> class yourformview(pyramidformview):
  ...   def __init__(self, context, request):
  ...     data = FormData()
  ...     data.addField(Field("foo", "some default value"))
  ...     data.addField(Field("bar"))
  ...     model = FormModel()
  ...     view = FormView()
  ...     # We'll leave the poperties out for now, check the main
  ...     # README for details
  ...     view.addRenderable(Input("input0", "Input foo", bind="foo"))
  ...     view.addRenderable(Input("input1", "Input bar here", bind="bar"))
  ...     submission = AttrStorage(attr_name="_data")
  ...     form = Form("test", data, model, view, submission)
  ...     pyramidformview.__init__(self, context, request, form)
  

  Now, a view for pyramid just takes a context, and a request, so let’s create the view instance:

  >>> class Context:
  ...  """ nothing needed here, but we'll store the data in here """
  >>> class Request:
  ...   def __init__(self, params=None):
  ...     self.params = params
  >>> ctx = Context()
  >>> req = Request()
  >>> view = yourformview(ctx, req)
  

  Ok, we’re ready for some action now. Let’s try to render the form.

  >>> print view.renderform()
  <form class="w20e-form" method="post" action="" enctype="multipart/form-data">
  <input type="hidden" name="formprocess" value="1"/>
  <div class="alert"></div>
  <div id="input0" class="control input relevant">
  <label for="input-input0">Input foo</label>
  <div class="alert"></div>
  <div class="hint"></div>
  <input id="input-input0" type="text" name="input0" value="some default value" size="20"/>
  </div>
  <div id="input1" class="control input relevant">
  <label for="input-input1">Input bar here</label>
  <div class="alert"></div>
  <div class="hint"></div>
  <input id="input-input1" type="text" name="input1" value="" size="20"/>
  </div>
  </form>
  <BLANKLINE>
  

  Nice. Now let’s give the request some content, and let the view handle the submission. This should result in the context having the form data stored in the _data attribute. formprocess is the marker used by w20e.forms to assume that the form is posted.

  >>> req = Request({'formprocess': 1, 'input0': 6, 'input1': 'whatever'})
  >>> view = yourformview(ctx, req)
  >>> view()
  {'status': 'stored', 'errors': {}}
  >>> ctx._data.getField('foo').value
  6
  >>> ctx._data.getField('bar').value
  'whatever'