Not Logged In

django-form-utils 1.0.2

This application provides utilities for enhancing Django’s form handling:

BetterForm and BetterModelForm classes, which are
subclasses of django.forms.Form and
django.forms.ModelForm, respectively. BetterForm and
BetterModelForm allow subdivision of forms into fieldsets
which are iterable from a template, and also allow definition
of row_attrs which can be accessed from the template to
apply attributes to the surrounding container (<li>, <tr>, or
whatever) of a specific form field.

A ClearableFileField to enhance FileField and
ImageField with a checkbox for clearing the contents of the
field.

An ImageWidget which display a thumbnail of the image
rather than just the filename.

An AutoResizeTextarea widget which auto-resizes to
accommodate its contents.

Installation

Install from PyPI with easy_install or pip:

pip install django-form-utils

To use django-form-utils in your Django project, just include
form_utils in your INSTALLED_APPS setting. django-form-utils does
not provide any models, but including it in INSTALLED_APPS makes the
form_utils template tag library available.

You may also want to override the default form rendering templates by
providing alternate templates at templates/form_utils/better_form.html
and templates/form_utils/form.html.

Dependencies

django-form-utils is tested on Django 1.4 and later and Python 2.6,
2.7, and 3.3. It is known to be incompatible with Python 3.0, 3.1, and 3.2.

Usage

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:

fieldsets

Fieldset definitions are similar to ModelAdmin fieldset definitions:
each fieldset is a two-tuple with a name and an options
dictionary. Valid fieldset options in the dictionary include:

fields

(required) A tuple of field names to display in this fieldset.

classes

A tuple/list of extra CSS classes to apply to the fieldset.

legend

This value, if present, will be the contents of a legend
tag to open the fieldset. If not present the name of the fieldset will
be used (so a value of ” for legend must be used if no legend is
desired.)

description

A string of optional extra text to be displayed
under the legend of the fieldset.

When iterated over, the fieldsets attribute of a BetterForm
(or BetterModelForm) yields Fieldset s. Each Fieldset has
a name attribute, a legend attribute, a classes attribute
(the classes tuple collapsed into a space-separated string), and a
description attribute, and when iterated over yields its
BoundField s.

For backwards compatibility, a BetterForm or BetterModelForm can
still be iterated over directly to yield all of its BoundField s,
regardless of fieldsets.

If you set fieldsets on a BetterModelForm and don’t set either
the fields or exclude options on that form class,
BetterModelForm will set fields to be the list of all fields
present in your fieldsets definition. This avoids problems with
forms that can’t validate because not all fields are listed in a
fieldset. If you manually set either fields or exclude,
BetterModelForm assumes you know what you’re doing and doesn’t
touch those definitions, even if they don’t match the fields listed in
your fieldsets.

For more detailed examples, see the tests in tests/tests.py.

row_attrs

The row_attrs declaration is a dictionary mapping field names to
dictionaries of attribute/value pairs. The attribute/value
dictionaries will be flattened into HTML-style attribute/values
(i.e. {‘style’: ‘display: none’} will become style="display:
none"), and will be available as the row_attrs attribute of the
BoundField.

A BetterForm or BetterModelForm will add a CSS class of
“required” or “optional” automatically to the row_attrs of each
BoundField depending on whether the field is required, and will
also add a CSS class of “error” if the field has errors.

One can also access the fieldset directly if any special casing needs to be
done, e.g.:

{% for field in form.fieldsets.main %}
...
{% endfor %}

django-form-utils also provides a convenience template filter,
render. It is used like this:

{% load form_utils %}
{{ form|render }}

By default, it will check whether the form is a BetterForm, and if
so render it using the template form_utils/better_form.html. If
not, it will render it using the template form_utils/form.html.
(In either case, the form object will be passed to the render
template’s context as form).

The render filter also accepts an optional argument, which is a
template name or comma-separated list of template names to use for
rendering the form:

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

Utility Filters

All the below filters require {% load form_utils %} in the template where
they are used.

These filters are complementary to the useful filters found in the
django-widget-tweaks library for setting arbitrary attributes and classes on
form field widgets; thus such filters are not provided in
django-form-utils.

label

Render a label tag for the given form field by rendering the template
forms/_label.html with the context field (the boundfield object),
id (the form field id attribute), and label_text.

By default the Python-defined label text for the form field is used, but
alternate label text can be provided as an argument to the filter:

{{ form.fieldname|label:"Alternate label" }}

value_text

Display the current value of the given form field in a human-readable way
(i.e. display labels for choice values rather than the internal value). The
current value may be the default value (for first-time rendering of a form) or
the previously-input value (for repeat rendering of a form with
errors). Usage:

{{ form.fieldname|value_text }}

selected_values

Similar to value_text, but for use with multiple-select form fields, and
returns a list of selected values rather than a single string. Usage:

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:

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:

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:

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

Settings

JQUERY_URL

AutoResizeTextarea requires the jQuery Javascript library. By
default, django-form-utils links to the most recent minor version
of jQuery 1.8 available at ajax.googleapis.com (via the URL
http://ajax.googleapis.com/ajax/libs/jquery/1.8/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 STATIC_URL/jquery.min.js. Note
that a relative JQUERY_URL is relative to STATIC_URL.