API Layout

class layout.BaseInput(name, value, *, css_id=None, css_class=None, template=None, **kwargs)[source]

A base class to reduce the amount of code in the Input classes.

Parameters:

namestr: The name attribute of the button.
valuestr: The value attribute of the button.
css_idstr, optional: A custom DOM id for the layout object. If not provided the name argument is slugified and turned into the id for the submit button. By default None.
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <input>.

Attributes:

template: str: The default template which this Layout Object will be rendered with.
field_classes: str: CSS classes to be applied to the <input>.

render(form, context, template_pack=<SimpleLazyObject: <function get_template_pack>>, **kwargs)[source]: Renders an <input /> if container is used as a Layout object. Input button value can be a variable in context.

class layout.Button(name, value, *, css_id=None, css_class=None, template=None, **kwargs)[source]

Used to create a button descriptor for the {% crispy %} template tag.

Parameters:

namestr: The name attribute of the button.
valuestr: The value attribute of the button.
css_idstr, optional: A custom DOM id for the layout object. If not provided the name argument is slugified and turned into the id for the submit button. By default None.
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <input>.

Attributes:

template: str: The default template which this Layout Object will be rendered with.
field_classes: str: CSS classes to be applied to the <input>.
input_type: str: The type attribute of the <input>.

Examples

Note: form arg to render() is not required for BaseInput inherited objects.

>>> button = Button('Button 1', 'Press Me!')
>>> button.render("", "", Context())
'<input type="button" name="button-1" value="Press Me!" '
'class="btn" id="button-id-button-1"/>'

>>> button = Button('Button 1', 'Press Me!', css_id="custom-id",
                     css_class="custom class", my_attr=True, data="my-data")
>>> button.render("", "", Context())
'<input type="button" name="button-1" value="Press Me!" '
'class="btn custom class" id="custom-id" data="my-data" my-attr/>'

Usually you will not call the render method on the object directly. Instead add it to your Layout manually or use the add_input method:

class ExampleForm(forms.Form):
[...]
def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.helper = FormHelper()
    self.helper.add_input(Button('Button 1', 'Press Me!'))

class layout.ButtonHolder(*fields, css_id=None, css_class=None, template=None)[source]

Layout object. It wraps fields in a <div class=”buttonHolder”>

This is where you should put Layout objects that render to form buttons

Parameters:

*fieldsHTML or BaseInput: The layout objects to render within the ButtonHolder. It should only hold HTML and BaseInput inherited objects.
css_idstr, optional: A custom DOM id for the layout object. If not provided the name argument is slugified and turned into the id for the submit button. By default None.
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.

Attributes:

template: str: The default template which this Layout Object will be rendered with.

Examples

An example using ButtonHolder in your layout:

ButtonHolder(
    HTML(<span style="display: hidden;">Information Saved</span>),
    Submit('Save', 'Save')
)

class layout.Column(*fields, css_id=None, css_class=None, template=None, **kwargs)[source]

Layout object. It wraps fields in a <div> and the template adds the appropriate class to render the contents in a column. e.g. col-md when using the Bootstrap4 template pack.

Parameters:

*fieldsstr, LayoutObject: Any number of fields as positional arguments to be rendered within the <div>.
css_idstr, optional: A DOM id for the layout object which will be added to the <div> if provided. By default None.
css_classstr, optional: Additional CSS classes to be applied in addition to those declared by the class itself. If using the Bootstrap4 template pack the default col-md is removed if this string contins another col- class. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <div>.

Attributes:

templatestr: The default template which this Layout Object will be rendered with.
css_classstr, optional: CSS classes to be applied to the <div>. By default None.

Examples

In your Layout you can:

Column('form_field_1', 'form_field_2', css_id='col-example')

It is also possible to nest Layout Objects within a Row:

Div(
    Column(
        Field('form_field', css_class='field-class'),
        css_class='col-sm,
    ),
    Column('form_field_2', css_class='col-sm'),
)

class layout.Div(*fields, css_id=None, css_class=None, template=None, **kwargs)[source]

Layout object. It wraps fields in a <div>.

Parameters:

*fieldsstr, LayoutObject: Any number of fields as positional arguments to be rendered within the <div>.
css_idstr, optional: A DOM id for the layout object which will be added to the <div> if provided. By default None.
css_classstr, optional: Additional CSS classes to be applied in addition to those declared by the class itself. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <div>.

Attributes:

templatestr: The default template which this Layout Object will be rendered with.
css_classstr, optional: CSS classes to be applied to the <div>. By default None.

Examples

In your Layout you can:

Div(
    'form_field_1',
    'form_field_2',
    css_id='div-example',
    css_class='divs',
)

It is also possible to nest Layout Objects within a Div:

Div(
    Div(
        Field('form_field', css_class='field-class'),
        css_class='div-class',
    ),
    Div('form_field_2', css_class='div-class'),
)

class layout.Field(*fields, css_class=None, wrapper_class=None, template=None, **kwargs)[source]

A Layout object, usually containing one field name, where you can add attributes to it easily.

Parameters:

*fieldsstr: Usually a single field, but can be any number of fields, to be rendered with the same attributes applied.
css_classstr, optional: CSS classes to be applied to the field. These are added to any classes included in the attrs dict. By default None.
wrapper_class: str, optional: CSS classes to be used when rendering the Field. This class is usually applied to the <div> which wraps the Field’s <label> and <input> tags. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are converted into key=”value”, pairs. These attributes are added to the field’s <input>.

Attributes:

templatestr: The default template which this Layout Object will be rendered with.
attrsdict: Attributes to be applied to the field. These are converted into html attributes. e.g. data_id: 'test' in the attrs dict will become data-id='test' on the field’s <input>.

Examples

Example:

Field('field_name', style="color: #333;", css_class="whatever", id="field_name")

class layout.Fieldset(legend, *fields, css_class=None, css_id=None, template=None, **kwargs)[source]

A layout object which wraps fields in a <fieldset>

Parameters:

legendstr: The content of the fieldset’s <legend>. This text is context aware, to bring this to life see the examples section.
*fieldsstr | LayoutObject | HTML: Any number of fields as positional arguments to be rendered within the <fieldset>
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
css_idstr, optional: A custom DOM id for the layout object. If not provided the name argument is slugified and turned into the id for the submit button. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <fieldset>.

Examples

The Fieldset Layout object is added to your Layout for example:

Fieldset("Text for the legend",
    "form_field_1",
    "form_field_2",
    css_id="my-fieldset-id",
    css_class="my-fieldset-class",
    data="my-data"
)

The above layout will be rendered as:

'''
<fieldset id="fieldset-id" class="my-fieldset-class" data="my-data">
   <legend>Text for the legend</legend>
   # form fields render here
</fieldset>
'''

The first parameter is the text for the fieldset legend. This text is context aware, so you can do things like:

Fieldset("Data for {{ user.username }}",
    'form_field_1',
    'form_field_2'
)

class layout.HTML(html)[source]

Layout object. It can contain pure HTML and it has access to the whole context of the page where the form is being rendered.

Examples:

HTML("{% if saved %}Data saved{% endif %}")
HTML('<input type="hidden" name="{{ step_field }}" value="{{ step0 }}" />')

class layout.Hidden(name, value, *, css_id=None, css_class=None, template=None, **kwargs)[source]

Used to create a Hidden input descriptor for the {% crispy %} template tag.

Parameters:

namestr: The name attribute of the button.
valuestr: The value attribute of the button.
css_idstr, optional: A custom DOM id for the layout object. If not provided the name argument is slugified and turned into the id for the submit button. By default None.
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <input>.

Attributes:

template: str: The default template which this Layout Object will be rendered with.
field_classes: str: CSS classes to be applied to the <input>.
input_type: str: The type attribute of the <input>.

Examples

Note: form arg to render() is not required for BaseInput inherited objects.

>>> hidden = Hidden("hidden", "hide-me")
>>> hidden.render("", "", Context())
'<input type="hidden" name="hidden" value="hide-me"/>'

Usually you will not call the render method on the object directly. Instead add it to your Layout manually or use the add_input method:

class ExampleForm(forms.Form):
[...]
def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.helper = FormHelper()
    self.helper.add_input(Hidden("hidden", "hide-me"))

class layout.Layout(*fields)[source]

Form Layout. It is conformed by Layout objects: Fieldset, Row, Column, MultiField, HTML, ButtonHolder, Button, Hidden, Reset, Submit and fields. Form fields have to be strings. Layout objects Fieldset, Row, Column, MultiField and ButtonHolder can hold other Layout objects within. Though ButtonHolder should only hold HTML and BaseInput inherited classes: Button, Hidden, Reset and Submit.

Example:

helper.layout = Layout(
    Fieldset('Company data',
        'is_company'
    ),
    Fieldset(_('Contact details'),
        'email',
        Row('password1', 'password2'),
        'first_name',
        'last_name',
        HTML('<img src="/media/somepicture.jpg"/>'),
        'company'
    ),
    ButtonHolder(
        Submit('Save', 'Save', css_class='button white'),
    ),
)

class layout.MultiField(label, *fields, label_class=None, help_text=None, css_class=None, css_id=None, template=None, field_template=None, **kwargs)[source]

MultiField container for Bootstrap3. Renders to a MultiField <div>.

Parameters:

label: str: The label for the multifield.
*fields: str: The fields to be rendered within the multifield.
label_class: str, optional: CSS classes to be added to the multifield label. By default None.
help_text: str, optional: Help text will be available in the context of the multifield template. This is unused in the bootstrap3 template provided. By default None.
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
css_idstr, optional: A DOM id for the layout object which will be added to the wrapping <div> if provided. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
field_templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the wrapping <div>.

Attributes:

template: str: The default template which this Layout Object will be rendered with.
field_template: str: The template which fields will be rendered with.

class layout.MultiWidgetField(*fields, attrs=None, template=None, wrapper_class=None)[source]

Layout object. For fields with MultiWidget as widget, you can pass additional attributes to each widget.

Parameters:

*fieldsstr: Usually a single field, but can be any number of fields, to be rendered with the same attributes applied.
attrsstr, optional: Additional attrs to be added to each widget. These are added to any classes included in the attrs dict. By default None.
wrapper_class: str, optional: CSS classes to be used when rendering the Field. This class is usually applied to the <div> which wraps the Field’s <label> and <input> tags. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.

Attributes:

templatestr: The default template which this Layout Object will be rendered with.

Examples

Example:

MultiWidgetField(
    'multiwidget_field_name',
    attrs=(
        {'style': 'width: 30px;'},
        {'class': 'second_widget_class'}
    ),
)

class layout.Pointer(positions: List[int], name: str)[source]

class layout.Reset(name, value, *, css_id=None, css_class=None, template=None, **kwargs)[source]

Used to create a reset button descriptor for the {% crispy %} template tag.

Parameters:

namestr: The name attribute of the button.
valuestr: The value attribute of the button.
css_idstr, optional: A custom DOM id for the layout object. If not provided the name argument is slugified and turned into the id for the submit button. By default None.
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <input>.

Attributes:

template: str: The default template which this Layout Object will be rendered with.
field_classes: str: CSS classes to be applied to the <input>.
input_type: str: The type attribute of the <input>.

Examples

Note: form arg to render() is not required for BaseInput inherited objects.

>>> reset = Reset('Reset This Form', 'Revert Me!')
>>> reset.render("", "", Context())
'<input type="reset" name="reset-this-form" value="Revert Me!" '
'class="btn btn-inverse" id="reset-id-reset-this-form"/>'

>>> reset = Reset('Reset This Form', 'Revert Me!', css_id="custom-id",
                     css_class="custom class", my_attr=True, data="my-data")
>>> reset.render("", "", Context())
'<input type="reset" name="reset-this-form" value="Revert Me!" '
'class="btn btn-inverse custom class" id="custom-id" data="my-data" my-attr/>'

Usually you will not call the render method on the object directly. Instead add it to your Layout manually manually or use the add_input method:

class ExampleForm(forms.Form):
[...]
def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.helper = FormHelper()
    self.helper.add_input(Reset('Reset This Form', 'Revert Me!'))

class layout.Row(*fields, css_id=None, css_class=None, template=None, **kwargs)[source]

Layout object. It wraps fields in a <div> and the template adds the appropriate class to render the contents in a row. e.g. form-row when using the Bootstrap4 template pack.

Parameters:

*fieldsstr, LayoutObject: Any number of fields as positional arguments to be rendered within the <div>.
css_idstr, optional: A DOM id for the layout object which will be added to the <div> if provided. By default None.
css_classstr, optional: Additional CSS classes to be applied in addition to those declared by the class itself. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <div>.

Attributes:

templatestr: The default template which this Layout Object will be rendered with.
css_classstr, optional: CSS classes to be applied to the <div>. By default None.

Examples

In your Layout you can:

Row('form_field_1', 'form_field_2', css_id='row-example')

It is also possible to nest Layout Objects within a Row:

Row(
    Div(
        Field('form_field', css_class='field-class'),
        css_class='div-class',
    ),
    Div('form_field_2', css_class='div-class'),
)

class layout.Submit(name, value, *, css_id=None, css_class=None, template=None, **kwargs)[source]

Used to create a Submit button descriptor for the {% crispy %} template tag.

Parameters:

namestr: The name attribute of the button.
valuestr: The value attribute of the button.
css_idstr, optional: A custom DOM id for the layout object. If not provided the name argument is slugified and turned into the id for the submit button. By default None.
css_classstr, optional: Additional CSS classes to be applied to the <input>. By default None.
templatestr, optional: Overrides the default template, if provided. By default None.
**kwargsdict, optional: Additional attributes are passed to flatatt and converted into key=”value”, pairs. These attributes are added to the <input>.

Attributes:

template: str: The default template which this Layout Object will be rendered with.
field_classes: str: CSS classes to be applied to the <input>.
input_type: str: The type attribute of the <input>.

Examples

Note: form arg to render() is not required for BaseInput inherited objects.

>>> submit = Submit('Search the Site', 'search this site')
>>> submit.render("", "", Context())
'<input type="submit" name="search-the-site" value="search this site" '
'class="btn btn-primary" id="submit-id-search-the-site"/>'

>>> submit = Submit('Search the Site', 'search this site', css_id="custom-id",
                     css_class="custom class", my_attr=True, data="my-data")
>>> submit.render("", "", Context())
'<input type="submit" name="search-the-site" value="search this site" '
'class="btn btn-primary custom class" id="custom-id" data="my-data" my-attr/>'

Usually you will not call the render method on the object directly. Instead add it to your Layout manually or use the add_input method:

class ExampleForm(forms.Form):
[...]
def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.helper = FormHelper()
    self.helper.add_input(Submit('submit', 'Submit'))