django-goodfields / README.markdown

django-goodfields

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.

Requirements

Field rendering only:

Inline validation:

Installation

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 media into your project:

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

Install:

cd django-goodfields
python setup.py install

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

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" />
</form>

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" 
           name="username"
           value="" />
</div>

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" />
</form>

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.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.