.. include:: /Includes.rst.txt

.. _variables:

=========
Variables
=========

Assign a variable in PHP:

..  code-block:: php

    $this->view->assign('title', 'An example title');

In the template's HTML code, wrap the variable name into curly
braces to output it:

..  code-block:: html

    <h1>{title}</h1>

The result:

..  code-block:: html

    <h1>An example title</h1>

.. _variable-escaping:

Output Escaping for Variables
=============================

By default, Fluid escapes the output of variables to prevent cross-site-scripting
attacks. If a variable contains characters that have special meaning in HTML, such
as `<` or `>`, these will be replaced with the matching HTML entities, such as
`&lt;` or `&gt;`.

This can be avoided by passing the variable to a ViewHelper that disables output
escaping, such as `<f:format.raw> <https://docs.typo3.org/permalink/fluid:typo3fluid-fluid-format-raw>`_.

..  important::
    Be extra careful when using `<f:format.raw>` in your template. Make sure that all
    user-provided input is escaped properly!

The following variable:

..  code-block:: php

    $this->view->assign('title', 'An <b>example</b> title');

would be escaped automatically in a template, unless wrapped in `<f:format.raw>`:

..  code-block:: html
    {title}
    Result: An &lt;b&gt;example&lt;/b&gt; title

    <f:format.raw>{title}</f:format.raw>
    Result: An <b>example</b> title

.. _variable-all:

Special _all Variable
=====================

The special variable `{_all}` contains an array with all variables that are currently
defined in your template. This can be helpful for debugging purposes, but also if you
want to pass all variables to a partial:

..  code-block:: xml

    <f:render partial="MyPartial" arguments="{_all}" />

However, be advised that this makes it more difficult to re-use partials, so it's recommend
to only pass the variables that are actually needed in the partial.

.. _variable-scopes:

Variable Scopes
===============

Each Fluid template, partial and section has its own variable scope. For templates,
these variables are set via the PHP API, for partials and sections the `<f:render>`
ViewHelper has a `arguments` argument to provide variables.

Inside templates, partials and sections there are two variable scopes: global
variables and local variables. Local variables are created by ViewHelpers that
provide additional variables to their child nodes. Local variables are only valid
in their appropriate context and don't leak out to the whole template.

For example, `<f:alias>` and `<f:for>` create local variables:

.. code-block:: xml

    <f:for each="{items}" as="item">
        <!-- {item} is valid here -->
    </f:for>
    <!-- {item} is no longer valid here -->

    <f:alias map="{item: myObject.sub.item}">
        <!-- {item} is valid here -->
    </f:for>
    <!-- {item} is no longer valid here -->

If a global variable uses the same name as a local value, the state of the global
value will be restored when the local variable is invalidated:

.. code-block:: xml

    <f:variable name="item" value="global item" />
    <!-- {item} is "global item" -->
    <f:for each="{0: 'local item'}" as="item">
        <!-- {item} is "local item" -->
    </f:for>
    <!-- {item} is "global item" -->

If a variable is created in a local block, for example by using the `<f:variable>`
ViewHelper, that variable is treated as a global variable, so it will leak out of
the scope:

.. code-block:: xml

    <f:for each="{0: 'first', 1: 'second'}" as="item">
        <f:variable name="lastItem" value="{item}" />
    </f:for>
    <!-- {lastItem} is "second" -->

If a global variable is created inside a local scope and uses the same name as a local
variable, it will still leak out of the scope and will also be valid inside the scope:

.. code-block:: xml

    <f:for each="{0: 'first', 1: 'second'}" as="item">
        <!-- {item} is "first" or "second" -->
        <f:variable name="item" value="overwritten" />
        <!-- {item} is "overwritten" -->
    </f:for>
    <!-- {item} is "overwritten" -->