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.

render(form, context, template_pack=<SimpleLazyObject: 'bootstrap4'>, **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>.

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!'))
Attributes
template: str

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

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.

Examples

An example using ButtonHolder in your layout:

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

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

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>.

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'),
)
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.

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>.

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'),
)
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.

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 <div>.

Examples

Example:

Field('field_name', style="color: #333;", css_class="whatever", id="field_name")
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>.

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

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>.

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"))
Attributes
template: str

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

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.

Examples

Example:

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

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

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>.

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!'))
Attributes
template: str

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

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>.

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'),
)
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.

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>.

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'))
Attributes
template: str

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