Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Form] add tailwindcss form theme docs
- Loading branch information
Showing
3 changed files
with
96 additions
and
0 deletions.
There are no files selected for viewing
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,95 @@ | ||
Tailwind CSS Form Theme | ||
======================= | ||
|
||
Symfony provides a minimal form theme for `Tailwind CSS`_. Tailwind is a *utility first* | ||
CSS framework and provides *unlimited ways* to customize your forms. Tailwind has | ||
an official `form plugin`_ that provides a basic form reset that standardizes their look | ||
on all browsers. This form theme requires this plugin and adds a few basic tailwind | ||
classes so out of the box, your forms will look decent. Customization is almost always | ||
going to be required so this theme makes that easy. | ||
|
||
.. image:: /_images/form/tailwindcss-form.png | ||
:align: center | ||
|
||
To use, first be sure you have installed and integrated `Tailwind CSS`_ and the | ||
`form plugin`_. Follow their respective documentation to install both packages. | ||
|
||
If you prefer to use the Tailwind theme on a form by form basis, include the | ||
``form_theme`` tag in the templates where those forms are used: | ||
|
||
.. code-block:: html+twig | ||
|
||
{# ... #} | ||
{# this tag only applies to the forms defined in this template #} | ||
{% form_theme form 'tailwind_2_layout.html.twig' %} | ||
|
||
{% block body %} | ||
<h1>User Sign Up:</h1> | ||
{{ form(form) }} | ||
{% endblock %} | ||
|
||
Customization | ||
------------- | ||
|
||
Customizing CSS classes is especially important for this theme. | ||
|
||
Twig Form Functions | ||
~~~~~~~~~~~~~~~~~~~ | ||
|
||
You can customize classes of individual fields by setting some class options. | ||
|
||
.. code-block:: twig | ||
{{ form_row(form.title, { | ||
row_class: 'my row classes', | ||
label_class: 'my label classes', | ||
error_item_class: 'my error item classes', | ||
widget_class: 'my widget classes', | ||
widget_disabled_class: 'my disabled widget classes', | ||
widget_errors_class: 'my widget with error classes', | ||
}) }} | ||
When customizing the classes this way the defaults provided by the theme | ||
are *overridden* opposed to merged as is the case with other themes. This | ||
enables you to take full control of the classes without worrying about | ||
*undoing* the generic defaults the theme provides. | ||
|
||
Project Specific Form Layout | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
If you have a generic Tailwind style for all your forms, you can create | ||
a custom form theme using the Tailwind CSS theme as a base. | ||
|
||
.. code-block:: twig | ||
{% use 'tailwind_2_layout.html.twig' %} | ||
{%- block form_row -%} | ||
{%- set row_class = row_class|default('my row classes') -%} | ||
{{- parent() -}} | ||
{%- endblock form_row -%} | ||
{%- block widget_attributes -%} | ||
{%- set widget_class = widget_class|default('my widget classes') -%} | ||
{%- set widget_disabled_class = widget_disabled_class|default('my disabled widget classes') -%} | ||
{%- set widget_errors_class = widget_errors_class|default('my widget with error classes') -%} | ||
{{- parent() -}} | ||
{%- endblock widget_attributes -%} | ||
{%- block form_label -%} | ||
{%- set label_class = label_class|default('my label classes') -%} | ||
{{- parent() -}} | ||
{%- endblock form_label -%} | ||
{%- block form_help -%} | ||
{%- set help_class = help_class|default('my label classes') -%} | ||
{{- parent() -}} | ||
{%- endblock form_help -%} | ||
{%- block form_errors -%} | ||
{%- set error_item_class = error_item_class|default('my error item classes') -%} | ||
{{- parent() -}} | ||
{%- endblock form_errors -%} | ||
.. _`Tailwind CSS`: https://tailwindcss.com | ||
.. _`form plugin`: https://github.com/tailwindlabs/tailwindcss-forms |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters