django-form-utils 0.1.8

Dependencies

django-form-utils requires Django 1.0 or later.

ClearableFileField requires Django 1.1 or later.

ImageWidget requires the Python Imaging Library. sorl-thumbnail is optional, but without it full-size images will be displayed instead of thumbnails.

AutoResizeTextarea requires jQuery (by default using a Google-served version; see JQUERY_URL).

BetterForm

Simply inherit your form class from form_utils.forms.BetterForm (rather than django.forms.Form), or your modelform class from form_utils.forms.BetterModelForm, and define the fieldsets and/or row_attrs attributes of the inner Meta class:

class MyForm(BetterForm):
    one = forms.CharField()
    two = forms.CharField()
    three = forms.CharField()
    class Meta:
        fieldsets = (('main', {'fields': ('two',), 'legend': ''}),
                     ('Advanced', {'fields': ('three', 'one'),
                                   'description': 'advanced stuff',
                                   'classes': ('advanced', 'collapse'}))
        row_attrs = {'one': {'style': 'display: none'}}

{% if form.non_field_errors %}{{ form.non_field_errors }}{% endif %}
{% for fieldset in form.fieldsets %}
  <fieldset class="{{ fieldset.classes }}">
  {% if fieldset.legend %}
    <legend>{{ fieldset.legend }}</legend>
  {% endif %}
  {% if fieldset.description %}
    <p class="description">{{ fieldset.description }}</p>
  {% endif %}
  <ul>
  {% for field in fieldset %}
    {% if field.is_hidden %}
      {{ field }}
    {% else %}
      <li{{ field.row_attrs }}>
        {{ field.errors }}
        {{ field.label_tag }}
        {{ field }}
      </li>
    {% endif %}
  {% endfor %}
  </ul>
  </fieldset>
{% endfor %}

{{ form|render }}

{{ form|render:"my_form_stuff/custom_form_template.html" }}

ClearableFileField

A replacement for django.forms.FileField that has a checkbox to clear the field of an existing file. Use as you would any other form field class:

from django import forms

from form_utils.fields import ClearableFileField

class MyModelForm(forms.ModelForm):
    pdf = ClearableFileField()

ClearableFileField also accepts two keyword arguments, file_field and template.

file_field is the instantiated field to actually use for representing the file portion. For instance, if you want to use ClearableFileField to replace an ImageField, and you want to use ImageWidget, you could do the following:

from django import forms

from form_utils.fields import ClearableFileField
from form_utils.widgets import ImageWidget

class MyModelForm(forms.ModelForm):
    avatar = ClearableFileField(
        file_field=forms.ImageField(widget=ImageWidget))

By default, file_field is a plain forms.FileField with the default forms.FileInput widget.

template is a string defining how the FileField (or alternative file_field) and the clear checkbox are displayed in relation to each other. The template string should contain variable interpolation markers %(input)s and %(checkbox)s. The default value is %(input)s Clear: %(checkbox)s.

To use ClearableFileField in the admin; just inherit your admin options class from form_utils.admin.ClearableFileFieldsAdmin instead of django.contrib.admin.ModelAdmin, and all FileField``s and ``ImageField``s in that model will automatically be made clearable (while still using the same file/image field/widget they would have otherwise, including any overrides you provide in ``formfield_overrides).

ClearableImageField

form_utils.fields.ClearableImageField is just a ClearableFileField with the default file field set to forms.ImageField rather than forms.FileField.

ImageWidget

A widget for representing an ImageField that includes a thumbnail of the current image in the field, not just the name of the file. (Thumbnails only available if sorl-thumbnail is installed; otherwise the full-size image is displayed). To use, just pass in as the widget class for an ImageField:

from django import forms

from form_utils.widgets import ImageWidget

class MyForm(forms.Form):
    pic = forms.ImageField(widget=ImageWidget())

ImageWidget accepts a keyword argument, template. This is a string defining how the image thumbnail and the file input widget are rendered relative to each other. The template string should contain variable interpolation markers %(input)s and %(image)s. The default value is %(input)s<br />%(image)s. For example, to display the image above the input rather than below:

pic = forms.ImageField(
    widget=ImageWidget(template='%(image)s<br />%(input)s'))

To use in the admin, set as the default widget for ImageField using formfield_overrides:

from django.db import models

from form_utils.widgets import ImageWidget

class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = { models.ImageField: {'widget': ImageWidget}}

AutoResizeTextarea

Just import the widget and assign it to a form field:

from django import forms
from form_utils.widgets import AutoResizeTextarea

class MyForm(forms.Form):
    description = forms.CharField(widget=AutoResizeTextarea())

Or use it in formfield_overrides in your ModelAdmin subclass:

from django import forms
from django.contrib import admin
from form_utils.widgets import AutoResizeTextarea

class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {forms.CharField: {'widget': AutoResizeTextarea()}}

There is also an InlineAutoResizeTextarea, which simply provides smaller default sizes suitable for use in a tabular inline.

FORM_UTILS_MEDIA_URL

Some projects separate user-uploaded media at MEDIA_URL from static assets. If you keep static assets at a URL other than MEDIA_URL, just set FORM_UTILS_MEDIA_URL to that URL, and make sure the contents of the form_utils/media/form_utils directory are available at FORM_UTILS_MEDIA_URL/form_utils/.

JQUERY_URL

AutoResizeTextarea requires the jQuery Javascript library. By default, django-form-utils links to the most recent minor version of jQuery 1.4 available at ajax.googleapis.com (via the URL http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js). If you wish to use a different version of jQuery, or host it yourself, set the JQUERY_URL setting. For example:

JQUERY_URL = 'jquery.min.js'

This will use the jQuery available at MEDIA_URL/jquery.min.js. Note that a relative JQUERY_URL is always relative to MEDIA_URL, it does not use FORM_UTILS_MEDIA_URL.

tip (unreleased)

0.1.8 (2010.03.16)

• Restrict PIL import to ImageWidget only

• Added AutoResizeTextarea

0.1.7 (2009.12.02)

• Fix ClearableFileField import in admin.py.

0.1.6 (2009.11.24)

• Added documentation and tests for ImageWidget and ClearableFileField.

• Moved ClearableFileField from widgets.py to fields.py.

• Converted doctests to unittests.

0.1.5 (2009.11.10)

• Added fieldset classes (previously existed only as a figment of the documentation).

0.1.0 (2009-03-26)

• Initial public release.