# API Layout

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

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

  Parameters:
    name str

      The name attribute of the button.

    value str

      The value attribute of the button.

    css_id str, 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_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, 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)

    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)

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

  Parameters:
    name str

      The name attribute of the button.

    value str

      The value attribute of the button.

    css_id str, 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_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, 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)

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

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

  Parameters:
    *fields HTML or BaseInput

      The layout objects to render within the `ButtonHolder`. It should only hold HTML and BaseInput inherited objects.

    css_id str, 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_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    template str, 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)

  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:
    *fields str, LayoutObject

      Any number of fields as positional arguments to be rendered within the `<div>`.

    css_id str, optional

      A DOM id for the layout object which will be added to the `<div>` if provided. By default None.

    css_class str, 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 contains another `col-` class. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, optional

      Additional attributes are passed to `flatatt` and converted into key=”value”, pairs. These attributes are added to the `<div>`.

  Attributes:
    template str

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

    css_class str, 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)

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

  Parameters:
    *fields str, LayoutObject

      Any number of fields as positional arguments to be rendered within the `<div>`.

    css_id str, optional

      A DOM id for the layout object which will be added to the `<div>` if provided. By default None.

    css_class str, optional

      Additional CSS classes to be applied in addition to those declared by the class itself. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, optional

      Additional attributes are passed to `flatatt` and converted into key=”value”, pairs. These attributes are added to the `<div>`.

  Attributes:
    template str

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

    css_class str, 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)

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

  Parameters:
    *fields str

      Usually a single field, but can be any number of fields, to be rendered with the same attributes applied.

    css_class str, 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`.

    template str, optional

      Overrides the default template, if provided. By default `None`.

    **kwargs dict, optional

      Additional attributes are converted into key=”value”, pairs. These attributes are added to the field’s `<input>`.

  Attributes:
    template str

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

    attrs dict

      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)

  A layout object which wraps fields in a `<fieldset>`

  Parameters:
    legend str

      The content of the fieldset’s `<legend>`. This text is context aware, to bring this to life see the examples section.

    *fields str | LayoutObject | HTML

      Any number of fields as positional arguments to be rendered within the `<fieldset>`

    css_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    css_id str, 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.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, 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)

  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)

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

  Parameters:
    name str

      The name attribute of the button.

    value str

      The value attribute of the button.

    css_id str, 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_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, 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)

  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)

  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_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    css_id str, optional

      A DOM id for the layout object which will be added to the wrapping `<div>` if provided. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    field_template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, 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)

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

  Parameters:
    *fields str

      Usually a single field, but can be any number of fields, to be rendered with the same attributes applied.

    attrs str, 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`.

    template str, 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

  Example:

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

class layout.Pointer(positions: list[int], name: str)

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

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

  Parameters:
    name str

      The name attribute of the button.

    value str

      The value attribute of the button.

    css_id str, 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_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, 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)

  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:
    *fields str, LayoutObject

      Any number of fields as positional arguments to be rendered within the `<div>`.

    css_id str, optional

      A DOM id for the layout object which will be added to the `<div>` if provided. By default None.

    css_class str, optional

      Additional CSS classes to be applied in addition to those declared by the class itself. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, optional

      Additional attributes are passed to `flatatt` and converted into key=”value”, pairs. These attributes are added to the `<div>`.

  Attributes:
    template str

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

    css_class str, 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)

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

  Parameters:
    name str

      The name attribute of the button.

    value str

      The value attribute of the button.

    css_id str, 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_class str, optional

      Additional CSS classes to be applied to the `<input>`. By default None.

    template str, optional

      Overrides the default template, if provided. By default None.

    **kwargs dict, 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'))