|
| 1 | +Tailwind CSS Form Theme |
| 2 | +======================= |
| 3 | + |
| 4 | +Symfony provides a minimal form theme for `Tailwind CSS`_. Tailwind is a *utility first* |
| 5 | +CSS framework and provides *unlimited ways* to customize your forms. Tailwind has |
| 6 | +an official `form plugin`_ that provides a basic form reset that standardizes their look |
| 7 | +on all browsers. This form theme requires this plugin and adds a few basic tailwind |
| 8 | +classes so out of the box, your forms will look decent. Customization is almost always |
| 9 | +going to be required so this theme makes that easy. |
| 10 | + |
| 11 | +.. image:: /_images/form/tailwindcss-form.png |
| 12 | + :align: center |
| 13 | + |
| 14 | +To use, first be sure you have installed and integrated `Tailwind CSS`_ and the |
| 15 | +`form plugin`_. Follow their respective documentation to install both packages. |
| 16 | + |
| 17 | +If you prefer to use the Tailwind theme on a form by form basis, include the |
| 18 | +``form_theme`` tag in the templates where those forms are used: |
| 19 | + |
| 20 | +.. code-block:: html+twig |
| 21 | + |
| 22 | + {# ... #} |
| 23 | + {# this tag only applies to the forms defined in this template #} |
| 24 | + {% form_theme form 'tailwind_2_layout.html.twig' %} |
| 25 | + |
| 26 | + {% block body %} |
| 27 | + <h1>User Sign Up:</h1> |
| 28 | + {{ form(form) }} |
| 29 | + {% endblock %} |
| 30 | + |
| 31 | +Customization |
| 32 | +------------- |
| 33 | + |
| 34 | +Customizing CSS classes is especially important for this theme. |
| 35 | + |
| 36 | +Twig Form Functions |
| 37 | +~~~~~~~~~~~~~~~~~~~ |
| 38 | + |
| 39 | +You can customize classes of individual fields by setting some class options. |
| 40 | + |
| 41 | +.. code-block:: twig |
| 42 | +
|
| 43 | + {{ form_row(form.title, { |
| 44 | + row_class: 'my row classes', |
| 45 | + label_class: 'my label classes', |
| 46 | + error_item_class: 'my error item classes', |
| 47 | + widget_class: 'my widget classes', |
| 48 | + widget_disabled_class: 'my disabled widget classes', |
| 49 | + widget_errors_class: 'my widget with error classes', |
| 50 | + }) }} |
| 51 | +
|
| 52 | +When customizing the classes this way the defaults provided by the theme |
| 53 | +are *overridden* opposed to merged as is the case with other themes. This |
| 54 | +enables you to take full control of the classes without worrying about |
| 55 | +*undoing* the generic defaults the theme provides. |
| 56 | + |
| 57 | +Project Specific Form Layout |
| 58 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 59 | + |
| 60 | +If you have a generic Tailwind style for all your forms, you can create |
| 61 | +a custom form theme using the Tailwind CSS theme as a base. |
| 62 | + |
| 63 | +.. code-block:: twig |
| 64 | +
|
| 65 | + {% use 'tailwind_2_layout.html.twig' %} |
| 66 | +
|
| 67 | + {%- block form_row -%} |
| 68 | + {%- set row_class = row_class|default('my row classes') -%} |
| 69 | + {{- parent() -}} |
| 70 | + {%- endblock form_row -%} |
| 71 | +
|
| 72 | + {%- block widget_attributes -%} |
| 73 | + {%- set widget_class = widget_class|default('my widget classes') -%} |
| 74 | + {%- set widget_disabled_class = widget_disabled_class|default('my disabled widget classes') -%} |
| 75 | + {%- set widget_errors_class = widget_errors_class|default('my widget with error classes') -%} |
| 76 | + {{- parent() -}} |
| 77 | + {%- endblock widget_attributes -%} |
| 78 | +
|
| 79 | + {%- block form_label -%} |
| 80 | + {%- set label_class = label_class|default('my label classes') -%} |
| 81 | + {{- parent() -}} |
| 82 | + {%- endblock form_label -%} |
| 83 | +
|
| 84 | + {%- block form_help -%} |
| 85 | + {%- set help_class = help_class|default('my label classes') -%} |
| 86 | + {{- parent() -}} |
| 87 | + {%- endblock form_help -%} |
| 88 | +
|
| 89 | + {%- block form_errors -%} |
| 90 | + {%- set error_item_class = error_item_class|default('my error item classes') -%} |
| 91 | + {{- parent() -}} |
| 92 | + {%- endblock form_errors -%} |
| 93 | +
|
| 94 | +.. _`Tailwind CSS`: https://tailwindcss.com |
| 95 | +.. _`form plugin`: https://github.com/tailwindlabs/tailwindcss-forms |
0 commit comments