Layout Objects

This template pack renders Django widgets with the Tailwind CSS framework. This page shows examples of how these widgets look when rendered with the default styling. For these objects we have given an opinion on how they should look.

If you are using the |crispy filter the form will be styled using the default layout. If you wish to customise the form you can use {% crispy %} tags and FormHelper to control the layout of your form.

Wherever possible layout objects are used from crispy-forms itself (either core or bootstrap). Where these can not be used Tailwind versions are included within this template pack. This means that the layout objects may be found within one of three files.

  • crispy_forms.layout (Layout and other standard objects)

  • crispy_forms.bootstrap (Some bootstrap objects work out of the box, so we will use these)

  • crispy_tailwind.layout (Customised versions for Tailwind are found here)

Knowledge for crispy-forms Layout class is assumed. Please see https://django-crispy-forms.readthedocs.io/en/latest/layouts.html for further information.

crispy_forms.layout

Layout

The core Layout class which provides the ability to control the rendering of your form. This is the parent which will wrap individual layout objects.

Column

The Column layout object wraps fields in a div so it can be used as a column. The Tailwind template adds no css class to this wrapper by default. If required classes can be added:

Column('form_field_1', 'form_field_2', css_class='additional classes',)

Row

The Row layout object wraps fields in a div so it can be used as a row. The Tailwind template adds flex flex-row to this wrapper by default. If required this default can be replaced by custom css classes:

Row('form_field_1', 'form_field_2', css_class='additional classes',)

Row and Column layouts are typically used together. Here is an example layout with an image showing how the form is rendered:

Row(
  Column(Field("first_name"), Field("last_name"), css_class="px-2"),
  Column("email", css_class="px-2"),
)
_images/row_col.png

Field

The Field layout object allows attributes to be easily added to a single field.

Div

The Div layout object wraps fields in a Div. No classes are added by default.

HTML

Used to render pure HTML code and behaves like a Django template. See the django-crispy-forms HTML docs for more information.

The HTML: https://django-crispy-forms.readthedocs.io/en/latest/layouts.html?#universal-layout-objects

Hidden

Used to create a hidden input.

Fieldset

Wraps fields in a <fieldset>. The first parameter is the legend for the fieldset. By default the class for the legend is block text-gray-700 font-bold mb-2. Below is an example layout and the default rendering:

Fieldset("Text for the legend", "is_company", "email",)
_images/fieldset.png

If you wish to customise the legend please over ride the template. See the over riding layout objects templates docs for guidance on how to do this.

TBC

Multifield, MultiWidgetField

crispy_forms.bootstrap

The following objects can be imported from crispy_forms.boostrap.

Field With Buttons

An oppinionated field with buttons template is provided with the template pack. If you wish to customise this layout object you can over ride templates.

_images/field_with_buttons.png

Inline Field

An oppinionated inline field. If you wish to customise this layout object you can over ride templates.

_images/inline_field.png

Prepended and Appended

The three layout objects which allow for prepended and appended inputs are:

  • PrependedText. First argument is the field name, the second is the prepended text.

  • AppendedText. First argument is the field name, the second is the appended text.

  • PrependedAppendedText. A combined prepended and appended text. The first parameter is the name of the field, then second is the prepended text and thirdly the appended text.

The image below shows examples of how these are rendered with the template provided with crispy-tailwind. If you wish to customise these then you will need to over ride templates.

_images/prepended.png

See the crispy-forms Prepended docs for more information on how to use these fields.

Note: the active argument does not have any impact on the crispy-tailwind template pack.

crispy_tailwind.layout

The following layout objects can be imported from crispy_tailwind.layout.

Buttons

The three Buttons (Button, Reset and Submit) from crispy-forms have been customised for the Tailwind template pack. Below is an example form layout with an image showing how it is rendered:

form.helper.layout = Layout(
    ButtonHolder(Button("button", "Button"), Submit("submit", "Submit",), Reset("cancel", "Cancel"))
)
_images/Buttons.png

The three buttons have default classes applied to them. The buttons can all be customised by adding css_classes to these layout objects. The following layout renders a single customised Submit button:

form.helper.layout = Layout(Submit("submit", "Submit", css_class="bg-transparent hover:bg-blue-500 text-blue-700 font-semibold hover:text-white py-2 px-4 border border-blue-500 hover:border-transparent rounded"))
_images/custom_button.png

Alert

Renders an alert message box:

form.helper.layout = Layout(
    Alert(content="<strong>Warning!</strong> Here's a test message.")
)
_images/alert.png

The css_class argument can be used to change the default classes on the wrapping <div>, this allows simple changes to the alert style (e.g. colour) .

By default alerts have a close button. To disable, set dismiss to false.

In addition the variety of alerts possible with Tailwind is wide and but may require a different HTML layout. In this case you may find is useful to over ride the alert.html template. See the crispy-forms docs on how to over ride templates for more information.