Mixins

class tapeforms.mixins.TapeformLayoutMixin

Bases: object

Mixin to render a form of fieldset as HTML.

layout_template = None

Layout template to use when rendering the form. Optional.

get_layout_template(template_name=None)

Returns the layout template to use when rendering the form to HTML.

Preference of template selection:

1. Provided method argument template_name

2. Form class property layout_template

3. Globally defined default template from defaults.LAYOUT_DEFAULT_TEMPLATE

Parameters:

template_name – Optional template to use instead of other configurations.

Returns:

Template name to use when rendering the form.

get_layout_context()

Returns the context which is used when rendering the form to HTML.

The generated template context will contain the following variables:

• form: Form instance

• errors: ErrorList instance with non field errors and hidden field errors

• hidden_fields: All hidden fields to render.

• visible_fields: All visible fields to render.

Returns:

Template context for form rendering.

as_tapeform()

Shortcut to render the form as a “tapeform” without including the tapeforms templatetags. Behaves similar to as_p and as_table.

class tapeforms.mixins.TapeformMixin(*args, **kwargs)

Bases: TapeformLayoutMixin

Mixin to extend the forms capability to render itself as HTML output. (using the template tags provided by tapeforms).

field_template = None

Field template to use when rendering a bound form-field. Optional.

field_template_overrides = None

A dictionary of form-field names and/or form-field classes to override the field template which is used when rendering a certain form-field. Optional.

field_container_css_class = 'form-field'

The CSS class to apply to the form-field container element.

field_label_css_class = None

CSS class to append to the rendered field label tag. Optional.

field_label_invalid_css_class = None

An additional CSS class to append to the rendered field label tag when the field has errors. Optional.

widget_template_overrides = None

A dictionary of form-field names and/or widget classes to override the widget template which is used when rendering a certain form-field. Optional.

widget_css_class = None

CSS class to append to the widget attributes. Optional.

widget_invalid_css_class = None

An additional CSS class to append to the widget attributes when the field has errors. Optional.

__init__(*args, **kwargs)

The init method is overwritten to apply widget templates and CSS classes.

full_clean(*args, **kwargs)

The full_clean method is hijacked to apply special treatment to invalid field inputs. For example adding extra options/classes to widgets.

get_field_template(bound_field, template_name=None)

Returns the field template to use when rendering a form field to HTML.

Preference of template selection:

1. Provided method argument template_name

2. Template from field_template_overrides selected by field name

3. Template from field_template_overrides selected by field class

4. Form class property field_template

5. Globally defined default template from defaults.LAYOUT_FIELD_TEMPLATE

Parameters:

• bound_field – BoundField instance to select a template for.

• template_name – Optional template to use instead of other configurations.

Returns:

Template name to use when rendering the form field.

get_field_container_css_class(bound_field)

Returns the container CSS class to use when rendering a field template.

By default, returns the Form class property field_container_css_class.

Parameters:

bound_field – BoundField instance to return CSS class for.

Returns:

A CSS class string.

get_field_label_css_class(bound_field)

Returns the optional label CSS class to use when rendering a field template.

By default, returns the Form class property field_label_css_class. If the field has errors and the Form class property field_label_invalid_css_class is defined, its value is appended to the CSS class.

Parameters:

bound_field – BoundField instance to return CSS class for.

Returns:

A CSS class string or None

get_field_context(bound_field)

Returns the context which is used when rendering a form field to HTML.

The generated template context will contain the following variables:

• form: Form instance

• field: BoundField instance of the field

• field_id: Field ID to use in <label for=”..”>

• field_name: Name of the form field to render

• errors: ErrorList instance with errors of the field

• required: Boolean flag to signal if the field is required or not

• label: The label text of the field

• label_css_class: The optional label CSS class, might be None

• help_text: Optional help text for the form field. Might be None

• container_css_class: The CSS class for the field container.

• widget_class_name: Lowercased version of the widget class name (e.g. ‘textinput’)

• widget_input_type: input_type property of the widget instance, falls back to widget_class_name if not available.

Returns:

Template context for field rendering.

apply_widget_options(field_name)

Applies additional widget options like changing the input type of DateInput and TimeInput to “date” / “time” to enable Browser date pickers or other attributes/properties.

apply_widget_template(field_name)

Applies widget template overrides if available.

The method uses the get_widget_template method to determine if the widget template should be exchanged. If a template is available, the template_name property of the widget instance is updated.

Parameters:

field_name – A field name of the form.

get_widget_template(field_name, field)

Returns the optional widget template to use when rendering the widget for a form field.

Preference of template selection:

1. Template from widget_template_overrides selected by field name

2. Template from widget_template_overrides selected by widget class

By default, returns None which means “use Django’s default widget template”.

Parameters:

• field_name – The field name to select a widget template for.

• field – Field instance to return a widget template.

Returns:

Template name to use when rendering the widget or None

apply_widget_css_class(field_name)

Applies CSS classes to widgets if available.

The method uses the get_widget_css_class method to determine if the widget CSS class should be changed. If a CSS class is returned, it is appended to the current value of the class property of the widget instance.

Parameters:

field_name – A field name of the form.

get_widget_css_class(field_name, field)

Returns the optional widget CSS class to use when rendering the form’s field widget.

By default, returns None which means “no CSS class / no change”.

Parameters:

• field_name – The field name of the corresponding field for the widget.

• field – Field instance to return CSS class for.

Returns:

A CSS class string or None

apply_widget_invalid_options(field_name)

Applies additional widget options for an invalid field.

This method is called when there is some error on a field to apply additional options on its widget. It does the following:

• Sets the aria-invalid property of the widget for accessibility.

• Adds an invalid CSS class, which is determined by the returned value of get_widget_invalid_css_class method. If a CSS class is returned, it is appended to the current value of the class property of the widget.

Parameters:

field_name – A field name of the form.

get_widget_invalid_css_class(field_name, field)

Returns the optional widget CSS class to append when rendering the form’s field widget in case of error.

By default, returns None which means “no CSS class / no change”.

Parameters:

• field_name – The field name of the corresponding field for the widget.

• field – Field instance to return CSS class for.

Returns:

A CSS class string or None