django-form-utils 1.0.3

依赖项

django-form-utils已在Django 1.4及更高版本和Python 2.6、2.7和3.3上进行了测试。已知与Python 3.0、3.1和3.2不兼容。

ImageWidget需要Python Imaging Library。 sorl-thumbnail或easy-thumbnails是可选的，但没有它将显示完整大小的图像而不是缩略图。默认缩略图大小为200px x 200px。

AutoResizeTextarea需要jQuery（默认使用Google提供的版本；请参阅JQUERY_URL）。

BetterForm

简单地将您的表单类从form_utils.forms.BetterForm继承（而不是django.forms.Form），或将模型表单类从form_utils.forms.BetterModelForm继承，并定义内部Meta类的fieldsets和/或row_attrs属性

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

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

{% load form_utils %}

{{ form|render }}

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

实用过滤器

以下所有过滤器都需要在它们使用的模板中包含 {% load form_utils %}。

这些过滤器是 django-widget-tweaks 库中发现的实用过滤器的补充，用于在表单字段小部件上设置任意属性和类；因此，django-form-utils 中没有提供此类过滤器。

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

{{ form.fieldname|value_text }}

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

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

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

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

ClearableFileField

是django.forms.FileField的替代品，它具有一个复选框来清除现有文件的字段。像使用其他表单字段类一样使用

from django import forms

from form_utils.fields import ClearableFileField

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

ClearableFileField还接受两个关键字参数，file_field和template。

file_field是实际用于表示文件部分的实例化字段。例如，如果您想使用ClearableFileField来替换ImageField，并且想使用ImageWidget，您可以这样操作

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

默认情况下，file_field是一个普通的forms.FileField，带有默认的forms.FileInput控件。

template是一个字符串，定义了如何相对于彼此显示FileField（或替代file_field）和清除复选框。模板字符串应包含变量插值标记%(input)s和%(checkbox)s。默认值是%(input)s 清除：%(checkbox)s。

要在管理界面中使用ClearableFileField，只需从form_utils.admin.ClearableFileFieldsAdmin继承您的管理选项类，而不是从django.contrib.admin.ModelAdmin继承，该模型中的所有FileField和ImageField将自动变为可清除的（同时仍然使用它们原本会使用的相同的文件/图像字段/控件，包括在formfield_overrides中提供的任何覆盖）。

ClearableImageField

form_utils.fields.ClearableImageField只是一个将默认文件字段设置为forms.ImageField而不是forms.FileField的ClearableFileField。

ImageWidget

这是一个用于表示ImageField的控件，它包括字段中当前图像的缩略图，而不仅仅是文件的名称。（如果安装了sorl-thumbnail，则提供缩略图；否则显示全尺寸图像）。使用时，只需将其作为ImageField的控件类传递即可

from django import forms

from form_utils.widgets import ImageWidget

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

ImageWidget接受一个关键字参数，template。这是一个定义图像缩略图和文件输入控件相对于彼此如何渲染的字符串。模板字符串应包含变量插值标记%(input)s和%(image)s。默认值是%(input)s<br />%(image)s。例如，要将图像显示在输入上方而不是下方

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

要在管理界面中使用，请使用formfield_overrides将ImageField的默认控件设置为

from django.db import models

from form_utils.widgets import ImageWidget

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

AutoResizeTextarea

只需导入小部件并将其分配给表单字段

from django import forms
from form_utils.widgets import AutoResizeTextarea

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

或者，在您的 ModelAdmin 子类中使用 formfield_overrides

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

还有一个 InlineAutoResizeTextarea，它提供适合在表格内联中使用的小型默认尺寸。

1.0.3 (2015-08-25)

• 修复了与Django 1.9的兼容性。修复了GH-12。

1.0.2 (2014-09-08)

• 修复了与Django 1.7的兼容性。修复了BB-20和GH-8。

1.0.1 (2013-10-19)

• 移除了无效的 python_2_unicode_compatible 使用，这破坏了 https://github.com/django/django/commit/589dc49e129f63801c54c15e408c944a345b3dfe。感谢ocZio的报告。

• 修复了表单Meta类的继承。感谢chmodas。修复了BB-16。

1.0 (2013.08.22)

• 添加了Python 3.3兼容性。感谢chmodas!（合并了GH-5。）

0.3.1 (2013.06.25)

• 从 ImageWidget.render 调用 FileInput.render，确保在HTML中不输出任何值。修复了GH-4。感谢Aron Griffis。

0.3.0 (2013.06.04)

• 向后不兼容：将模板标签库的名称从 form_utils_tags 更改为 form_utils。

• 向后不兼容：删除了 FORM_UTILS_MEDIA_URL 设置，并更新为在整个项目中使用 STATIC_URL 而不是 MEDIA_URL。

• 将“error”类添加到具有错误的字段的row_attrs中。感谢Aron Griffis。

• 停止对Django 1.4之前和Python 2.6之前版本的支持。

0.2.0 (2011.01.28)

• 为ImageWidget添加宽度和高参数。

• 使ImageWidget对图像检测后端友好，不直接使用PIL。修复了问题#7。

• 修复了默认模板对单选/复选框输入标签的渲染。

• 修复了ClearableFileField绑定表单的错误重新显示。

• 如果未手动设置 fields 或 exclude，则自动将 BetterModelForm 上的 fields 设置为存在于 fieldsets 中的字段列表。

• 更新为允许对fieldsets进行 __getitem__ 访问。

0.1.8 (2010.03.16)

• 将PIL导入限制在ImageWidget中

• 添加了AutoResizeTextarea

0.1.7 (2009.12.02)

• 修复了admin.py中的ClearableFileField导入。

0.1.6 (2009.11.24)

• 为ImageWidget和ClearableFileField添加了文档和测试。

• 将ClearableFileField从widgets.py移动到fields.py。

• 将doctests转换为unittests。

0.1.5 (2009.11.10)

• 添加了fieldset类（以前仅存在于文档中）。

0.1.0 (2009-03-26)

• 首次公开发布。