Package: django-widget-tweaks
Tweak the form field rendering in templates, not in python-level
form definitions. Altering CSS classes and HTML attributes is supported.That should be enough for designers to customize field presentation (using
CSS and unobtrusive javascript) without touching python code.License is MIT.InstallationYou can get Django Widget Tweaks by using pip:$ pip install django-widget-tweaksTo enablewidget_tweaksin your project you need to add it toINSTALLED_APPSin your projectssettings.pyfile:INSTALLED_APPS+=['widget_tweaks',]UsageThis app provides two sets of tools that may be used together or standalone:arender_fieldtemplate tag for customizing form fields by using an
HTML-like syntax.several template filters for customizing form field HTML attributes and CSS
classesTherender_fieldtag should be easier to use and should make form field
customizations much easier for designers and front-end developers.The template filters are more powerful than therender_fieldtag, but they
use a more complex and less HTML-like syntax.render_fieldThis 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:{%loadwidget_tweaks%}<!-- change input type (e.g. to HTML5) -->{%render_fieldform.search_querytype="search"%}<!-- add/change several attributes -->{%render_fieldform.textrows="20"cols="20"title="Hello, world!"%}<!-- append to an attribute -->{%render_fieldform.titleclass+="css_class_1 css_class_2"%}<!-- template variables can be used as attribute values -->{%render_fieldform.textplaceholder=form.text.label%}<!-- double colon -->{%render_fieldform.search_queryv-bind::class="{active:isActive}"%}For fields rendered with{% render_field %}tag it is possible
to set error class and required fields class by usingWIDGET_ERROR_CLASSandWIDGET_REQUIRED_CLASStemplate variables:{%withWIDGET_ERROR_CLASS='my_error'WIDGET_REQUIRED_CLASS='my_required'%}{%render_fieldform.field1%}{%render_fieldform.field2%}{%render_fieldform.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 %}.attrAdds or replaces any single html attribute for the form field.Examples:{%loadwidget_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"}}<!-- attributes with double colon Vuejs output: v-bind:class="{active:ValueEnabled}" -->{{form.search_query|attr:"v-bind::class:{active:ValueEnabled}"}}add_classAdds CSS class to field element. Split classes by whitespace in order to add
several classes at once.Example:{%loadwidget_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’ filter
that prepends attribute names with ‘data-’ string.Example:{%loadwidget_tweaks%}<!-- data-filters:"OverText" will be added to input field -->{{form.title|set_data:"filters:OverText"}}append_attrAppends attribute value with extra data.Example:{%loadwidget_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.remove_attrRemoves any single html attribute for the form field.Example:{%loadwidget_tweaks%}<!-- removes autofocus attribute from field element -->{{form.title|remove_attr:"autofocus"}}add_label_classThe same asadd_classbut adds css class to form labels.Example:{%loadwidget_tweaks%}<!-- add 2 extra css classes to field label element -->{{form.title|add_label_class:"label_class_1 label_class_2"}}add_error_classThe same as ‘add_class’ but adds css class only if validation failed for
the field (field.errors is not empty).Example:{%loadwidget_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 for
the field (field.errors is not empty). This can be useful when dealing
with accessibility:{%loadwidget_tweaks%}<!-- add aria-invalid="true" attribute on field error -->{{form.title|add_error_attr:"aria-invalid:true"}}add_required_classThe same as ‘add_error_class’ adds css class only for required field.Example:{%loadwidget_tweaks%}<!-- add 'is-required' css class on field required -->{{form.title|add_required_class:"is-required"}}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:{%loadwidget_tweaks%}<divclass="field{{field|field_type}}{{field|widget_type}}{{field.html_name}}">{{field}}</div>Output:<divclass="field charfield textinput name"><inputid="id_name"type="text"name="name"maxlength="100"/></div>Mixing render_field and filtersThe render_field tag and filters mentioned above can be mixed.Example:{%render_fieldform.category|append_attr:"readonly:readonly"type="text"placeholder="Category"%}returns:<inputname="category"placeholder="Profession"readonly="readonly"type="text">Filter chainingThe order django-widget-tweaks filters apply may seem counter-intuitive
(leftmost filter wins):{{form.simple|attr:"foo:bar"|attr:"foo:baz"}}returns:<inputfoo="bar"type="text"name="simple"id="id_simple"/>It is not a bug, it is a feature that enables creating reusable templates
with overridable defaults.Reusable field template example:{# inc/field.html #}{%loadwidget_tweaks%}<div>{{field|attr:"foo:default_foo"}}</div>Example usage:{# my_template.html #}{%loadwidget_tweaks%}<formmethod='POST'action=''>{%csrf_token%}{%include"inc/field.html"withfield=form.title%}{%include"inc/field.html"withfield=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/jazzband/django-widget-tweaks/Bug tracker:https://github.com/jazzband/django-widget-tweaks/issuesTestingMake sure you havetoxinstalled, then typetoxfrom the source checkout.NOT SUPPORTEDMultiWidgets: SplitDateTimeWidget, SplitHiddenDateTimeWidgetChanges1.5.0 (2023-08-25)Add Django 4.2 support.Add Django 4.1 support.Drop Django 4.0 support.Drop Django 2.2 support.Add Python 3.11 support.Drop Python 3.7 support.1.4.12 (2022-01-13)Set minimum required Python version to 3.7.Add better documentation syntax highlighting.Adjust build settings and stop building deprecated universal Python 2 wheels.1.4.11 (2022-01-08)Add support for Django 4.0Drop support for Django 3.0 and 3.1Add support for Python 3.10Drop support for Python 3.61.4.9 (2021-09-02)Add support for Django 3.2Move to GitHub Actions.Drop support for Django 1.11.Add support for Python 3.9.1.4.8 (2020-03-12)Fix Release version1.4.7 (2020-03-10)Fix Travis deployment to Jazzband site1.4.6 (2020-03-09)Feature remove attribute from fieldAdded documentation for remove_attr featureReformat code with black for PEP8 compatibilityMore consistent tox configurationadding a new templatetag, unittest and documentationDeprecate Python 2.7 supportUse automatic formatting for all files1.4.5 (2019-06-08)Fix rST formatting errors.1.4.4 (2019-06-05)Add support for type attr.Add Python 3.7 and drop Python 3.3 support.Add support for double colon syntax.1.4.3 (2018-09-6)Added add_label_class filter for CSS on form labelsRemoved compatibility code for unsupported Django versionsFixed support for non-value attributes in Django < 1.8Support non-value attributes in HTML5 by setting their value to True1.4.2 (2018-03-19)update readme to make installation more clearshallow copy field before updating attributesdrop Python 2.6 and Python 3.2 supportalways cast the result of render to a stringfix import for django >= 2.0moved to jazzband1.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 forWIDGET_ERROR_CLASSandWIDGET_REQUIRED_CLASStemplate variables that affect{% render_field %}.1.2 (2013-03-23)newadd_error_attrtemplate filter;testing improvements.1.1.2 (2012-06-06)support for template variables is added torender_fieldtag;newfield_typeandwidget_typefilters.1.1.1 (2012-03-22)some issues withrender_fieldtag are fixed.1.1 (2012-03-22)render_fieldtemplate 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_classfilter.0.2.1 (2011-02-03)Attributes customized in widgets are preserved;no more extra whitespaces;tests;0.1 (2011-01-12)Initial release.