Adding a documentation page about Bootstrap 4 form theme #9351

Nyholm · 2018-02-26T18:13:24Z

The Boostrap 4 theme has some "special" feature that we should mention.

I wanted to give the user a copy-paste get started template.
I mention WCAG2.0 because we should be proud of that and make users aware of it
The special classes in "custom forms" are not boostrap classes. They are feature flags in the Symfony boostrap 4 theme.
The half "labels and erros" is copied from the form_custimazation.rst.

javiereguiluz

I like this a lot. Thanks for contributing it. However, I was thinking of making some changes in the intro of the article to explain things more in detail:

Original

An example how to use the Boostrap 4 theme might look like this. You could of course
use any sources for the Boostrap CSS and JavaScript.

.. code-block:: html+twig

    {% form_theme form 'bootstrap_4_layout.html.twig' %}

    {% block head %}
        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
        <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js" integrity="sha384-ApNbgh9B+Y1QKtv3Rn7W3mgPxhU9K/ScQsAP7hUibX39j7fakFPskvXusvfa0b4Q" crossorigin="anonymous"></script>
        <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js" integrity="sha384-JZR6Spejh4U02d8jOt6vLEHfe/JQGiRRSQQxSfFWpi1MquVdAyjUar5+76PVCmYl" crossorigin="anonymous"></script>
    {% endblock head %}

    {% block body %}
      <h1>Here is my form:</h1>
      {{ form(form) }}
    {% endblock body %}

Proposal

Symfony provides several ways of integrating Bootstrap into your application. The
most straightforward way is to just add the required ``<link>`` and ``<script>``
elements in your templates (usually you only include them in the main layout
template which other templates extend from):

.. code-block:: html+twig

    {# templates/base.html.twig #}

    {# beware that the blocks in your template may be named different #}
    {% block head_css %}
        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
    {% endblock %}
    {% block head_js %}
        <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js" integrity="sha384-ApNbgh9B+Y1QKtv3Rn7W3mgPxhU9K/ScQsAP7hUibX39j7fakFPskvXusvfa0b4Q" crossorigin="anonymous"></script>
        <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js" integrity="sha384-JZR6Spejh4U02d8jOt6vLEHfe/JQGiRRSQQxSfFWpi1MquVdAyjUar5+76PVCmYl" crossorigin="anonymous"></script>
    {% endblock head %}

If your application uses modern front-end practices, it's better to use
:ref:`Webpack Encore </frontend>` and follow :ref:`this tutorial </frontend/encore/bootstrap>`
to import Bootstrap's sources into your SCSS and JavaScript files.

The next step is to configure the Symfony application to use Bootstrap 4 styles
when rendering forms. If you want to apply them to all forms, define this
configuration:

.. code-block:: yaml
    
    # config/packages/twig.yaml
    twig:
        # ...
        form_themes: ['bootstrap_4_layout.html.twig']

If you prefer to apply the Bootstrap styles on a form to form basis, include the
``form_theme`` tag in the templates where those forms are used:

.. code-block:: twig

    {# ... #}
    {# this tag only applies to the forms defined in this template #}
    {% form_theme form 'bootstrap_4_layout.html.twig' %}

    {% block body %}
        <h1>User Sign Up:</h1>
        {{ form(form) }}
    {% endblock body %}

xabbuh · 2018-02-27T09:08:26Z

Do we really need a full article for this theme? Couldn't this be integrated into the existing page where we list all the available form themes?

javiereguiluz · 2018-02-27T09:16:06Z

The thing is that Bootstrap is extremely special and popular. Fun fact: this article published on symfony.com blog in 2014 is still our most popular blog post ever by an infinite difference: https://symfony.com/blog/new-in-symfony-2-6-bootstrap-form-theme Bootstrap is just incredibly popular, so I like the idea of a short and practical guide for it (and not for other frameworks).

Nyholm · 2018-02-27T09:18:06Z

Thank you for the feedback and reviews.

I've considered to make it as a part as an existing page. But it was too many things that were special with bootstrap 4. Also this symfony/symfony#26331 will be a special symfony/boostrap feature.

Nyholm · 2018-02-28T18:12:26Z

@weaverryan Do you have any input on this PR?

xabbuh · 2018-03-04T08:53:28Z

form/bootstrap4.rst

+
+    {# beware that the blocks in your template may be named different #}
+    {% block head_css %}
+        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">


I am not sure if we really should include this code example here. It will become outdated really fast and people will still continue to copy and paste it. What about linking to the Bootstrap getting started docs instead?

xabbuh · 2018-03-04T08:54:16Z

form/bootstrap4.rst

+when rendering forms. If you want to apply them to all forms, define this
+configuration:
+
+.. code-block:: yaml


We should best add a configuration block containing the config for the PHP and XML formats too.

xabbuh · 2018-03-04T08:54:47Z

form/bootstrap4.rst

+Accessibility
+-------------
+
+The Bootstrap 4 framework has done a good job making in accessible for function


[...] making it [...]?

xabbuh · 2018-03-04T08:56:00Z

form/bootstrap4.rst

+``form_label()`` for a checkbox/radio field doesn't show anything. Due to Bootstrap
+internals, the label is already shown by ``form_widget()``.
+
+You may also note that the form errors is rendered **inside** the ``<label>``. This


xabbuh · 2018-03-04T08:56:22Z

form/bootstrap4.rst

+internals, the label is already shown by ``form_widget()``.
+
+You may also note that the form errors is rendered **inside** the ``<label>``. This
+is done to make sure there is a strong connection between the error and in the


[...] and in the [...]

xabbuh · 2018-03-04T08:56:40Z

form/form_customization.rst

@@ -127,6 +127,10 @@ fragment needed to render every part of a form:
    calling ``form_label()`` for a checkbox/radio field doesn't show anything.
    Due to Bootstrap internals, the label is already shown by ``form_widget()``.

+.. tip::
+
+    Read more about :doc:`Bootstrap 4 form theme </form/bootstrap4>`.


[...] about the Bootstrap [...]?

Nyholm · 2018-03-04T11:07:46Z

Thank you for the review. I've updated accordingly

javiereguiluz

This is looking really good. Thanks for this Tobias.

javiereguiluz · 2018-03-04T12:01:15Z

form/bootstrap4.rst

+-------------
+
+The Bootstrap 4 framework has done a good job making it accessible for function
+variations like impaired vision and cognitive ability. Symfony has taken this one


Just asking: does this term sounds good to you? -> function variations Should it be functional variations or even functional diversity?

Im not sure. It is the perfect word in Swedish. We may need a native English speaker.

My intent is to not have the word "disabilities" or anything that could be connected to a negative tone.

javiereguiluz · 2018-03-04T12:02:19Z

form/bootstrap4.rst

+
+The Bootstrap 4 framework has done a good job making it accessible for function
+variations like impaired vision and cognitive ability. Symfony has taken this one
+step further to make sure the form theme complies with the `WCAG2.0 standard`_.


WCAG2.0 standard -> WCAG 2.0 standard

javiereguiluz · 2018-03-04T12:03:23Z

form/bootstrap4.rst

+-----------------
+
+When you use the Bootstrap form themes and render the fields manually, calling
+``form_label()`` for a checkbox/radio field doesn't show anything. Due to Bootstrap


doesn't show anything -> doesn't render anything ? (and later ... already shown by -> already rendered by ?)

javiereguiluz · 2018-03-04T12:05:06Z

form/bootstrap4.rst

+``form_label()`` for a checkbox/radio field doesn't show anything. Due to Bootstrap
+internals, the label is already shown by ``form_widget()``.
+
+You may also note that the form errors are rendered **inside** the ``<label>``. This


We could remove this -> You may also note that the ... This is done to ... to make it more concise:

Form errors are rendered **inside** the ``<label>`` element to make sure there is a strong connection between the error and its ``<input>``, as required by the `WCAG2.0 standard`_.

javiereguiluz · 2018-03-13T09:41:49Z

This is finally merged! Thanks Tobias for such a nice contribution.

Nyholm · 2018-03-13T09:45:14Z

Awesome. Thanks

javiereguiluz · 2018-03-13T09:52:28Z

My incompetence is also awesome 😭 I should have merged this into 3.4 instead of master. I'm going to try to fix that.

Update: I finally merged this on 3.4 branch too: https://github.com/symfony/symfony-docs/commits/3.4

… theme (Nyholm) This PR was squashed before being merged into the master branch (closes symfony#9351). Discussion ---------- Adding a documentation page about Bootstrap 4 form theme The Boostrap 4 theme has some "special" feature that we should mention. * I wanted to give the user a copy-paste get started template. * I mention WCAG2.0 because we should be proud of that and make users aware of it * The special classes in "custom forms" are not boostrap classes. They are feature flags in the Symfony boostrap 4 theme. * The half "labels and erros" is copied from the `form_custimazation.rst`. Commits ------- 696a366 Adding a documentation page about Bootstrap 4 form theme

Adding a documentation page about Bootstrap 4 form theme

6effb03

carsonbot added the Status: Needs Review label Feb 26, 2018

cs

8a3b9cb

javiereguiluz requested changes Feb 27, 2018

View reviewed changes

Nyholm added 2 commits February 27, 2018 10:19

Updated the intro

5657f66

typo

9852b4c

xabbuh added this to the 3.4 milestone Mar 4, 2018

xabbuh reviewed Mar 4, 2018

View reviewed changes

Nyholm added 3 commits March 4, 2018 12:02

fixed typos

3757a02

Added config block

dc1fced

Added note to copy js/css from docs

747712e

javiereguiluz approved these changes Mar 4, 2018

View reviewed changes

Nyholm added 2 commits March 4, 2018 13:30

Fixes

0b47211

Use the term "functional variations"

69f5d68

javiereguiluz added Status: Reviewed Form and removed Status: Needs Review labels Mar 13, 2018

javiereguiluz closed this in 727fc74 Mar 13, 2018

Nyholm deleted the bootstrap4 branch March 13, 2018 09:45

Nyholm restored the bootstrap4 branch March 13, 2018 09:54

Nyholm deleted the bootstrap4 branch March 13, 2018 15:46

Uh oh!

Adding a documentation page about Bootstrap 4 form theme #9351

Adding a documentation page about Bootstrap 4 form theme #9351

Uh oh!

Conversation

Nyholm commented Feb 26, 2018

Uh oh!

javiereguiluz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Original

Proposal

Uh oh!

xabbuh commented Feb 27, 2018

Uh oh!

javiereguiluz commented Feb 27, 2018

Uh oh!

Nyholm commented Feb 27, 2018

Uh oh!

Nyholm commented Feb 28, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nyholm commented Mar 4, 2018

Uh oh!

javiereguiluz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

javiereguiluz commented Mar 13, 2018

Uh oh!

Nyholm commented Mar 13, 2018

Uh oh!

javiereguiluz commented Mar 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

javiereguiluz left a comment •

edited

Loading

javiereguiluz commented Mar 13, 2018 •

edited

Loading