Customizing newforms

This post was written on 2007/06/01 at 13:09:36 by Horst Gutmann

You like newforms but are a little bit uncertain how to style your forms using CSS with form.as_ul? Well, if you want more CSS classes to style upon, here a simple way on how to get them the easy way.

This mini-tutorial will show you how to add CSS classes to the help text and position the errorlist differently for fields in a newform-Form rendered with as_p() (although this also should apply to all the other rendering methods).

First of all a short look at the current implementation of the as_p() method of the BaseForm class as defined in django.newforms.forms: 

   def as_p(self):
       "Returns this form rendered as HTML <p>s."
       return self._html_output(u'<p>%(label)s %(field)s%(help_text)s</p>',
           u'<p>%s</p>', '</p>', u' %s', True)

So if we want to change this, just create a subclass of the Form class (which itself is a subclass to BaseForm) somewhere in your code - let's say in myproj.myapp.forms for now: 

   import django.newforms as forms



class BaseForm(forms.Form):
       def as_p(self):
           return self._html_output(u'<p>%(label)s %(field)s%(help_text)s</p>',
               u'<p>%s</p>', '</p>', u' %s', True)

To get more detailed output, all we have to do, is change the parameters passed to self._html_output(..), so I will skip the rest from now on.

This method offers parameters for everything we will need from now on:

normal_row
Here you can set the base format for the field rendering.
error_row
This argument allows you to style the "wrapper" for the errorlist and will only get used if really an error affecting the current field appears and it will only be used if the errorlist should get its own row (as can be set with the last argument).
row_ender
This is only used internally, so we will skip this.
help_text_html
Formating the help output which only gets used if there is any help_text to apply it on ;-)
errors_on_separate_row
Remember when I said error_row is a little bit misleading? Well, this only really applied when you set this parameter to False ;-) Then you will have to put "%(errors)s" somewhere into your normal_row format in order to get any error rendering at all :-)

So let's apply this intel: First of all, it would be handy, if the help_text of each form field had it's own class, so we could easily ban it to its own line using display:block if we want to: 

   return self._html_output(u'<p>%(label)s %(field)s<span class="help">%(help_text)s</span></p>',
       u'<p>%s</p>', '</p>', u' %s', True)

This is the dirty way of doing it, since it will create that span even if the actual help text is empty. To get around this, you can change the help_text_html argument: 

   return self._html_output(u'<p>%(label)s %(field)s%(help_text)s</p>',
       u'<p>%s</p>', '</p>', u'<span class="help">%s</span>', True)

So this will make styling the help text way easier. But one big problem for me still remained: The error messages for each field were flying around like crazy. That's because the argument that is set to True here (errors_on_separate_row) actually tells the method, to put the error messages to a field on their own rows, or in this case in their own paragraphs. Since I don't like that, I will just switch it to False, which will put the error list right into the same paragraph with the rest of the field's output. If you do this, you will also have to add the errors to the first argument: 

   u'<p>%(label)s %(field)s%(errors)s%(help_text)s</p>', u'<p>%s</p>'

The error_row content can stay the same, since the error list already comes with the "errorlist" class by default :-)

Comments:

  • Smaaz (Guest)

    Hi, is there a demo of these styles somewhere? Thanks

    June 10, 2007, 2:17 p.m.

  • zerok

    Hi :)

    Nope, not yet. What kind of demo would you like to see?

    Basically this is part of my on-going effort to re-implement this site using Django and so I also use this technique for zerokspot v5, which will hopefully go live somewhen at the end of June or during the first days of July.

    June 10, 2007, 2:37 p.m.

*'d input fields are required.