1. dwaiter
  2. django-goodfields


django-goodfields / README.markdown


Customizing the markup of Django forms is a pain. django-goodfields tries to make it hurt less by making it easy to render form fields and add inline validation.


Field rendering only:

Inline validation:


With Pip

pip install -e hg+http://bitbucket.org/dwaiter/django-goodfields@stable#egg=django-goodfields

# or...

pip install -e git://github.com/dwaiter/django-goodfields@stable#egg=django-goodfields

Now symlink (or copy) the templates and media into your project:

ln -s /path/to/django-goodfields/goodfields/templates/goodfields/ templates/goodfields
ln -s /path/to/django-goodfields/goodfields/media/goodfields/ media/goodfields

Or From Source

Get the code:

hg clone http://bitbucket.org/dwaiter/django-goodfields/
hg update stable

# or...

git clone git://github.com/dwaiter/django-goodfields/
git checkout stable


cd django-goodfields
python setup.py install

Now symlink the templates and media into your project:

ln -s /path/to/django-goodfields/goodfields/templates/goodfields/ templates/goodfields
ln -s /path/to/django-goodfields/goodfields/media/goodfields/ media/goodfields

Usage (Field Rendering)

Use the {% goodfield [form.field] [field type] %} template tag to render fields in your form:

<h1>Sign up for free!</h1>

<form action="" method="post">

    {% load goodfields %}
    {% goodfield form.username text %}
    {% goodfield form.first_name text %}
    {% goodfield form.last_name text %}
    {% goodfield form.password password %}

    {{ form.non_field_errors }}
    <input type="submit" value="Sign Up" />

The default field templates included with django-goodfields produce HTML that looks similar to this:

<div class="field" id="id_username-container">
    <label for="id_username">Username</label>
    <input type="text" class="text" id="id_username" 
           value="" />

Feel free to customize the templates to look however you prefer. Each field type (text, password, radio, etc) has its own template in templates/goodfields. You can add new field types by adding new templates.

django-goodfields will use the label attribute of the form field to create the <label> element by default. You can specify a custom label for a particular rendering of a field by using label "new label" in the {% goodfield %} tag, like this:

<form action="" method="post">
    {% load goodfields %}
    {% goodfield form.password password label "Pick a secure password!" %}
    <input type="submit" value="Sign Up" />

Usage (Inline Validation)

django-goodfields can automatically add some sane inline validation to rendered form fields by looking at attributes of your Django fields.

To use this you'll first need to include the jQuery and LiveValidation libraries somewhere in your pages.