From b1c35cd1fc4d5b584d0a494b9c2d2a077367a9be Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Thu, 12 Sep 2024 19:12:58 +0200 Subject: [PATCH] Tweak docs --- doc/filters/slice.rst | 2 +- doc/functions/attribute.rst | 2 +- doc/templates.rst | 100 +++++++++++++++++++++--------------- 3 files changed, 61 insertions(+), 43 deletions(-) diff --git a/doc/filters/slice.rst b/doc/filters/slice.rst index 3642b85d8..47af2b923 100644 --- a/doc/filters/slice.rst +++ b/doc/filters/slice.rst @@ -21,7 +21,7 @@ You can use any valid expression for both the start and the length: {# ... #} {% endfor %} -As syntactic sugar, you can also use the ``[]`` notation: +As syntactic sugar, you can also use the ``[]`` operator: .. code-block:: twig diff --git a/doc/functions/attribute.rst b/doc/functions/attribute.rst index 832859de1..96ec6ea11 100644 --- a/doc/functions/attribute.rst +++ b/doc/functions/attribute.rst @@ -20,7 +20,7 @@ attribute: .. note:: The resolution algorithm is the same as the one used for the ``.`` - notation, except that the item can be any valid expression. + operator, except that the item can be any valid expression. Arguments --------- diff --git a/doc/templates.rst b/doc/templates.rst index 199d40fe4..6a4ab80c9 100644 --- a/doc/templates.rst +++ b/doc/templates.rst @@ -72,17 +72,16 @@ You might also be interested in: Variables --------- -The application passes variables to the templates for manipulation in the -template. Variables may have attributes or elements you can access, too. The -visual representation of a variable depends heavily on the application providing -it. +Twig templates have access to variables provided by the PHP application and +variables created in templates via the :doc:`set ` tag. These +variables can be manipulated and displayed in the template. Use a dot (``.``) to access attributes of a variable (methods or properties of a PHP object, or items of a PHP array): .. code-block:: twig - {{ foo.bar }} + {{ user.name }} .. note:: @@ -97,41 +96,7 @@ If a variable or attribute does not exist, the behavior depends on the * When ``false``, it returns ``null``; * When ``true``, it throws an exception. -.. sidebar:: Implementation - - For convenience's sake ``foo.bar`` does the following things on the PHP - layer: - - * check if ``foo`` is a sequence or a mapping and ``bar`` a valid element; - * if not, and if ``foo`` is an object, check that ``bar`` is a valid property; - * if not, and if ``foo`` is an object, check that ``bar`` is a valid method - (even if ``bar`` is the constructor - use ``__construct()`` instead); - * if not, and if ``foo`` is an object, check that ``getBar`` is a valid method; - * if not, and if ``foo`` is an object, check that ``isBar`` is a valid method; - * if not, and if ``foo`` is an object, check that ``hasBar`` is a valid method; - * if not, and if ``strict_variables`` is ``false``, return ``null``; - * if not, throw an exception. - - Twig also supports a specific syntax for accessing items on PHP arrays, - ``foo['bar']``: - - * check if ``foo`` is a sequence or a mapping and ``bar`` a valid element; - * if not, and if ``strict_variables`` is ``false``, return ``null``; - * if not, throw an exception. - -.. note:: - - If you want to access a dynamic attribute of a variable, use the - :doc:`attribute` function instead. - - The ``attribute`` function is also useful when the attribute contains - special characters (like ``-`` that would be interpreted as the minus - operator): - - .. code-block:: twig - - {# equivalent to the non-working foo.data-foo #} - {{ attribute(foo, 'data-foo') }} +Learn more about the :ref:`dot operator `. Global Variables ~~~~~~~~~~~~~~~~ @@ -798,8 +763,60 @@ The following operators don't fit into any of the other categories: " ~ name ~ "!" }}`` would return (assuming ``name`` is ``'John'``) ``Hello John!``. +.. _dot_operator: + * ``.``, ``[]``: Gets an attribute of a variable. + The (``.``) operator abstracts getting an attribute of a variable (methods + or properties of a PHP object, or items of a PHP array): + + .. code-block:: twig + + {{ user.name }} + + .. sidebar:: PHP Implementation + + To resolve ``user.name`` to a PHP call, Twig uses the following algorithm + at runtime: + + * check if ``user`` is a PHP array or a ArrayObject/ArrayAccess object and + ``name`` a valid element; + * if not, and if ``user`` is a PHP object, check that ``name`` is a valid property; + * if not, and if ``user`` is a PHP object, check the following methods and + call the first valid one: ``name()``, ``getName()``, ``isName()``, or + ``hasName()``; + * if not, and if ``strict_variables`` is ``false``, return ``null``; + * if not, throw an exception. + + Twig supports a specific syntax via the ``[]`` operator for accessing items + on sequences and mappings, like in ``user['name']``: + + * check if ``user`` is an array and ``name`` a valid element; + * if not, and if ``strict_variables`` is ``false``, return ``null``; + * if not, throw an exception. + + Twig supports a specific syntax via the ``()`` operator for calling methods + on objects, like in ``user.name()``: + + * check if ``user`` is a object and has the ``name()``, ``getName()``, + ``isName()``, or ``hasName()`` method; + * if not, and if ``strict_variables`` is ``false``, return ``null``; + * if not, throw an exception. + + .. note:: + + If you want to access a dynamic attribute of a variable, use the + :doc:`attribute` function instead. + + The ``attribute`` function is also useful when the attribute contains + special characters (like ``-`` that would be interpreted as the minus + operator): + + .. code-block:: twig + + {# equivalent to the non-working user.first-name #} + {{ attribute(user, 'first-name') }} + * ``?:``: The ternary operator: .. code-block:: twig @@ -876,7 +893,8 @@ determine how to convert the code to PHP: {# it is converted to the following PHP code: (6 & 2) || (6 & 16) #} -Change the default precedence by explicitly grouping expressions with parentheses: +Change the default precedence by explicitly grouping expressions with +parentheses: .. code-block:: twig