From 9bd5f8b180a6ca18248779a8d535d39b7511662d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 11 Jul 2018 18:03:45 +0200 Subject: [PATCH] Moved PHP-related code from Forms to the PHP templating page --- form/form_customization.rst | 218 ++---------------------------------- templating/PHP.rst | 216 +++++++++++++++++++++++++++++++++++ 2 files changed, 225 insertions(+), 209 deletions(-) diff --git a/form/form_customization.rst b/form/form_customization.rst index be20db2005a..0596a0968bc 100644 --- a/form/form_customization.rst +++ b/form/form_customization.rst @@ -304,53 +304,10 @@ different than the one of your main form. Just specify both your themes: {% form_theme form.a_child_form 'form/fields_child.html.twig' %} -Form Theming in PHP -------------------- +.. _referencing-base-form-blocks-twig-specific: -When using PHP as a templating engine, the only method to customize a fragment -is to create a new template file - this is similar to the second method used by -Twig. - -The template file must be named after the fragment. You must create a ``integer_widget.html.php`` -file in order to customize the ``integer_widget`` fragment. - -.. code-block:: html+php - - -
- block( - $form, - 'form_widget_simple', - array('type' => isset($type) ? $type : "number") - ) ?> -
- -Now that you've created the customized form template, you need to tell Symfony -to use it. Inside the template where you're actually rendering your form, -tell Symfony to use the theme via the ``setTheme()`` helper method:: - - setTheme($form, array(':form')); ?> - - widget($form['age']) ?> - -When the ``form.age`` widget is rendered, Symfony will use the customized -``integer_widget.html.php`` template and the ``input`` tag will be wrapped in -the ``div`` element. - -If you want to apply a theme to a specific child form, pass it to the ``setTheme()`` -method:: - - setTheme($form['child'], ':form'); ?> - -.. note:: - - The ``:form`` syntax is based on the functional names for templates: - ``Bundle:Directory``. As the form directory lives in the - ``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting - in ``:form``. - -Referencing base Form Blocks (Twig specific) --------------------------------------------- +Referencing base Form Blocks +---------------------------- So far, to override a particular form block, the best method is to copy the default block from `form_div_layout.html.twig`_, paste it into a different template, @@ -406,6 +363,8 @@ the base block by using the ``parent()`` Twig function: templating engine. You have to manually copy the content from the base block to your new template file. +.. _twig: + Making Application-wide Customizations -------------------------------------- @@ -413,9 +372,6 @@ If you'd like a certain form customization to be global to your application, you can accomplish this by making the form customizations in an external template and then importing it inside your application configuration. -Twig -~~~~ - By using the following configuration, any customized form blocks inside the ``form/fields.html.twig`` template will be used globally when a form is rendered. @@ -512,125 +468,6 @@ your template file rather than adding the template as a resource: Note that the ``form`` variable in the above code is the form view variable that you passed to your template. -PHP -~~~ - -By using the following configuration, any customized form fragments inside the -``app/Resources/views/Form`` folder will be used globally when a -form is rendered. - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - templating: - form: - resources: - - 'AppBundle:Form' - # ... - - .. code-block:: xml - - - - - - - - - AppBundle:Form - - - - - - - .. code-block:: php - - // app/config/config.php - // PHP - $container->loadFromExtension('framework', array( - 'templating' => array( - 'form' => array( - 'resources' => array( - 'AppBundle:Form', - ), - ), - ), - - // ... - )); - -By default, the PHP engine uses a *div* layout when rendering forms. Some people, -however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable`` -resource to use such a layout: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - templating: - form: - resources: - - 'FrameworkBundle:FormTable' - - .. code-block:: xml - - - - - - - - - FrameworkBundle:FormTable - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('framework', array( - 'templating' => array( - 'form' => array( - 'resources' => array( - 'FrameworkBundle:FormTable', - ), - ), - ), - - // ... - )); - -If you only want to make the change in one template, add the following line to -your template file rather than adding the template as a resource: - -.. code-block:: html+php - - setTheme($form, array('FrameworkBundle:FormTable')); ?> - -Note that the ``$form`` variable in the above code is the form view variable -that you passed to your template. - How to Customize an individual Field ------------------------------------ @@ -866,7 +703,7 @@ Adding a "Required" Asterisk to Field Labels If you want to denote all of your required fields with a required asterisk (``*``), you can do this by customizing the ``form_label`` fragment. -In Twig, if you're making the form customization inside the same template as your +If you're making the form customization inside the same template as your form, modify the ``use`` tag and add the following: .. code-block:: html+twig @@ -881,7 +718,7 @@ form, modify the ``use`` tag and add the following: {% endif %} {% endblock %} -In Twig, if you're making the form customization inside a separate template, use +If you're making the form customization inside a separate template, use the following: .. code-block:: html+twig @@ -896,24 +733,6 @@ the following: {% endif %} {% endblock %} -When using PHP as a templating engine you have to copy the content from the -original template: - -.. code-block:: html+php - - - - - - - humanize($name); } ?> - - - - - * - - .. tip:: See :ref:`form-theming-methods` for how to apply this customization. @@ -934,7 +753,7 @@ Adding "help" Messages You can also customize your form widgets to have an optional "help" message. -In Twig, if you're making the form customization inside the same template as your +If you're making the form customization inside the same template as your form, modify the ``use`` tag and add the following: .. code-block:: html+twig @@ -949,7 +768,7 @@ form, modify the ``use`` tag and add the following: {% endif %} {% endblock %} -In Twig, if you're making the form customization inside a separate template, use +If you're making the form customization inside a separate template, use the following: .. code-block:: html+twig @@ -964,25 +783,6 @@ the following: {% endif %} {% endblock %} -When using PHP as a templating engine you have to copy the content from the -original template: - -.. code-block:: html+php - - - - - value="escape($value) ?>" - block($form, 'widget_attributes') ?> - /> - - - - escape($help) ?> - - To render a help message below a field, pass in a ``help`` variable: .. code-block:: twig diff --git a/templating/PHP.rst b/templating/PHP.rst index 86b1d5abc79..1c4b31fc96b 100644 --- a/templating/PHP.rst +++ b/templating/PHP.rst @@ -382,4 +382,220 @@ instance, to output something in a JavaScript script, use the ``js`` context:: escape($var, 'js') ?> +Form Theming in PHP +------------------- + +When using PHP as a templating engine, the only method to customize a fragment +is to create a new template file - this is similar to the second method used by +Twig. + +The template file must be named after the fragment. You must create a ``integer_widget.html.php`` +file in order to customize the ``integer_widget`` fragment. + +.. code-block:: html+php + + +
+ block( + $form, + 'form_widget_simple', + array('type' => isset($type) ? $type : "number") + ) ?> +
+ +Now that you've created the customized form template, you need to tell Symfony +to use it. Inside the template where you're actually rendering your form, +tell Symfony to use the theme via the ``setTheme()`` helper method:: + + setTheme($form, array(':form')); ?> + + widget($form['age']) ?> + +When the ``form.age`` widget is rendered, Symfony will use the customized +``integer_widget.html.php`` template and the ``input`` tag will be wrapped in +the ``div`` element. + +If you want to apply a theme to a specific child form, pass it to the ``setTheme()`` +method:: + + setTheme($form['child'], ':form'); ?> + +.. note:: + + The ``:form`` syntax is based on the functional names for templates: + ``Bundle:Directory``. As the form directory lives in the + ``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting + in ``:form``. + +Making Application-wide Customizations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you'd like a certain form customization to be global to your application, +you can accomplish this by making the form customizations in an external +template and then importing it inside your application configuration. + +By using the following configuration, any customized form fragments inside the +``app/Resources/views/Form`` folder will be used globally when a +form is rendered. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + templating: + form: + resources: + - 'AppBundle:Form' + # ... + + .. code-block:: xml + + + + + + + + + AppBundle:Form + + + + + + + .. code-block:: php + + // app/config/config.php + // PHP + $container->loadFromExtension('framework', array( + 'templating' => array( + 'form' => array( + 'resources' => array( + 'AppBundle:Form', + ), + ), + ), + + // ... + )); + +By default, the PHP engine uses a *div* layout when rendering forms. Some people, +however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable`` +resource to use such a layout: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + templating: + form: + resources: + - 'FrameworkBundle:FormTable' + + .. code-block:: xml + + + + + + + + + FrameworkBundle:FormTable + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'templating' => array( + 'form' => array( + 'resources' => array( + 'FrameworkBundle:FormTable', + ), + ), + ), + + // ... + )); + +If you only want to make the change in one template, add the following line to +your template file rather than adding the template as a resource: + +.. code-block:: html+php + + setTheme($form, array('FrameworkBundle:FormTable')); ?> + +Note that the ``$form`` variable in the above code is the form view variable +that you passed to your template. + +Adding a "Required" Asterisk to Field Labels +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to denote all of your required fields with a required asterisk +(``*``), you can do this by customizing the ``form_label`` fragment. + +When using PHP as a templating engine you have to copy the content from the +original template: + +.. code-block:: html+php + + + + + + + humanize($name); } ?> + + + + + * + + +Adding "help" Messages +~~~~~~~~~~~~~~~~~~~~~~ + +You can also customize your form widgets to have an optional "help" message. + +When using PHP as a templating engine you have to copy the content from the +original template: + +.. code-block:: html+php + + + + + value="escape($value) ?>" + block($form, 'widget_attributes') ?> + /> + + + + escape($help) ?> + + .. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view