mirror of
https://github.com/twigphp/Twig.git
synced 2026-08-30 12:06:56 +00:00
tweaked docs for macros
This commit is contained in:
Fabien Potencier
+1
-3
@@ -3,6 +3,4 @@
|
||||
|
||||
The ``from`` tag imports :doc:`macro<../tags/macro>` names into the current
|
||||
namespace. The tag is documented in detail in the documentation for the
|
||||
:doc:`import<../tags/import>` tag.
|
||||
|
||||
.. seealso:: :doc:`macro<../tags/macro>`, :doc:`import<../tags/import>`
|
||||
:doc:`macro<../tags/macro>` tag.
|
||||
|
||||
+3
-62
@@ -1,65 +1,6 @@
|
||||
``import``
|
||||
==========
|
||||
|
||||
Twig supports putting often used code into :doc:`macros<../tags/macro>`. These
|
||||
macros are defined in regular templates.
|
||||
|
||||
Imagine having a generic helper template that define how to render forms via
|
||||
macros (called ``forms.html``):
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% macro input(name, value, type, size) %}
|
||||
<input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
|
||||
{% endmacro %}
|
||||
|
||||
{% macro textarea(name, value, rows, cols) %}
|
||||
<textarea name="{{ name }}" rows="{{ rows|default(10) }}" cols="{{ cols|default(40) }}">{{ value|e }}</textarea>
|
||||
{% endmacro %}
|
||||
|
||||
There are two ways to import macros. You can import the complete template
|
||||
containing the macros into a local variable or only import specific macros from
|
||||
the template.
|
||||
|
||||
The easiest and most flexible is importing the whole module into a local
|
||||
variable:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% import 'forms.html' as forms %}
|
||||
|
||||
<dl>
|
||||
<dt>Username</dt>
|
||||
<dd>{{ forms.input('username') }}</dd>
|
||||
<dt>Password</dt>
|
||||
<dd>{{ forms.input('password', null, 'password') }}</dd>
|
||||
</dl>
|
||||
<p>{{ forms.textarea('comment') }}</p>
|
||||
|
||||
Alternatively you can import names from the template into the current
|
||||
namespace:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% from 'forms.html' import input as input_field, textarea %}
|
||||
|
||||
<dl>
|
||||
<dt>Username</dt>
|
||||
<dd>{{ input_field('username') }}</dd>
|
||||
<dt>Password</dt>
|
||||
<dd>{{ input_field('password', '', 'password') }}</dd>
|
||||
</dl>
|
||||
<p>{{ textarea('comment') }}</p>
|
||||
|
||||
.. note::
|
||||
|
||||
Importing macros using ``import`` or ``from`` is **local** to the current
|
||||
file. The imported macros are not available in included templates or child
|
||||
templates; you need to explicitely re-import macros in each file.
|
||||
|
||||
.. tip::
|
||||
|
||||
To import macros from the current file, use the special ``_self`` variable
|
||||
for the source.
|
||||
|
||||
.. seealso:: :doc:`macro<../tags/macro>`, :doc:`from<../tags/from>`
|
||||
The ``import`` tag imports :doc:`macro<../tags/macro>` names in a local
|
||||
variable. The tag is documented in detail in the documentation for the
|
||||
:doc:`macro<../tags/macro>` tag.
|
||||
|
||||
+51
-29
@@ -7,10 +7,12 @@
|
||||
signature was added in Twig 1.12.
|
||||
|
||||
Macros are comparable with functions in regular programming languages. They
|
||||
are useful to put often used HTML idioms into reusable elements to not repeat
|
||||
yourself.
|
||||
are useful to reuse template fragments to not repeat yourself.
|
||||
|
||||
Here is a small example of a macro that renders a form element:
|
||||
Macros are defined in regular templates.
|
||||
|
||||
Imagine having a generic helper template that define how to render HTML forms
|
||||
via macros (called ``forms.html``):
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
@@ -18,8 +20,12 @@ Here is a small example of a macro that renders a form element:
|
||||
<input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}" />
|
||||
{% endmacro %}
|
||||
|
||||
Each argument can have a default value (here ``text`` is the default value for
|
||||
``type`` if not provided in the call).
|
||||
{% macro textarea(name, value, rows = 10, cols = 40) %}
|
||||
<textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value|e }}</textarea>
|
||||
{% endmacro %}
|
||||
|
||||
Each macro argument can have a default value (here ``text`` is the default value
|
||||
for ``type`` if not provided in the call).
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -50,41 +56,28 @@ variables.
|
||||
Import
|
||||
------
|
||||
|
||||
Macros can be defined in any template, and need to be "imported" before being
|
||||
used (see the documentation for the :doc:`import<../tags/import>` tag for more
|
||||
information):
|
||||
There are two ways to import macros. You can import the complete template
|
||||
containing the macros into a local variable (via the ``import`` tag) or only
|
||||
import specific macros from the template (via the ``from`` tag).
|
||||
|
||||
To import all macros from a template into a local variable, use the ``import``
|
||||
tag:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% import "forms.html" as forms %}
|
||||
|
||||
The above ``import`` call imports the "forms.html" file (which can contain only
|
||||
macros, or a template and some macros), and import the functions as items of
|
||||
The above ``import`` call imports the ``forms.html`` file (which can contain
|
||||
only macros, or a template and some macros), and import the macros as items of
|
||||
the ``forms`` local variable.
|
||||
|
||||
The macro can then be called at will in the current template:
|
||||
The macros can then be called at will in the *current* template:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
<p>{{ forms.input('username') }}</p>
|
||||
<p>{{ forms.input('password', null, 'password') }}</p>
|
||||
|
||||
If macros are defined and used in the same template, you can use the
|
||||
special ``_self`` variable to import them:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% import _self as forms %}
|
||||
|
||||
<p>{{ forms.input('username') }}</p>
|
||||
|
||||
.. warning::
|
||||
|
||||
When you define a macro in the template where you are going to use it, you
|
||||
might be tempted to call the macro directly via ``_self.input()`` instead of
|
||||
importing it; even if it seems to work, this is just a side-effect of the
|
||||
current implementation and it won't work anymore in Twig 2.x.
|
||||
|
||||
When you want to use a macro in another macro from the same file, you need to
|
||||
import it locally:
|
||||
|
||||
@@ -102,6 +95,37 @@ import it locally:
|
||||
</div>
|
||||
{% endmacro %}
|
||||
|
||||
Alternatively you can import names from the template into the current namespace
|
||||
via the ``from`` tag:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% from 'forms.html' import input as input_field, textarea %}
|
||||
|
||||
<p>{{ input_field('password', '', 'password') }}</p>
|
||||
<p>{{ textarea('comment') }}</p>
|
||||
|
||||
.. note::
|
||||
|
||||
Importing macros using ``import`` or ``from`` is **local** to the current
|
||||
file. The imported macros are not available in included templates or child
|
||||
templates; you need to explicitely re-import macros in each file.
|
||||
|
||||
.. tip::
|
||||
|
||||
To import macros from the current file, use the special ``_self`` variable:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% import _self as forms %}
|
||||
|
||||
<p>{{ forms.input('username') }}</p>
|
||||
|
||||
When you define a macro in the template where you are going to use it, you
|
||||
might be tempted to call the macro directly via ``_self.input()`` instead of
|
||||
importing it; even if it seems to work, this is just a side-effect of the
|
||||
current implementation and it won't work anymore in Twig 2.x.
|
||||
|
||||
Named Macro End-Tags
|
||||
--------------------
|
||||
|
||||
@@ -115,5 +139,3 @@ readability:
|
||||
{% endmacro input %}
|
||||
|
||||
Of course, the name after the ``endmacro`` word must match the macro name.
|
||||
|
||||
.. seealso:: :doc:`from<../tags/from>`, :doc:`import<../tags/import>`
|
||||
|
||||
+3
-46
@@ -499,52 +499,9 @@ Macros
|
||||
.. versionadded:: 1.12
|
||||
Support for default argument values was added in Twig 1.12.
|
||||
|
||||
Macros are comparable with functions in regular programming languages. They
|
||||
are useful to reuse often used HTML fragments to not repeat yourself.
|
||||
|
||||
A macro is defined via the :doc:`macro<tags/macro>` tag. Here is a small example
|
||||
(subsequently called ``forms.html``) of a macro that renders a form element:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% macro input(name, value, type, size) %}
|
||||
<input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
|
||||
{% endmacro %}
|
||||
|
||||
Macros can be defined in any template, and need to be "imported" via the
|
||||
:doc:`import<tags/import>` tag before being used:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% import "forms.html" as forms %}
|
||||
|
||||
<p>{{ forms.input('username') }}</p>
|
||||
|
||||
Alternatively, you can import individual macro names from a template into the
|
||||
current namespace via the :doc:`from<tags/from>` tag and optionally alias them:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% from 'forms.html' import input as input_field %}
|
||||
|
||||
<dl>
|
||||
<dt>Username</dt>
|
||||
<dd>{{ input_field('username') }}</dd>
|
||||
<dt>Password</dt>
|
||||
<dd>{{ input_field('password', '', 'password') }}</dd>
|
||||
</dl>
|
||||
|
||||
A default value can also be defined for macro arguments when not provided in a
|
||||
macro call:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% macro input(name, value = "", type = "text", size = 20) %}
|
||||
<input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}" />
|
||||
{% endmacro %}
|
||||
|
||||
If extra positional arguments are passed to a macro call, they end up in the
|
||||
special ``varargs`` variable as a list of values.
|
||||
Macros are comparable with functions in regular programming languages. They are
|
||||
useful to reuse HTML fragments to not repeat yourself. They are described in the
|
||||
:doc:`macro<tags/macro>` tag documentation.
|
||||
|
||||
.. _twig-expressions:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user