8000 minor #10926 Simplified the form theming docs (javiereguiluz) · symfony/symfony-docs@70eedcf · GitHub
[go: up one dir, main page]
Skip to content

Commit 70eedcf

Browse files
javiereguiluzjaviereguiluz
committed
minor #10926 Simplified the form theming docs (javiereguiluz)
This PR was squashed before being merged into the 4.1 branch (closes #10926). Discussion ---------- Simplified the form theming docs This is a total revamp of all the docs related to form themes and form customization. The current problems are: * `form/form_customization.rst` and `form/rendering.rst` are too similar. * `form/form_themes.rst` is incomplete and confusing * Most of the form theming things are explained in `form/form_customization.rst` instead of `form/form_themes.rst` * `reference/forms/twig_reference.rst` and `reference/twig_reference.rst` duplicate lots of contents This PR does the following: * Delete `form/rendering.rst` and merge it with `form/form_customization.rst` * Remove anything related to form themes from `form/form_customization.rst` * Add everything related to form themes to ``form/form_themes.rst`` * Remove the duplicated contents from `reference/twig_reference.rst` and link to the other form reference. The result is: * `form.rst`: main article explaining all the basics about forms. * `form/form_customization.rst` explains everything about Form helper functions (`form_start()`, `form_row()`, etc.) and form variables (`required`, `compound`, etc.) * `form/form_themes.rst` explains everything about form themes, including the form fragment naming and all the different options to create themes. On top of 8000 all the above, this PR removes 800 lines of docs! Commits ------- 7cdf54a Simplified the form theming docs
2 parents 7a953d8 + 7cdf54a commit 70eedcf

16 files changed

+813
-1651
lines changed

‎_build/redirection_map

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -403,3 +403,5 @@
403403
/frontend/encore/installation-no-flex /frontend/encore/installation
404404
/http_cache/form_csrf_caching /security/csrf
405405
/console/logging /console
406+
/reference/forms/twig_reference /form/form_customization
407+
/form/rendering /form/form_customization

‎_images/form/form-field-parts.svg

Lines changed: 1 addition & 0 deletions
Loading

‎_images/sources/form/form-field-parts.dia

2 KB
Binary file not shown.

‎components/form.rst

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -177,8 +177,9 @@ between Twig and several Symfony components:
177177
178178
$ composer require symfony/twig-bridge
179179
180-
The TwigBridge integration provides you with several :doc:`Twig Functions </reference/forms/twig_reference>`
181-
that help you render the HTML widget, label and error for each field
180+
The TwigBridge integration provides you with several
181+
:ref:`Twig Functions <reference-form-twig-functions-variables>`
182+
that help you render the HTML widget, label, help and errors for each field
182183
(as well as a few other things). To configure the integration, you'll need
183184
to bootstrap or access Twig and add the :class:`Symfony\\Bridge\\Twig\\Extension\\FormExtension`::
184185

@@ -231,7 +232,7 @@ The exact details of your `Twig Configuration`_ will vary, but the goal is
231232
always to add the :class:`Symfony\\Bridge\\Twig\\Extension\\FormExtension`
232233
to Twig, which gives you access to the Twig functions for rendering forms.
233234
To do this, you first need to create a :class:`Symfony\\Bridge\\Twig\\Form\\TwigRendererEngine`,
234-
where you define your :ref:`form themes <form-customization-form-themes>`
235+
where you define your :doc:`form themes </form/form_themes>`
235236
(i.e. resources/files that define form HTML markup).
236237

237238
For general details on rendering forms, see :doc:`/form/form_customization`.
@@ -510,8 +511,8 @@ Rendering the Form
510511

511512
Now that the form has been created, the next step is to render it. This is
512513
done by passing a special form "view" object to your template (notice the
513-
``$form->createView()`` in the controller above) and using a set of form
514-
helper functions:
514+
``$form->createView()`` in the controller above) and using a set of
515+
:ref:`form helper functions <reference-form-twig-functions>`:
515516

516517
.. code-block:: html+twig
517518

@@ -528,7 +529,7 @@ That's it! By printing ``form_widget(form)``, each field in the form is
528529
rendered, along with a label and error message (if there is one). While this is
529530
convenient, it's not very flexible (yet). Usually, you'll want to render each
530531
form field individually so you can control how the form looks. You'll learn how
531-
to do that in the ":doc:`/form/rendering`" section.
532+
to do that in the :doc:`form customization </form/form_customization>` article.
532533

533534
Changing a Form's Method and Action
534535
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎form/create_custom_field_type.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,9 @@ shipping options.
9090
Creating a Template for the Field
9191
---------------------------------
9292

93-
Each field type is rendered by a template fragment, which is determined in part by
94-
the class name of your type. For more information, see :ref:`form-customization-form-themes`.
93+
Each field type is rendered by a template fragment whose name is determined in
94+
part by the class name of your type. Read the :ref:`from fragment naming <form-fragment-naming>`
95+
rules for more details.
9596

9697
.. note::
9798

@@ -147,8 +148,8 @@ link for details), create a ``shipping_widget`` block to handle this:
147148
.. note::
148149

149150
Make sure the correct widget prefix is used. In this example the name should
150-
be ``shipping_widget`` (see :ref:`form-customization-form-themes`).
151-
Further, the main config file should point to the custom form template
151+
be ``shipping_widget`` (see :ref:`form fragment naming <form-fragment-naming>`
152+
rules). Further, the main config file should point to the custom form template
152153
so that it's used when rendering all forms.
153154

154155
When using Twig this is:

‎form/create_form_type_extension.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,7 @@ Override the File Widget Template Fragment
210210

211211
Each field type is rendered by a template fragment. Those template fragments
212212
can be overridden in order to customize form rendering. For more information,
213-
you can refer to the :ref:`form-customization-form-themes` article.
213+
you can refer to the :ref:`form fragment naming <form-fragment-naming>` rules.
214214

215215
In your extension class, you added a new variable (``image_url``), but
216216
you still need to take advantage of this new variable in your templates.

0 commit comments

Comments
 (0)
0