==============
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.
.. _Layout: https://django-crispy-forms.readthedocs.io/en/latest/layouts.html?#fundamentals
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',)
.. _column: https://django-crispy-forms.readthedocs.io/en/latest/api_layout.html?#layout.Column
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"),
)
.. image:: img/row_col.png
:width: 50%
.. _Row : https://django-crispy-forms.readthedocs.io/en/latest/api_layout.html?#layout.Row
Field
-----
The Field_ layout object allows attributes to be easily added to a single
field.
.. _Field: https://django-crispy-forms.readthedocs.io/en/latest/api_layout.html?#layout.Field
Div
---
The Div_ layout object wraps fields in a `Div`. No classes are added by default.
.. _Div: https://django-crispy-forms.readthedocs.io/en/latest/api_layout.html?#layout.Div
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
.. _HTML:
Hidden
------
Used to create a hidden_ input.
.. _Hidden: https://django-crispy-forms.readthedocs.io/en/latest/api_layout.html?#layout.Hidden
Fieldset
--------
Wraps fields in a ``