Tags

The sniplates app consists solely of a custom template tag library.

The load_widgets tag

{% load_widgets alias=template_name ... %}

This tag is used to load widget libraries from templates. You can load more than one library, either at a time, or in separate tags. Because the widgets are stored in the render context, not the context, they are available in child templates even when defined in an inherited template.

If you pass _soft=True any alias that already exists will be skipped. This can be helpful to allow templates to ensure they have the widget sets they need without causing duplicate loads.

Caution

Because of how Django’s templates work, if you are using this in a template which inherits from another, it MUST be inside a {% block %} tag.

Any content in a template starting with {% extends %} which it outside a {% block %} tag is ignored and never rendered.

The widget tag

{% widget 'alias:block_name' ...  [as asvar] %}

Renders the specified widget with the current context. You can provide extra values to override, just like with {% include %}. Currently does not support the only argument.

The name is composed of the alias specified in the load_widgets tag, and the name of the block in that template, joined with a ‘:’. If you use an “empty” alias, the block will be searched for in the current template (and any templates it extends). This form can be used without a load_widgets tag.

You may use the as form of the tag to store the result of the block in the context variable you supply instead of rendering it in the template.

The form_field tag

{% form_field form.fieldname [widget=] [alias=form] .... %}

Works like the widget tag, but extracts useful attributes of the field into the context.

The values are extracted using a FieldExtractor class, selected according to the form field class.

Any extra keyword arguments you pass to the field tag will overwrite values of the same name.

If widget is not specified, it will be determined from the first found of any block matching the following patterns:

  • {field}_{widget}_{name}
  • {field}_{name}
  • {widget}_{name}
  • {field}_{widget}
  • {name}
  • {widget}
  • {field}

Note

These will be looked up within the alias block set “form”, unless the alias keyword is passed to override it.

By way of example, given the following form:

from django.forms import Form, CharField, TextInput

class MyForm(Form):
    example_field = CharField(widget=TextInput)

using {% form_field myform.example_field %} without widget would look for a block with one of the following names, in the following order:

  • CharField_TextInput_example_field
  • CharField_example_field
  • TextInput_example_field
  • CharField_TextInput
  • example_field
  • TextInput
  • CharField

Values from BoundField

The following values are take from the BoundField:

  • css_classes
  • errors
  • field
  • form
  • help_text
  • html_name
  • id_for_label
  • label
  • name
  • value

If the field is a FileField, an extra value file will be added, which contains the size and url attributes of the current file. If it’s an ImageField, the width and height may also be avaialble.

Values from Field

And these from the Field itself:

  • choices
  • widget
  • required

If the field is a ChoicesField, an extra value display will be added, which is the display value for the current value, if any.

The nested_widget tag

{% nested_widget widgetname .... [as asvar] %}
    ...
{% endnested %}

This tag is a container block that will render its contents, and pass the output to its widget as ‘content’.

An example use of this is for wrapping fields in a fieldset template:

{% block fieldset %}
    <fieldset>
    {% if caption %}<caption>{{ caption }}</caption>{% endif %}
    {{ content }}
{% endblock %}

And would be used as follows:

{% nested_widget 'form:fieldset' caption="About You" %}
    {% form_field form.first_name %} <br>
    {% form_field form.last_name %}
{% endnested %}

This tag also supports storing the result in a context variable of your choice instead of rendering immediately.

The reuse tag

{% reuse blockname ... %}

Much like the widget tag, this re-renders an existing block tag in situ. However, instead of looking for the block in a loaded widget library, it searches the current template. This allows templates extending a base to define reusable “macro” blocks, without having to load a separate widget set.

As with other tags, you can extend the context by passing keyword arguments.

Note

This tag only works in templates that {% extends %} another template.