Package: django-widgets-improved
# django-widgets-improved[![Build Status](https://travis-ci.org/simhnna/django-widgets-improved.svg?branch=master)](https://travis-ci.org/simhnna/django-widgets-improved)Tweak the form field rendering in templates, not in python-levelform definitions. Altering CSS classes and HTML attributes is supported.That should be enough for designers to customize field presentation (usingCSS and unobtrusive javascript) without touching python code.This project is a fork of the unmaintained [django-widget-tweaks](https://github.com/jazzband/django-widget-tweaks) repository.It is a drop-in replacement. Just unintall django-widget-tweaks and install this instead.## InstallationYou can get Django Widget Tweaks by using pip::$ pip install django-widgets-improvedTo enable `widget_tweaks` in your project you need to add it to `INSTALLED_APPS` in your projects`settings.py` file:```INSTALLED_APPS = [...'widget_tweaks',...]```## UsageThis app provides two sets of tools that may be used together or standalone:1. a `render_field` template tag for customizing form fields by using anHTML-like syntax.2. several template filters for customizing form field HTML attributes and CSSclassesThe `render_field` tag should be easier to use and should make form fieldcustomizations much easier for designers and front-end developers.The template filters are more powerful than the `render_field` tag, but theyuse a more complex and less HTML-like syntax.### render_fieldThis is a template tag that can be used as an alternative to aforementionedfilters.  This template tag renders a field using a syntax similar to plainHTML 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 possibleto 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 couldset a default CSS error class on all fields rendered by`{% render_field %}`.### attrAdds 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_classAdds CSS class to field element. Split classes by whitespace in order to addseveral 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_dataSets HTML5 data attribute ( http://ejohn.org/blog/html-5-data-attributes/ ).Useful for unobtrusive javascript. It is just a shortcut for 'attr' filterthat 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_attrAppends 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 thatadds values to the 'class' attribute.### add_error_classThe same as 'add_class' but adds css class only if validation failed forthe 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_attrThe same as 'attr' but sets an attribute only if validation failed forthe field (field.errors is not empty). This can be useful when dealingwith 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 returnfield 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>```## Filter chainingThe order django-widget-tweaks filters apply may seem counter-intuitive(leftmost filter wins):```{{ form.simple|attr:"foo:bar"|attr:"foo:baz" }}```returns:```<input foo="bar" type="text" name="simple" id="id_simple" />```It is not a bug, it is a feature that enables creating reusable templateswith overridable defaults.Reusable field template example:```{# inc/field.html #}{% load widget_tweaks %}<div>{{ field|attr:"foo:default_foo" }}</div>```Example usage:```{# my_template.html #}{% load widget_tweaks %}<form method='POST' action=''> {% csrf_token %}{% include "inc/field.html" with field=form.title %}{% include "inc/field.html" with field=form.description|attr:"foo:non_default_foo" %}</form>```With 'rightmost filter wins' rule it wouldn't be possible to override`|attr:"foo:default_foo"` in main template.## ContributingIf you've found a bug, implemented a feature or have a suggestion,do not hesitate to contact me, fire an issue or send a pull request.* Source code: https://github.com/simhnna/django-widgets-improved/* Bug tracker: https://github.com/simhnna/django-widgets-improved/issues## TestingMake sure you have [tox](http://tox.testrun.org/) installed, then type `tox`from anywhere within the repository.# Changelog## 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.