WTForm (What The Form)

Author:: chrj
Posted:: May 3, 2007
Language:: Python
Version:: .96
Score:: 23 (after 25 ratings)

Download
Raw

WTForm is an extension to the django newforms library allowing the developer, in a very flexible way, to layout the form fields using fieldsets and columns

WTForm was built with the well-documented YUI Grid CSS in mind when rendering the columns and fields. This should make it easy to implement WTForm in your own applications.

Here is an image of an example form rendered with WTForm.

'''
WTForm (What The Form)
======================

WTForm is an extension to the django newforms library allowing
the developer, in a very flexible way, to layout the form
fields using <fieldset>s and columns

WTForm was built with the well-documented YUI Grid CSS[1] in
mind when rendering the columns and fields. This should make
it easy to implement WTForm in your own applications.

Revision history
----------------

0.1 (May 2007) - Initial release

0.2 (August 2007) - Bugfix release

  WTForm now works with form_for_model and form_for_instance
  (see "Using forms_for_model and form_for_instance" for details)

Specifying the form layout
--------------------------

WTForm will look for a subclass of your form called "Meta". This
class should have a tuple variable called layout . The layout
variable will hold a tree structure of fields, field sets and
columns.

Here is a simple example:

  class MyForm(WTForm):

      name = forms.CharField(label="Name")
      email = forms.EmailField(label="E-mail address")

      class Meta:

          layout = (Columns(("name",), ("email",)),)

This will result in the form layout of:

  +--------------------------+--------------------------+
  | Name                     | E-mail address           |
  | [______________________] | [______________________] |
  +--------------------------+--------------------------+

WTForm currently uses four types of nodes (fields):

  - Fieldset(legend, field[, field])

    Represents a HTML <fieldset> with the fields specified
    by the arguments as contents. The first argument will
    be the content of the <legend> HTML node. If the legend
    argument is the empty string, the <legend> HTML node
    will not be rendered.
  
  - Columns(column[, column] [, css_class="foobar"])

    Represents a column grid. The columns are specified as
    tuples of fields. In order to obtain different grid
    sizes, the Columns function takes an optional keyword
    argument called css_class which will be rendered as the
    class of the outer-most <div> of the grid layout.

    See the YUI Grid CSS specification[1] for details on
    possible values for css_class. Also, see the
    "Columns CSS styling" part of this documentation.

    Even if you only have one field per column, remember
    to pass a tuple to the Columns function:

      Columns(("field1",), ("field2",))
  
  - HTML(content)

    Represents HTML content. This is useful for embedding
    HTML pieces in between fields for documentation. This
    type of node has no children.

  - "name"

    A string represents a single field. The field must be
    defined in your form. If the field could not be
    resolved, the NoSuchFormField exception will be raised.

Columns and Fieldset nodes can be nested as deep as you
want (just as long as you dont get in a fight with your web
designer).

More examples:
--------------

If you need to add two individuals in your form, you could put
them in field sets:

  class MyForm(WTForm):

      name1 = forms.CharField(label="Name (1)")
      email1 = forms.EmailField(label="E-mail address (1)")

      name2 = forms.CharField(label="Name (2)")
      email2 = forms.EmailField(label="E-mail address (2)")

      class Meta:

          layout = (Fieldset("Person 1",
                             Columns(("name1",), ("email1",))),
                    Fieldset("Person 2",
                             Columns(("name2",), ("email2",))))

This will result in the form layout of:

  +-[ Person 1 ]----------------------------------------+
  |+-------------------------+-------------------------+|
  || Name (1)                | E-mail address (1)      ||
  || [_____________________] | [_____________________] ||
  |+-------------------------+-------------------------+|
  +-----------------------------------------------------+

  +-[ Person 2 ]----------------------------------------+
  |+-------------------------+-------------------------+|
  || Name (2)                | E-mail address (2)      ||
  || [_____________________] | [_____________________] ||
  |+-------------------------+-------------------------+|
  +-----------------------------------------------------+

Say you would like one big field set with the charfields in
two columns:

  class MyForm(WTForm):

      name1 = forms.CharField(label="Name (1)")
      email1 = forms.EmailField(label="E-mail address (1)")

      name2 = forms.CharField(label="Name (2)")
      email2 = forms.EmailField(label="E-mail address (2)")

      class Meta:

          layout = (Fieldset("Person details",
                             Columns(("name1", "name2"),
                                     ("email1", "email2"))),)

This will result in the form layout of:

  +-[ Person details ]----------------------------------+
  |+-------------------------+-------------------------+|
  || Name (1)                | E-mail address (1)      ||
  || [_____________________] | [_____________________] ||
  ||                         |                         ||
  || Name (2)                | E-mail address (2)      ||
  || [_____________________] | [_____________________] ||
  |+-------------------------+-------------------------+|
  +-----------------------------------------------------+

Columns CSS styling:
--------------------

The Column HTML is written with the intent of working with
the YUI CSS for grids. When using Columns you can specify
the CSS class of the outer <div> by supplying the keyword
argument css_class:

  Columns(field1, field2, field3, css_class="yui-gc")

This will create a 2/3 - 1/3 grid with two columns. Read
more about YUI Grids CSS:

  http://developer.yahoo.com/yui/grids/

Differences from newforms / HTML structure of fields:
-----------------------------------------------------

In order to make CSS styling a lot easier, WTForm til raise
NotImplemented on as_table, as_p and as_ul. When rendering
WTForm forms you must use as_div, as we believe that this
is the way to structure your forms.

A field will be rendered as:

  <div class="CharField TextInput">
    <label for="id_name">Name</label>
    <span class="help_text">Very helpful text</span>
    <ul class="errors">
      <li>Error 1</li>
      <li>Error 2</li>
    </ul>
    <div class="field">
      <input type="text" name="name" value="" id="id_name" />
    </div>
  </div>    
    
The CSS classes in the outer <div> is fetched from the field
type as well as the widget type. If the field is marked as
required - it will also get a Required.

Data handling / newforms compability:
-------------------------------------

WTForm descends from newforms.BaseForm, thus data handling is
done the same way: is_valid(), clean_data...

Refer to the newforms documentation[2] for details.

Using forms_for_model and form_for_instance
-------------------------------------------

When using form_for_model, you only need to define the layout
of the form. Here is an example from our Intranet application:

  from django import newforms as forms
  from intranet.timesheet.models import TimeEntry
  from wtform import WTForm, Fieldset

  class TimeEntryFormBase(WTForm):
    
      class Meta:
          
          layout = (Fieldset('Elements',
                             'employee', 'date', 'project',
                             'description', 'tickets'),)

  TimeEntryForm = forms.form_for_model(TimeEntry,
                                       form=TimeEntryFormBase)

As well as:

  TimeEntryForm = forms.form_for_instance(entry,
                                          form=TimeEntryFormBase)

Again, for details about form_for_model and form_for_instance,
you should refer to the newforms documentation[2] at the django
website.

Credits:
--------

Christian Joergensen <christian.joergensen [at] gmta.info>
Oscar Eg Gensmann <oscar.gensmann [at] gmta.info>

Founded in 2003, GMTA ApS is the partnership between three
danish computer enthusiasts with a strong interest in the
web-phenomenon.

Visit our website: http://www.gmta.info

License:
--------

Creative Commons Attribution-Share Alike 3.0 License
http://creativecommons.org/licenses/by-sa/3.0/

When attributing this work, you must maintain the Credits
paragraph above.

References:
-----------

 [1] http://developer.yahoo.com/yui/grids/
 [2] http://www.djangoproject.com/documentation/newforms/

'''

from django.newforms.forms import BoundField
from django.utils.html import escape
from django.newforms import BaseForm

class NoSuchFormField(Exception):
    "The form field couldn't be resolved."
    pass

def error_list(errors):
    return '<ul class="errors"><li>' + \
           '</li><li>'.join(errors) + \
           '</li></ul>'

class WTForm(BaseForm):

    def __init__(self, data=None, auto_id='id_%s', prefix=None, initial=None):

        super(WTForm, self).__init__(data, auto_id, prefix, initial)

        # do we have an explicit layout?
        
        if hasattr(self, 'Meta') and hasattr(self.Meta, 'layout'):
            self.layout = self.Meta.layout
        else:
            # Construct a simple layout using the keys from the fields
            self.layout = self.fields.keys()

        self.prefix = []
        self.top_errors = []

    def as_table(self):
        raise NotImplementedError("WTForm does not support <table> output.")

    def as_ul(self):
        raise NotImplementedError("WTForm does not support <ul> output.")
    
    def as_p(self):
        raise NotImplementedError("WTForm does not support <p> output.")

    def as_div(self):

        ''' Render the form as a set of <div>s. '''

        output = self.render_fields(self.layout)
        prefix = u''.join(self.prefix)

        if self.top_errors:
            errors = error_list(self.top_errors)
        else:
            errors = u''

        self.prefix = []
        self.top_errors = []

        return prefix + errors + output

    # Default output is now as <div> tags.
    
    __str__ = as_div

    def render_fields(self, fields, separator=u""):

        ''' Render a list of fields and join the fields by
            the value in separator. '''

        output = []
        
        for field in fields:

            if isinstance(field, (Columns, Fieldset, HTML)):
                output.append(field.as_html(self))
            else:
                output.append(self.render_field(field))

        return separator.join(output)

    def render_field(self, field):

        ''' Render a named field to HTML. '''

        try:
            field_instance = self.fields[field]
        except KeyError:
            raise NoSuchFormField("Could not resolve form field '%s'." % field)

        bf = BoundField(self, field_instance, field)

        output = ''

        if bf.errors:

            # If the field contains errors, render the errors to a <ul>
            # using the error_list helper function.
            bf_errors = error_list([escape(error) for error in bf.errors])

        else:
            bf_errors = ''

        if bf.is_hidden:

            # If the field is hidden, add it at the top of the form

            self.prefix.append(unicode(bf))

            # If the hidden field has errors, append them to the top_errors
            # list which will be printed out at the top of form
            
            if bf_errors:
                self.top_errors.extend(bf.errors)

        else:

            # Find field + widget type css classes
            css_class = type(field_instance).__name__ + " " + \
                        type(field_instance.widget).__name__

            # Add an extra class, Required, if applicable
            if field_instance.required:
                css_class += " Required"

            if bf.label:

                # The field has a label, construct <label> tag
                label = escape(bf.label)
                label = bf.label_tag(label) or ''

            else:
                label = ''

            if field_instance.help_text:

                # The field has a help_text, construct <span> tag
                help_text = escape(field_instance.help_text)
                help_text = '<span class="help_text">%s</span>' % help_text

            else:
                help_text = u''

            # Finally render the field
            output = '<div class="field %(class)s">%(label)s%(help_text)s%(errors)s<div class="input">%(field)s</div></div>\n' % \
                     {'class': css_class, 'label': label, 'help_text': help_text, 'errors': bf_errors, 'field': unicode(bf)}

        return output

class Fieldset(object):

    ''' Fieldset container. Renders to a <fieldset>. '''

    def __init__(self, legend, *fields):
        self.legend_html = legend and ('<legend>%s</legend>' % legend) or ''
        self.fields = fields
    
    def as_html(self, form):
        return u'<fieldset>%s%s</fieldset>' % \
               (self.legend_html, form.render_fields(self.fields))
            
class Columns(object):

    ''' Columns container. Renders to a set og <div>s named
        with classes as used by YUI (Yahoo UI)  '''

    def __init__(self, *columns, **kwargs):
        self.columns = columns
        self.css_class = kwargs.has_key('css_class') and kwargs['css_class'] or 'yui-g'

    def as_html(self, form):
        output = []
        first = " first"

        output.append('<div class="%s">' % self.css_class)

        for fields in self.columns:
            output.append('<div class="yui-u%s">%s</div>' % \
                          (first, form.render_fields(fields)))
            first = ''

        output.append('</div>')

        return u''.join(output)

class HTML(object):

    ''' HTML container '''

    def __init__(self, html):
        self.html = html

    def as_html(self, form):
        return self.html

Comments

jmohr (on May 25, 2007):

Thank you, this is very nice! However, it doesn't seem to work with form_for_model or form_for_instance... the resulting class doesn't have any goodies in it:

    >>> ArticleForm = forms.form_for_model(Article,form=WTForm)
    >>> f = ArticleForm()
    >>> f.as_div()
    u''
    >>> f.fields.keys()
    []
    >>> 
    >>> ArticleForm = forms.form_for_model(Article)
    >>> f = ArticleForm()
    >>> f.fields.keys()
    ['title', 'slug', 'author', 'intro', 'body', 'tag_list', 'published']
    >>>

chrj (on July 2, 2007):

You're right. I will try to look into this.

Regards,

simon (on July 3, 2007):

Do you have a URL to a page showing this code in action?

chrj (on August 5, 2007):

jmohr, your issue has now been resolved. The WTForm class now descends directly form BaseForm and that solved the problem.

Thank you.

chrj (on August 5, 2007):

simon, I have added a screenshot to the description.

micktwomey (on August 8, 2007):

With recent django svn (r5830) I'm seeing a couple of problems:

Without either deriving from forms.Form or adding a __metaclass__ = django.newforms.forms.DeclarativeFieldsMetaclass" to the class I see an error about base_fields being missing on the WTForm class when I try to use it.
There are some new arguments in the BaseForm class, omitting them seems to break errors, changing the __init__ to this fixes it:

def __init__(self, *args, **kwargs): super(WTForm, self).__init__(*args, **kwargs)

(sorry, can't seem to get indentation working right)

digi604 (on October 8, 2007):

the tabindex needs to be set if you use 2 columns... is there a way to automate this?

mthorley (on November 29, 2007):

object has no attribute 'base_fields'

I want to clarify mickwomey's comment because I glossed over the first part of what he said and had to do my own debugging.

The WTForm class must be updated to match the following

from django.newforms.forms import BaseForm, DeclarativeFieldsMetaclass
class WTForm(BaseForm):
    __metaclass__ = DeclarativeFieldsMetaclass

    def __init__(self, *args, **kwargs):
        super(WTForm, self).__init__(*args, **kwargs)

Note that DeclarativeFieldMetaclass must be imported from django.newforms.forms and NOT django.newforms

I have tested this with django r6063

mthorley (on November 29, 2007):

WTForm fails silently with no output

I ran into another problem (user error) when trying to use this great module. I guess I need to start reading more carefully because the answer is in the documentation.

For clarification the layout variable must be a tuple or other iterable object, meaning it has a getitem method.

What annoyed me, was that if you fail to make to do so, there is no warning. The modules just fails silently. It took me close to an hour of debugging to figure out where I had gone wrong.

Example:

This fails silently

layout = (Columns(("name",), ("email",)))

This does not

layout = (Columns(("name",), ("email",)),)

The difference being the comma between the last two parenthesis.

Solution: To avoid this minor detail snagging me again I added a assert statement to the WTForm init method, to ensure that layout is iterable.

I have reprinted the entire method for clarity. Please note that my sample includes the changes first pointed out by micktwomey that are required to make this module compatible with current versions of django.

def __init__(self, *args, **kwargs):
    super(WTForm, self).__init__(*args, **kwargs)

    # do we have an explicit layout?

    if hasattr(self, 'Meta') and hasattr(self.Meta, 'layout'):
        assert hasattr(self.Meta.layout, '__getitem__') is True, "Meta.layout must be iterable"
        self.layout = self.Meta.layout
    else:
        # Construct a simple layout using the keys from the fields
        self.layout = self.fields.keys()

    self.prefix = []
    self.top_errors = []

I have tested this with django r6063

Subsume (on March 14, 2008):

Crying shame this isn't maintained.

Subsume (on March 17, 2008):

Was able to make it work as of March 08.

Subsume (on March 17, 2008):

^ append

Got this working with a lot of hassle made short thanks to the advice of mthorley above. Good work!

One thing you will also have to do is....

from django.utils import safestring

and then for as_div....

return safestring.mark_safe(prefix + errors + output)

njeudy (on March 18, 2008):

@subsume:

CAn you explain hox you did it working ? I always have this error: Could not resolve form field 'name'.

My function:

class PageFormBase(WTForm):
      class Meta:
          layout = (Fieldset('test','name','content'),)
   PageForm = forms.form_for_model(Page,form=PageFormBase)
   f = PageForm()
   f.as_div()

and my Page model:

class Page(models.Model):
    name = models.CharField(maxlength="20", primary_key=True)
    content = models.TextField(blank=True)

thanks if you could help me.

gvkreddyvamsi (on April 18, 2008):

HI,

Iam new to python and django.

Here i need to enable radio buttons on home screen depending on data stored in model database. How we can do this to get data in database and enabling radio buttons on same screen?

For example i have to choose role which is not filled already.

Plz help me.

my mail [email protected]

Thanks in advance by vamsi

Ciantic (on March 18, 2009):

Oh my, I discareded my version, also in django snippets (which is quiet similar as this approach) long time ago because this damn well should be in django already!

Thumbs up for maintaining! If we could get this to be part of Django distribution (contrib or something), then I for one could try to make django admin use this. I hate the way Django admin does fieldsets.

sub_anseo (on May 1, 2014):

A very nice article to read, and I will share thank you.

Please login first before commenting.

WTForm (What The Form)

More like this

Comments