Field¶

class crispy_forms_gds.layout.Field(*fields, css_class=None, context=None, template=None, **kwargs)¶

A Layout object for display one or more fields in a form.

Field instances are rather low level. You can set the attributes and define the context variables used when the field is rendered.

Examples:

Field(
    "name",
    context={'label_size': 'govuk-label--m'},
    css_class="govuk-!-width-one-half"
)

Field(
    'age',
    css_class="govuk-input-width-5",
    style="color: #333;"
)

However it is much simpler to use the class methods to generate Field instances. This hide some of the details in the way the field is rendered and give more of a “component” feel. You can always update the instances after if you need to.

Examples:

Field.text("name", label_size=Size.MEDIUM, field_width=Fluid.ONE_HALF)
Field.checkboxes("options", legend_size=Size.MEDIUM)
Field.radios("method", small=True)

Field is a copy of the Crispy Forms Field class but with more well-defined interface. The ability to set template variables was added and the template keyword argument was made explicit - before it was just another kwarg. The one incompatibility is the wrapper_class keyword argument, which was removed. You can still add it via the context since it was used as a template variable.

Parameters

css_class (str, optional) – the css classes that will be added to the widget.
context (dict, optional) – the list of values that will be added to the template context when the field is rendered.
template (str, optional) – the template used to render this field, overriding the one defined on the class.
*fields – the names of the fields to display.
**kwargs (str) – the list of attributes that will be added to the widget. Use ‘_’ instead of ‘-’ in the attribute name. It will be converted to ‘-‘.

The variables defined in the context are only in scope while the field is being rendered. The original template context is then restored.

classmethod checkbox(field, small=False, **kwargs)¶

Create a field for displaying a single checkbox.

Parameters

field (str) – the name of the field.
small (bool) – Display small checkboxes. Default is False.
**kwargs – Attributes to add to the <input> element when the field is rendered.

classmethod checkboxes(field, legend_size=None, legend_tag=None, small=False, **kwargs)¶

Create a field for displaying a set of checkboxes.

Parameters

field (str) – the name of the field. The field’s label will be used as the title of the <legend>.
legend_size (str) – the size of the legend. The default is None in which case the legend will be rendered at the same size as regular text.
legend_tag (str) – Wrap the field legend with this HTML tag. Default is None.
small (bool) – Display small checkboxes. Default is False.
**kwargs – Attributes to add to the <input> element when the field is rendered.

classmethod radios(field, legend_size=None, legend_tag=None, small=False, inline=False, **kwargs)¶

Create a field for displaying radio buttons.

Parameters

field (str) – the name of the field.
legend_size (str) – the size of the legend. The default is None in which case the legend will be rendered at the same size as regular text.
legend_tag (str) – Wrap the field legend with this HTML tag. Default is None.
small (bool) – Display small radio buttons. Default is False.
inline (bool) – Display the radio buttons in a row. Default is False.
**kwargs – Attributes to add to the <input> element when the field is rendered.

classmethod select(field, legend_size=None, legend_tag=None, **kwargs)¶

Create a field for displaying a select drop-down.

Parameters

field (str) – the name of the field.
legend_size (str) – the size of the legend. The default is None in which case the legend will be rendered at the same size as regular text.
legend_tag (str) – Wrap the field legend with this HTML tag. Default is None.
**kwargs – Attributes to add to the <select> element when the field is rendered.

classmethod text(field, label_size=None, label_tag=None, field_width=None, **kwargs)¶

Create a field for displaying a Text input.

Parameters

field (str) – the name of the field.
label_size (str) – the size of the label. The default is None in which case the label will be rendered at the same size as regular text.
label_tag (str) – Wrap the field label with this HTML tag. Default is None.
field_width (int, str) – the width of the field - fixed or fluid. The default is None in which case the field will be rendered full width.
**kwargs – Attributes to add to the <input> element when the field is rendered.

classmethod textarea(field, label_size=None, label_tag=None, rows=10, max_characters=None, max_words=None, threshold=None, **kwargs)¶

Create a field for displaying a Textarea.

Parameters

field (str) – the name of the field.
label_size (str) – the size of the label. The default is None in which case the label will be rendered at the same size as regular text.
label_tag (str) – Wrap the field label with this HTML tag. Default is None.
rows (int) – the number of rows to display. If not specified then Django’s default of 10 will be used (the default used by most browsers is 2).
max_characters (int, optional) – the maximum number of characters that should be entered. Default is None.
max_words (int, optional) – the maximum number of words that should be entered. Default is None.
threshold (int, optional) – the percentage of the count that has to be reached before the limit is shown. Default is None.
**kwargs – Attributes to add to the <textarea> element when the field is rendered.

Raises

ValueError – if you set max_characters and max_words at the same time.

Hidden¶

class crispy_forms_gds.layout.Hidden(name, value, **kwargs)¶

Add a hidden field to a form’s layout.

Examples:

Hidden("name", "Homer Simpson")

Parameters

name (str) – the name of the field when the form is submitted.
value (str) – the value that will be submitted.
css_id (str, optional) – an unique identifier for the hidden field.
css_class (str, optional) – the names of one or more CSS classes that will be added to the hidden field.
template (str, optional) – the path to a template that overrides the one normally used.
**kwargs – any additional attributes you want to add to the <button>.

The class is simply imported from django-crispy-forms. It’s included so all the imports, when using the template pack come from the same source.

Generally the css_id, css_class, template and remaining keywords arguments are of limited use in this case. They are present as they are common to all fields.