django-widget-tweaks 1.4.1

render_field

This is a template tag that can be used as an alternative to aforementioned filters. This template tag renders a field using a syntax similar to plain HTML attributes.

Example:

{% load widget_tweaks %}

<!-- change input type (e.g. to HTML5) -->
{% render_field form.search_query type="search" %}

<!-- add/change several attributes -->
{% render_field form.text rows="20" cols="20" title="Hello, world!" %}

<!-- append to an attribute -->
{% render_field form.title class+="css_class_1 css_class_2" %}

<!-- template variables can be used as attribute values -->
{% render_field form.text placeholder=form.text.label %}

For fields rendered with {% render_field %} tag it is possible to set error class and required fields class by using WIDGET_ERROR_CLASS and WIDGET_REQUIRED_CLASS template variables:

{% with WIDGET_ERROR_CLASS='my_error' WIDGET_REQUIRED_CLASS='my_required' %}
    {% render_field form.field1 %}
    {% render_field form.field2 %}
    {% render_field form.field3 %}
{% endwith %}

You can be creative with these variables: e.g. a context processor could set a default CSS error class on all fields rendered by {% render_field %}.

attr

Adds or replaces any single html atribute for the form field.

Examples:

{% load widget_tweaks %}

<!-- change input type (e.g. to HTML5) -->
{{ form.search_query|attr:"type:search" }}

<!-- add/change several attributes -->
{{ form.text|attr:"rows:20"|attr:"cols:20"|attr:"title:Hello, world!" }}

<!-- attributes without parameters -->
{{ form.search_query|attr:"autofocus" }}

add_class

Adds CSS class to field element. Split classes by whitespace in order to add several classes at once.

Example:

{% load widget_tweaks %}

<!-- add 2 extra css classes to field element -->
{{ form.title|add_class:"css_class_1 css_class_2" }}

set_data

Sets HTML5 data attribute ( http://ejohn.org/blog/html-5-data-attributes/ ). Useful for unobtrusive javascript. It is just a shortcut for ‘attr’ filter that prepends attribute names with ‘data-’ string.

Example:

{% load widget_tweaks %}

<!-- data-filters:"OverText" will be added to input field -->
{{ form.title|set_data:"filters:OverText" }}

append_attr

Appends atribute value with extra data.

Example:

{% load widget_tweaks %}

<!-- add 2 extra css classes to field element -->
{{ form.title|append_attr:"class:css_class_1 css_class_2" }}

‘add_class’ filter is just a shortcut for ‘append_attr’ filter that adds values to the ‘class’ attribute.

add_error_class

The same as ‘add_class’ but adds css class only if validation failed for the field (field.errors is not empty).

Example:

{% load widget_tweaks %}

<!-- add 'error-border' css class on field error -->
{{ form.title|add_error_class:"error-border" }}

add_error_attr

The same as ‘attr’ but sets an attribute only if validation failed for the field (field.errors is not empty). This can be useful when dealing with accessibility:

{% load widget_tweaks %}

<!-- add aria-invalid="true" attribute on field error -->
{{ form.title|add_error_attr:"aria-invalid:true" }}

field_type and widget_type

'field_type' and 'widget_type' are template filters that return field class name and field widget class name (in lower case).

Example:

{% load widget_tweaks %}

<div class="field {{ field|field_type }} {{ field|widget_type }} {{ field.html_name }}">
    {{ field }}
</div>

Output:

<div class="field charfield textinput name">
    <input id="id_name" type="text" name="name" maxlength="100" />
</div>

Testing

Make sure you have tox installed, then type

tox

from the source checkout.

1.4.1 (2015-06-29)

• fixed a regression in django-widget-tweaks v1.4 (the field is no longer deep copied).

1.4 (2015-06-27)

• Django 1.7, 1.8 and 1.9 support;

• setup.py is switched to setuptools;

• testing improvements;

• Python 3.4 support is added;

• Python 2.5 is not longer supported;

• bitbucket repository is no longer supported (development is moved to github).

1.3 (2013-04-05)

• added support for WIDGET_ERROR_CLASS and WIDGET_REQUIRED_CLASS template variables that affect {% render_field %}.

1.2 (2013-03-23)

• new add_error_attr template filter;

• testing improvements.

1.1.2 (2012-06-06)

• support for template variables is added to render_field tag;

• new field_type and widget_type filters.

1.1.1 (2012-03-22)

• some issues with render_field tag are fixed.

1.1 (2012-03-22)

• render_field template tag.

1.0 (2012-02-06)

• filters return empty strings instead of raising exceptions if field is missing;

• test running improvements;

• python 3 support;

• undocumented ‘behave’ filter is removed.

0.3 (2011-03-04)

• add_error_class filter.

0.2.1 (2011-02-03)

• Attributes customized in widgets are preserved;

• no more extra whitespaces;

• tests;

0.1 (2011-01-12)

Initial release.