Advanced usage¶
Most of the advanced features are also demo’ed in the examples project you can find
in the django-tapeforms codebase. Go to the examples
directory.
Note
Most class properties have a corresponding method to access the value. This helps in cases where you might want to manipulate the response in a more dynamic way. If you’re unsure what can be changed, refer to the API Reference.
Overriding layout templates¶
In the context of django-tapeforms the layout template is the outer part of a form which contains the non field errors and the loop over the fields to render.
If you want to override the template used for rendering the form layout, the best way is defining a property on the form class:
class MyForm(TapeformMixin, forms.Form):
layout_template = 'another-form-template.html'
field1 = forms.CharField()
You are done. The form
template tag will pick the new
defined template for rendering.
If you need to select the layout template on other things like the instance
in ModelForm
, you can overwrite the get_layout_template
method.
Overriding field templates¶
In the context of django-tapeforms the field template is the part of a form which contains the label, widget, errors and help text for a certain field.
If you want to override the template used for rendering fields, there is more than one way.
When the template should be changed for all fields, you can simply set the
field_template
property.
class MyForm(TapeformMixin, forms.Form):
field_template = 'my-field-template.html'
field1 = forms.CharField()
The formfield
template tag will now pick the new
defined template for rendering the fields.
You can define the templates used for field rendering in a more specific way.
class MyForm(TapeformMixin, forms.Form):
field_template_overrides = {
'field1': 'my-field1-template.html',
forms.IntegerField: 'my-number-template.html',
}
field1 = forms.CharField()
field2 = forms.IntegerField()
field3 = forms.IntegerField()
As you can see, you can override the templates for fields based on the field name and also based on the field class.
If you need to select the field template depending on other things, you can
overwrite the get_field_template
method. It receives a
BoundField
instance for the template selection.
Overriding widget templates¶
In the context of django-tapeforms and Django itself, the widget template is used for the actual input element.
If you want to override the template used for rendering widgets, you can change
the template_name
by subclassing the widget classes but this requires much effort.
To make this easier, the TapeformMixin provided a helper to set the widget
template_name
. The matching is done using the field name and widget class.
class MyForm(TapeformMixin, forms.Form):
widget_template_overrides = {
'field1': 'my-field1-widget-template.html',
forms.NumberInput: 'my-number-widget-template.html',
}
field1 = forms.CharField()
field2 = forms.IntegerField()
field3 = forms.IntegerField()
If you need to select the widget template based on other things, you can overwrite
the get_widget_template
method. It receives the
field name as str
and the Field
instance.
Changing the applied CSS classes¶
When you render the form using django-tapeforms you can apply CSS classes to the field container, label and widget.
This is done using the properties field_container_css_class
,
field_label_css_class
and widget_css_class
.
For all CSS class properties, there are methods to override the applied CSS class per field. Please refer to the API Reference to learn what arguments are passed to the CSS class methods.
Adding CSS classes to invalid field¶
When you render the form using django-tapeforms, you can also apply additional CSS classes to the label and widget of a field which has errors.
This is done using the properties field_label_invalid_css_class
and
widget_invalid_css_class
.
If you need to set more attributes to the widget when there are errors, you can
overwrite the apply_widget_invalid_options
method. It
receives the field name as str
.