DOCSEARCHbyAlgolia
Submit Docs

django-widget-tweaks

repository·master·Indexed 24 days ago

https://github.com/jazzband/django-widget-tweaks

A Django template library that allows developers to customize form field rendering, such as CSS classes and HTML attributes, directly within templates rather than in Python code. It provides the {% render_field %} template tag and a variety of filters including attr, add_class, set_data, and append_attr to manipulate form fields and their labels.

Tokens
1.2K
Snippets
4
Records
5
Agent score
30%

What's inside django-widget-tweaks

  1. Handle MultiWidgets (e.g. RadioSelect)

    master

    Fields that render as a MultiWidget (composed of multiple subwidgets, such as a ChoiceField using RadioSelect) require a loop to apply tags or filters to each individual widget.

    {% load widget_tweaks %}

{% for widget in form.choice %}
    {{ widget|add_class:"css_class_1 css_class_2" }}
{% endfor %}

  2. Render form error messages

    master

    You can render different types of errors manually in your templates:

    1. Field-specific errors: Iterate over field.errors.
    2. Non-field related errors: Check form.non_field_errors.
    3. All errors: Use form.errors to display all errors.
    {% load widget_tweaks %}

<!-- Field errors -->
{% for error in field.errors %}
    <span class="text-danger">{{ error }}</span>
{% endfor %}

<!-- Non-field errors -->
{% if form.non_field_errors %}
    <span class="text-danger">{{ form.non_field_errors }}</span>
{% endif %}

<!-- All errors -->
{{ form.errors }}

  4. Use the render_field template tag

    master

    The {% render_field %} tag allows you to customize form fields using an HTML-like syntax. It is often easier for designers than using individual filters.

    Key capabilities:

    • Change input types (e.g., type="search").
    • Add or change multiple attributes (e.g., rows, cols, title).
    • Append to existing attributes using += (e.g., class+="css_class_1").
    • Use template variables as attribute values.
    • Use double colons :: for specific syntax requirements (like Vue.js v-bind::).

    To control error and required field classes globally for render_field, use the WIDGET_ERROR_CLASS and WIDGET_REQUIRED_CLASS template variables within a {% with %} block.

    {% load widget_tweaks %}

<!-- change input type -->
{% 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 as values -->
{% render_field form.text placeholder=form.text.label %}

<!-- double colon syntax -->
{% render_field form.search_query v-bind::class="{active:isActive}" %}

<!-- setting error/required classes via context variables -->
{% with WIDGET_ERROR_CLASS='my_error' WIDGET_REQUIRED_CLASS='my_required' %}
    {% render_field form.field1 %}
{% endwith %}

  5. Customize fields with template filters

    master

    Template filters provide powerful ways to manipulate HTML attributes and CSS classes on form fields. Note that when chaining filters, the leftmost filter wins, allowing you to override defaults in reusable templates.

    Available filters:

    • attr: Adds or replaces a single HTML attribute (syntax: attr:"name:value").
    • add_class: Adds CSS classes to the field element.
    • set_data: Shortcut for attr that prepends data- to the attribute name.
    • append_attr: Appends a value to an existing attribute (e.g., append_attr:"class:extra_class").
    • remove_attr: Removes a specific HTML attribute.
    • add_label_class: Adds CSS classes to the field's label.
    • add_error_class: Adds a CSS class only if the field has validation errors.
    • add_error_attr: Adds an attribute only if the field has validation errors.
    • add_required_class: Adds a CSS class only if the field is required.
    • field_type: Returns the field class name (lowercase).
    • widget_type: Returns the widget class name (lowercase).