Source

django-form-utils / README.rst

Carl Meyer 4890e74 













Carl Meyer 2900635 
Carl Meyer 211c43c 




Carl Meyer 4890e74 






Carl Meyer 4d674e3 
Carl Meyer 2900635 
Carl Meyer 4d674e3 
Carl Meyer 211c43c 
Carl Meyer 4890e74 


















Carl Meyer ca44782 

Carl Meyer 4890e74 

Martins Grunskis b6253ad 


Carl Meyer 4890e74 
Carl Meyer 4d674e3 


Carl Meyer 4890e74 
Carl Meyer 89db8f5 
Carl Meyer 4890e74 
Martins Grunskis b6253ad 
Carl Meyer ca44782 
Carl Meyer 4d674e3 
Carl Meyer 4890e74 



Carl Meyer 4d674e3 


Carl Meyer 4890e74 









Carl Meyer e77957b 

Carl Meyer 4890e74 
Carl Meyer e77957b 
Carl Meyer 4890e74 


Carl Meyer 4d674e3 
Carl Meyer 4890e74 































Carl Meyer 523b4b4 









Carl Meyer 4890e74 


Carl Meyer 4d674e3 
Carl Meyer 4890e74 







Aron Griffis fc604c3 



Carl Meyer 4890e74 

Carl Meyer 4d674e3 
Carl Meyer 4890e74 




























Rob Hudson 59576da 






Carl Meyer 4890e74 


Carl Meyer d84d4a4 

Carl Meyer 4890e74 













Carl Meyer 211c43c 


























































































Carl Meyer 4890e74 




























































































Carl Meyer 4d674e3 































Carl Meyer 2900635 

Carl Meyer 4d674e3 




Carl Meyer aeaae95 
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
=================
django-form-utils
=================

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

    1. ``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.

    2. A variety of small template filters that are useful for giving template
       authors more control over custom rendering of forms without needing to
       edit Python code: `label`_, `value_text`_, `selected_values`_,
       `optional`_, `is_checkbox`_, and `is_multiple`_.

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

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

    4. 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.

`ImageWidget`_ requires the `Python Imaging Library`_.
`sorl-thumbnail`_ or `easy-thumbnails`_ is optional, but without it
full-size images will be displayed instead of thumbnails. The default
thumbnail size is 200px x 200px.

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

.. _Django: http://www.djangoproject.com/
.. _Python: http://www.python.org/
.. _sorl-thumbnail: http://pypi.python.org/pypi/sorl-thumbnail
.. _easy-thumbnails: http://pypi.python.org/pypi/easy-thumbnails
.. _Python Imaging Library: http://python-imaging.github.io/
.. _jQuery: http://www.jquery.com/

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::

    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'}}

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.

Rendering
'''''''''

A possible template for rendering a ``BetterForm``::

    {% 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 %}


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``.

.. _django-widget-tweaks: http://pypi.python.org/pypi/django-widget-tweaks


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::

    <ul>
      {% for selected_value in form.multiselect|selected_values %}
        <li>{{ selected_value }}</li>
      {% endfor %}
    </ul>


optional
''''''''

Return ``True`` if the given field is optional, ``False`` if it is
required. Sample usage::

    {% if form.fieldname|optional %}(optional){% endif %}


is_checkbox
'''''''''''

Return ``True`` if the given field's widget is a ``CheckboxInput``, ``False``
otherwise. Sample usage::

    {% if form.fieldname|is_checkbox %}
      {{ form.fieldname }}
      {{ form.fieldname|label }}
    {% else %}
      {{ form.fieldname|label }}
      {{ form.fieldname }}
    {% endif %}


is_multiple
'''''''''''

Return ``True`` if the given field is a ``MultipleChoiceField``, ``False``
otherwise. Sample usage::

    {% if form.fieldname|is_multiple %}
      {% for value in form.fieldname|selected_values %}{{ value }} {% endif %}
    {% else %}
      {{ form.fieldname|value_text }}
    {% endif %}



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}}

.. _sorl-thumbnail: http://pypi.python.org/pypi/sorl-thumbnail

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.

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``.
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.