Permalink
Browse files

bug #3543 Fix the definition of customizing form's global errors. (mt…

…rojanowski)

This PR was merged into the 2.3 branch.

Discussion
----------

Fix the definition of customizing form's global errors.

The documentation for customizing global errors was actually still referring to the way it was done in 2.0. (where two different blocks were used: `field_errors` and `form_errors`). Since 2.1. only `form_errors` is used and errors are differentiated using the `compound` variable (set to `true` for form errors).

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.3+
| Fixed tickets | #3542

Commits
-------

6f6fcca Applied some changes according to comments.
e3b20d8 Minor rewording. Added tip about meaning of `compound` var and expanded the example code to contain `else` statements.
1e278c4 Added note about customizing errors for different field types.
236d06b Fix the definition of customizing form's global errors.
  • Loading branch information...
weaverryan committed Mar 18, 2014
2 parents 2192c32 + 6f6fcca commit 4ce7a15e92a82541bee319206620cb175978844f
Showing with 51 additions and 5 deletions.
  1. +51 −5 cookbook/form/form_customization.rst
@@ -771,8 +771,17 @@ and customize the ``form_errors`` fragment.
See :ref:`cookbook-form-theming-methods` for how to apply this customization.
You can also customize the error output for just one specific field type.
For example, certain errors that are more global to your form (i.e. not specific
to just one field) are rendered separately, usually at the top of your form:
To customize *only* the markup used for these errors, follow the same directions
as above but put the contents in a relative ``_errors`` block (or file in case
of PHP templates). For example: ``text_errors`` (or ``text_errors.html.php``).
.. tip::
See :ref:`form-template-blocks` to find out which specific block or file you
have to customize.
Certain errors that are more global to your form (i.e. not specific to just one
field) are rendered separately, usually at the top of your form:
.. configuration-block::
@@ -785,9 +794,46 @@ to just one field) are rendered separately, usually at the top of your form:
<?php echo $view['form']->render($form); ?>
To customize *only* the markup used for these errors, follow the same directions
as above, but now call the block ``form_errors`` (Twig) / the file ``form_errors.html.php``
(PHP). Now, when errors for the ``form`` type are rendered, your customized
fragment will be used instead of the default ``form_errors``.
as above, but now check if the ``compound`` variable is set to ``true``. If it
is ``true``, it means that what's being currently rendered is a collection of
fields (e.g. a whole form), and not just an individual field.
.. configuration-block::
.. code-block:: html+jinja
{# form_errors.html.twig #}
{% block form_errors %}
{% spaceless %}
{% if errors|length > 0 %}
{% if compound %}
<ul>
{% for error in errors %}
<li>{{ error.message }}</li>
{% endfor %}
</ul>
{% else %}
{# ... display the errors for a single field #}
{% endif %}
{% endif %}
{% endspaceless %}
{% endblock form_errors %}
.. code-block:: html+php
<!-- form_errors.html.php -->
<?php if ($errors): ?>
<?php if ($compound): ?>
<ul>
<?php foreach ($errors as $error): ?>
<li><?php echo $error->getMessage() ?></li>
<?php endforeach; ?>
</ul>
<?php else: ?>
<!-- ... render the errors for a single field -->
<?php endif; ?>
<?php endif ?>
Customizing the "Form Row"
~~~~~~~~~~~~~~~~~~~~~~~~~~

0 comments on commit 4ce7a15

Please sign in to comment.