Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[TwigBridge] add tailwindcss form layout #40449

Merged
merged 1 commit into from Mar 27, 2021

Conversation

kbond
Copy link
Member

@kbond kbond commented Mar 11, 2021

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 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 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 for the form plugin as a style guide. Here is a screenshot of this layout used in a demo Symfony app with several common form types (I'll try to keep this updated as I update the PR):
New-Post

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:
    {{ 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:
    {% 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:

{%- 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:
New-Post (3)

@carsonbot carsonbot added Status: Needs Review Feature RFC RFC = Request For Comments (proposals about features that you want to be discussed) TwigBridge labels Mar 11, 2021
@carsonbot carsonbot changed the title [RFC][WIP][TwigBridge] add tailwindcss form layout [TwigBridge] [WIP] add tailwindcss form layout Mar 11, 2021
@kbond kbond force-pushed the feature/tailwind-form-layout branch 2 times, most recently from 6b31fd6 to 26f0602 Compare March 15, 2021 16:12
@kbond kbond force-pushed the feature/tailwind-form-layout branch 2 times, most recently from fd85ac3 to aa6ac46 Compare March 15, 2021 17:40
@nicolas-grekas nicolas-grekas added this to the 5.x milestone Mar 16, 2021
@kbond kbond force-pushed the feature/tailwind-form-layout branch from aa6ac46 to c17df6e Compare March 26, 2021 19:11
@kbond kbond changed the title [TwigBridge] [WIP] add tailwindcss form layout [TwigBridge] add tailwindcss form layout Mar 26, 2021
@kbond kbond force-pushed the feature/tailwind-form-layout branch from c17df6e to c6240ba Compare March 27, 2021 00:22
Copy link
Member

@weaverryan weaverryan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent work! And nice work building the demo. I think we should roll with this 👍

One question is - due to the complex nature of form themes AND the special nature of Tailwind (where there is no 100% correct set of classes to use), we could consider making this Tailwind form theme experimental for one minor version (5.3).

@kbond
Copy link
Member Author

kbond commented Mar 27, 2021

I'm also very much in favour of marking as experimental in 5.3. This will give us time to see how it's used in the wild and refine as needed for 5.4.

@fabpot
Copy link
Member

fabpot commented Mar 27, 2021

@kbond Can you add a comment at the beginning of the file to mark it as experimental?

@fabpot fabpot force-pushed the feature/tailwind-form-layout branch from ad983a9 to 3719a40 Compare March 27, 2021 15:07
@fabpot
Copy link
Member

fabpot commented Mar 27, 2021

Thank you @kbond.

@ahmed-bhs
Copy link
Contributor

@kbond thank you for your PR, any attentions to contribute a form_theme for tailwindcss version 3 ? Cheers!

@kbond
Copy link
Member Author

kbond commented Sep 23, 2022

@ahmed-bhs, is there anything that would have changed between 2 and 3? I think you could just use tailwind_2_layout.html.twig with tailwind 3 without issue.

@fantomas-code
Copy link

fantomas-code commented Apr 16, 2023

Greetings to all 😎
How do I create a theme completely from scratch without relying on form div layout.html.twig?
I've seen that all TwigBridge themes depend on that layout.
so far I have not been able to find a tutorial that can teach me.

@welcoMattic
Copy link
Member

Greetings to all 😎

How do I create a theme completely from scratch without relying on form div layout.html.twig?

I've seen that all TwigBridge themes depend on that layout.

so far I have not been able to find a tutorial that can teach me.

Closed issues are not the best place to ask for help. You can try to ask in GitHub Discussions tab, or on Slack Symfony Devs. In the mean time you can check this doc page https://symfony.com/doc/current/form/form_themes.html

OskarStark added a commit to symfony/symfony-docs that referenced this pull request Aug 16, 2023
This PR was merged into the 5.4 branch.

Discussion
----------

[Form] add tailwindcss form theme docs

This is a rough 1st draft. Some questions:
1. Should we add more detailed installation instructions? My hope is there will eventually be offical encore docs on integrating tailwind we can link to.
2. Should I include the *out of the box* screenshot from the PR?
3. Should I include the *customization* demo (code/screenshot) from the PR?

I'd appreciate some input/feedback!

Closes #15160, Symfony PR: symfony/symfony#40449

Commits
-------

4947010 [Form] add tailwindcss form theme docs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Feature RFC RFC = Request For Comments (proposals about features that you want to be discussed) Status: Reviewed TwigBridge
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

10 participants