forked from https://github.com/symfony/symfony
912d3e58b4
This PR was squashed before being merged into the 5.3-dev branch.
Discussion
----------
[TwigBridge] add tailwindcss form layout
| Q | A
| ------------- | ---
| Branch? | 5.x
| Bug fix? | no
| New feature? | yes
| Deprecations? | no
| Tickets | n/a
| License | MIT
| Doc PR | todo
Per @weaverryan's [call to action on twitter](https://twitter.com/weaverryan/status/1369654724107067392) and slack discussion.
It's been tricky to create a generic form layout for tailwind as it's a css *utility framework* and has an unlimited number of ways to style forms. With tailwindcss 2.0, the tailwind team released an [official form plugin](https://github.com/tailwindlabs/tailwindcss-forms) that provides form element reset/normalization that looks decent out of the box. This PR is an attempt to piggy-back on this plugin to provide a minimal Symfony form layout for tailwind. The goal is to have your forms look good in a tailwind/Symfony app with no customization (but of course allow customization as desired).
This layout **requires** tailwindcss 2 and the form plugin.
I followed the ["unstyled" demo](https://tailwindcss-forms.vercel.app/) for the form plugin as a style guide. Here is a screenshot of this layout used in [a demo Symfony app](https://github.com/kbond/symfony-tailwind) with several common form types (I'll try to keep this updated as I update the PR):
Some notes about the layout:
1. I tried to use as few tailwind classes as possible and avoid color (primary exception being the error color).
2. I decided on a mobile-first approach so out of the box, it will look decent on any device and drastically reduces the number of css classes/assumptions.
3. While other layouts merge classes passed by the user, I opted to replace. This ensures the user doesn't have to _undo_ the class decisions made by this layout. I also discovered "undoing" doesn't work as I expected anyway: `class="mt-1 mt-0"`, `mt-1` "wins" as `mt-1` comes later in the compiled stylesheet.
4. For the _low level_ blocks, I extracted the classes into their own "variables" (`row_class`, `widget_class`, `label_class`, `help_class`, `error_item_class`) to make it easier to extend and customize the layout. Note the `widget_disabled_class`/`widget_errors_class` variables: these are added even if you've overridden the `widget_class` variable.
### Customization
Customizing is especially important for this layout. Here are the two ways:
1. Twig form functions:
```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',
}) }}
```
2. Project specific form layout:
```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 -%}
```
#### Customization POC/Demo
With this custom form theme:
```twig
{%- block form_label -%}
{%- set label_class = label_class|default('block text-gray-500 uppercase tracking-wider text-sm font-bold') -%}
{{- parent() -}}
{%- endblock -%}
{%- block widget_attributes -%}
{%- set widget_class = widget_class|default('mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50') -%}
{{- parent() -}}
{%- endblock -%}
{%- block checkbox_widget -%}
{%- set widget_class = widget_class|default('mr-2 rounded border-gray-300 text-indigo-600 shadow-sm focus:border-indigo-300 focus:ring focus:ring-offset-0 focus:ring-indigo-200 focus:ring-opacity-50') -%}
{{- parent() -}}
{%- endblock -%}
{%- block checkbox_label -%}
{%- set label_class = label_class|default('block text-gray-800') -%}
{{- block('form_label') -}}
{%- endblock -%}
```
The above example looks like this:
Commits
-------
|
||
|---|---|---|
| .github | ||
| src/Symfony | ||
| .appveyor.yml | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| .php_cs.dist | ||
| .travis.yml | ||
| CHANGELOG-5.0.md | ||
| CHANGELOG-5.1.md | ||
| CHANGELOG-5.2.md | ||
| CODE_OF_CONDUCT.md | ||
| composer.json | ||
| CONTRIBUTING.md | ||
| CONTRIBUTORS.md | ||
| LICENSE | ||
| link | ||
| phpunit | ||
| phpunit.xml.dist | ||
| psalm.xml | ||
| README.md | ||
| UPGRADE-5.0.md | ||
| UPGRADE-5.1.md | ||
| UPGRADE-5.2.md | ||
| UPGRADE-5.3.md | ||
| UPGRADE-6.0.md | ||
Symfony is a PHP framework for web and console applications and a set of reusable PHP components. Symfony is used by thousands of web applications (including BlaBlaCar.com and Spotify.com) and most of the popular PHP projects (including Drupal and Magento).
Installation
- Install Symfony with Composer (see requirements details).
- Symfony follows the semantic versioning strictly, publishes "Long Term Support" (LTS) versions and has a release process that is predictable and business-friendly.
Documentation
- Read the Getting Started guide if you are new to Symfony.
- Try the Symfony Demo application to learn Symfony in practice.
- Master Symfony with the Guides and Tutorials, the Components docs and the Best Practices reference.
Community
- Join the Symfony Community and meet other members at the Symfony events.
- Get Symfony support on Stack Overflow, Slack, IRC, etc.
- Follow us on GitHub, Twitter and Facebook.
- Read our Code of Conduct and meet the CARE Team.
Contributing
Symfony is an Open Source, community-driven project with thousands of contributors. Join them contributing code or contributing documentation.
Security Issues
If you discover a security vulnerability within Symfony, please follow our disclosure procedure.
About Us
Symfony development is sponsored by SensioLabs, led by the Symfony Core Team and supported by Symfony contributors.