8000 minor #12274 Reworded all the docs related to templates and Twig (jav… · symfony/symfony-docs@3ce905a · GitHub
[go: up one dir, main page]
Skip to content

Commit 3ce905a

Browse files
javiereguiluzjaviereguiluz
committed
minor #12274 Reworded all the docs related to templates and Twig (javiereguiluz)
This PR was squashed before being merged into the 4.3 branch (closes #12274). Discussion ---------- Reworded all the docs related to templates and Twig As we did in the past with other topics, this pull request revamps the templating/templates/twig docs. The main goals were: * Create a single article `/templates.rst` that explain everything about templates. * Keep some `templating/*.rst` articles for uncommon things (PHP, Twig extensions, hinclude, etc.) * Remove all the small `templating/*.rst` articles. * Simplify all explanations and reduce verbosity. * Add more cross-links between articles. ----- The TOC of the new article looks like this: ``` Twig Templating Language Twig Configuration Creating Templates Template Naming Template Location Template Variables Linking to Other Pages Linking to CSS and JavaScript Assets The App Global Variable Rendering Templates Rendering Templates in Routes Rendering Templates in Controllers Rendering Templates in Services Rendering Templates in Emails Checking if a Template Exists Debugging Templates Linting Twig Templates Inspecting Twig Information The Dump Twig Utilities Reusing Template Contents Including Templates Embedding Controllers Template Inheritance and Layouts Output Escaping Template Namespaces Learn More ``` Commits ------- ec618e1 Reworded all the docs related to templates and Twig
2 parents dac594f + ec618e1 commit 3ce905a

30 files changed

+1299
-1968
lines changed

‎_build/redirection_map

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -446,3 +446,13 @@
446446
/form/action_method /forms
447447
/reference/requirements /setup
448448
/bundles/inheritance /bundles/override
449< 628C span class="diff-text-marker">+
/templating /templates
450+
/templating/escaping /templates
451+
/templating/syntax /templates
452+
/templating/debug /templates
453+
/templating/render_without_controller /templates
454+
/templating/app_variable /templates
455+
/templating/formats /templates
456+
/templating/namespaced_paths /templates
457+
/templating/embedding_controllers /templates
458+
/templating/inheritance /templates

‎components/http_foundation.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ which is almost equivalent to the more verbose, but also more flexible,
5757
$_SERVER
5858
);
5959

60+
.. _accessing-request-data:
61+
6062
Accessing Request Data
6163
~~~~~~~~~~~~~~~~~~~~~~
6264

‎components/templating.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ Usage
2828
.. seealso::
2929

3030
This article explains how to use the Templating features as an independent
31-
component in any PHP application. Read the :doc:`/templating` article to
32-
learn about how to work with templates in Symfony applications.
31+
component in any PHP application. Read the article about :doc:`templates </templates>`
32+
to learn about how to work with templates in Symfony applications.
3333

3434
The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
3535
of the component. It needs a
@@ -211,5 +211,5 @@ Learn More
211211
:glob:
212212

213213
/components/templating/*
214-
/templating
214+
/templates
215215
/templating/*

‎configuration/front_controllers_and_kernel.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,8 @@ new kernel.
123123
.. index::
124124
single: Configuration; Debug mode
125125

126+
.. _debug-mode:
127+
126128
Debug Mode
127129
~~~~~~~~~~
128130

‎controller.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,7 @@ object for you::
179179
return $this->render('lucky/number.html.twig', ['number' => $number]);
180180

181181
Templating and Twig are explained more in the
182-
:doc:`Creating and Using Templates article </templating>`.
182+
:doc:`Creating and Using Templates article </templates>`.
183183

184184
.. index::
185185
single: Controller; Accessing services
@@ -461,7 +461,8 @@ and then redirects. The message key (``notice`` in this example) can be anything
461461
you'll use this key to retrieve the message.
462462

463463
In the template of the next page (or even better, in your base layout template),
464-
read any flash messages from the session using ``app.flashes()``:
464+
read any flash messages from the session using the ``flashes()`` method provided
465+
by the :ref:`Twig global app variable <twig-app-variable>`:
465466

466467
.. code-block:: html+twig
467468

@@ -650,15 +651,15 @@ handle caching and more.
650651
Keep Going!
651652
-----------
652653

653-
Next, learn all about :doc:`rendering templates with Twig </templating>`.
654+
Next, learn all about :doc:`rendering templates with Twig </templates>`.
654655

655656
Learn more about Controllers
656657
----------------------------
657658

658659
.. toctree::
659660
:hidden:
660661

661-
templating
662+
templates
662663

663664
.. toctree::
664665
:maxdepth: 1

‎event_dispatcher.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -206,9 +206,9 @@ Request Events, Checking Types
206206
------------------------------
207207

208208
A single page can make several requests (one master request, and then multiple
209-
sub-requests - typically by :doc:`/templating/embedding_controllers`). For the core
210-
Symfony events, you might need to check to see if the event is for a "master" request
211-
or a "sub request"::
209+
sub-requests - typically when :ref:`embedding controllers in templates <templates-embed-controllers>`).
210+
For the core Symfony events, you might need to check to see if the event is for
211+
a "master" request or a "sub request"::
212212

213213
// src/EventListener/RequestListener.php
214214
namespace App\EventListener;

‎getting_started/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,5 @@ Getting Started
88
/page_creation
99
/routing
1010
/controller
11-
/templating
11+
/templates
1212
/configuration
EED3

‎http_cache/esi.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,8 +114,8 @@ independently of the rest of the page::
114114

115115
In this example, the full-page cache has a lifetime of ten minutes.
116116
Next, include the news ticker in the template by embedding an action.
117-
This is done via the ``render`` helper (see :doc:`/templating/embedding_controllers`
118-
for more details).
117+
This is done via the ``render()`` helper (for more details, see how to
118+
:ref:`embed controllers in templates <templates-embed-controllers>`).
119119

120120
As the embedded content comes from another page (or controller for that
121121
matter), Symfony uses the standard ``render`` helper to configure ESI tags:

‎introduction/from_flat_php_to_symfony.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -532,7 +532,7 @@ a simple application. Along the way, you've made a simple routing
532532
system and a method using ``ob_start()`` and ``ob_get_clean()`` to render
533533
templates. If, for some reason, you needed to continue building this "framework"
534534
from scratch, you could at least use Symfony's standalone
535-
:doc:`Routing </components/routing>` component and :doc:`Twig </templating>`,
535+
:doc:`Routing </components/routing>` component and :doc:`Twig </templates>`,
536536
which already solve these problems.
537537

538538
Instead of re-solving common problems, you can let Symfony take care of

‎mailer.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -291,7 +291,7 @@ create an event subscriber to set it automatically::
291291
Twig: HTML & CSS
292292
----------------
293293

294-
The Mime component integrates with the :doc:`Twig template engine </templating>`
294+
The Mime component integrates with the :ref:`Twig template engine <twig-language>`
295295
to provide advanced features such as CSS style inlining and support for HTML/CSS
296296
frameworks to create complex HTML email messages. First, make sure Twig is installed:
297297

‎page_creation.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -251,8 +251,8 @@ Now you may wonder where the Web Debug Toolbar has gone: that's because there is
251251
no ``</body>`` tag in the current template. You can add the body element yourself,
252252
or extend ``base.html.twig``, which contains all default HTML elements.
253253

254-
In the :doc:`/templating` article, you'll learn all about Twig: how to loop, render
255-
other templates and leverage its powerful layout inheritance system.
254+
In the :doc:`templates </templates>` article, you'll learn all about Twig: how
255+
to loop, render other templates and leverage its powerful layout inheritance system.
256256

257257
Checking out the Project Structure
258258
----------------------------------
@@ -304,7 +304,7 @@ Ok, time to finish mastering the fundamentals by reading these articles:
304304

305305
* :doc:`/routing`
306306
* :doc:`/controller`
307-
* :doc:`/templating`
307+
* :doc:`/templates`
308308
* :doc:`/configuration`
309309

310310
Then, learn about other important topics like the

‎reference/configuration/twig.rst

Lines changed: 40 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ Twig Configuration Reference (TwigBundle)
55
=========================================
66

77
The TwigBundle integrates the Twig library in Symfony applications to
8-
:doc:`render templates </templating>`. All these options are configured under
9-
the ``twig`` key in your application configuration.
8+
:ref:`render templates <templates-rendering>`. All these options are configured
9+
under the ``twig`` key in your application configuration.
1010

1111
.. code-block:: terminal
1212
@@ -41,8 +41,10 @@ Configuration
4141
* `timezone`_
4242

4343
* `debug`_
44+
* `default_path`_
4445
* `exception_controller`_
4546
* `form_themes`_
47+
* `globals`_
4648
* `number_format`_
4749

4850
* `decimals`_
@@ -62,6 +64,8 @@ If ``true``, whenever a template is rendered, Symfony checks first if its source
6264
code has changed since it was compiled. If it has changed, the template is
6365
compiled again automatically.
6466

67+
.. _config-twig-autoescape:
68+
6569
autoescape
6670
~~~~~~~~~~
6771

@@ -73,7 +77,7 @@ individually in the templates).
7377
.. caution::
7478

7579
Setting this option to ``false`` is dangerous and it will make your
76-
application vulnerable to XSS exploits because most third-party bundles
80+
application vulnerable to `XSS attacks`_ because most third-party bundles
7781
assume that auto-escaping is enabled and they don't escape contents
7882
themselves.
7983

@@ -139,8 +143,8 @@ charset
139143
**type**: ``string`` **default**: ``'%kernel.charset%'``
140144

141145
The charset used by the template files. By default it's the same as the value of
142-
the ``kernel.charset`` container parameter, which is ``UTF-8`` by default in
143-
Symfony applications.
146+
the :ref:`kernel.charset container parameter <configuration-kernel-charset>`,
147+
which is ``UTF-8`` by default in Symfony applications.
144148

145149
date
146150
~~~~
@@ -181,6 +185,17 @@ debug
181185
If ``true``, the compiled templates include a ``__toString()`` method that can
182186
be used to display their nodes.
183187

188+
.. _config-twig-default-path:
189+
190+
default_path
191+
~~~~~~~~~~~~
192+
193+
**type**: ``string`` **default**: ``'%kernel.project_dir%/templates'``
194+
195+
The path to the directory where Symfony will look for the application Twig
196+
templates by default. If you store the templates in more than one directory, use
197+
the :ref:`paths <config-twig-paths>` option too.
198+
184199
.. _config-twig-exception-controller:
185200

186201
exception_controller
@@ -195,7 +210,8 @@ is what's responsible for rendering specific templates under different error
195210
conditions (see :doc:`/controller/error_pages`). Modifying this
196211
option is advanced. If you need to customize an error page you should use
197212
the previous link. If you need to perform some behavior on an exception,
198-
you should add a listener to the ``kernel.exception`` event (see :ref:`dic-tags-kernel-event-listener`).
213+
you should add an :doc:`event listener </event_dispatcher>` to the
214+
:ref:`kernel.exception event <kernel-kernel.exception>`.
199215

200216
.. _config-twig-form-themes:
201217

@@ -253,6 +269,14 @@ These global themes are applied to all forms, even those which use the
253269
:ref:`form_theme Twig tag <reference-twig-tag-form-theme>`, but you can
254270
:ref:`disable global themes for specific forms <disabling-global-themes-for-single-forms>`.
255271

272+
globals
273+
~~~~~~~
274+
275+
**type**: ``array`` **default**: ``[]``
276+
277+
It defines the global variables injected automatically into all Twig templates.
278+
Learn more about :doc:`Twig global variables </templating/global_variables>`.
279+
256280
number_format
257281
~~~~~~~~~~~~~
258282

@@ -301,39 +325,15 @@ on. Set it to ``0`` to disable all the optimizations. You can even enable or
301325
disable these optimizations selectively, as explained in the Twig documentation
302326
about `the optimizer extension`_.
303327

304-
.. _config-twig-default-path:
305-
306-
default_path
307-
~~~~~~~~~~~~
308-
309-
**type**: ``string`` **default**: ``'%kernel.project_dir%/templates'``
310-
311-
The default directory where Symfony will look for Twig templates.
312-
313328
.. _config-twig-paths:
314329

315330
paths
316331
~~~~~
317332

318333
**type**: ``array`` **default**: ``null``
319334

320-
.. deprecated:: 4.2
321-
322-
Using the ``src/Resources/views/`` directory to store templates was
323-
deprecated in Symfony 4.2. Use instead the directory defined in the
324-
``default_path`` option (which is ``templates/`` by default).
325-
326-
This option defines the directories where Symfony will look for Twig templates
327-
in addition to the default locations. Symfony looks for the templates in the
328-
following order:
329-
330-
#. The directories defined in this option;
331-
#. The ``Resources/views/`` directories of the bundles used in the application;
332-
#. The ``src/Resources/views/`` directory of the application;
333-
#. The directory defined in the ``default_path`` option.
334-
335-
The values of the ``paths`` option are defined as ``key: value`` pairs where the
336-
``value`` part can be ``null``. For example:
335+
Defines the directories where application templates are stored in addition to
336+
the directory defined in the :ref:`default_path option <config-twig-default-path>`:
337337

338338
.. configuration-block::
339339

@@ -343,7 +343,8 @@ The values of the ``paths`` option are defined as ``key: value`` pairs where the
343343
twig:
344344
# ...
345345
paths:
346-
'%kernel.project_dir%/vendor/acme/foo-bar/templates': ~
346+
'email/default/templates': ~
347+
'backend/templates': 'admin'
347348
348349
.. code-block:: xml
349350
@@ -357,7 +358,8 @@ The values of the ``paths`` option are defined as ``key: value`` pairs where the
357358
358359
<twig:config>
359360
<!-- ... -->
360-
<twig:path>%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
361+
<twig:path>email/default/templates</twig:path>
362+
<twig:path namespace="admin">backend/templates</twig:path>
361363
</twig:config>
362364
</container>
363365
@@ -367,60 +369,12 @@ The values of the ``paths`` option are defined as ``key: value`` pairs where the
367369
$container->loadFromExtension('twig', [
368370
// ...
369371
'paths' => [
370-
'%kernel.project_dir%/vendor/acme/foo-bar/templates' => null,
372+
'email/default/templates' => null,
373+
'backend/templates' => 'admin',
371374
],
372375
]);
373376
374-
The directories defined in the ``paths`` option have more priority than the
375-
default directories defined by Symfony. In the above example, if the template
376-
exists in the ``acme/foo-bar/templates/`` directory inside your application's
377-
``vendor/``, it will be used by Symfony.
378-
379-
If you provide a value for any path, Symfony will consider it the Twig namespace
380-
for that directory:
381-
382-
.. configuration-block::
383-
384-
.. code-block:: yaml
385-
386-
# config/packages/twig.yaml
387-
twig:
388-
# ...
538E
389-
paths:
390-
'%kernel.project_dir%/vendor/acme/foo-bar/templates': 'foo_bar'
391-
392-
.. code-block:: xml
393-
394-
<!-- config/packages/twig.xml -->
395-
<container xmlns="http://symfony.com/schema/dic/services"
396-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
397-
xmlns:twig="http://symfony.com/schema/dic/twig"
398-
xsi:schemaLocation="http://symfony.com/schema/dic/services
399-
https://symfony.com/schema/dic/services/services-1.0.xsd
400-
http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
401-
402-
<twig:config>
403-
<!-- ... -->
404-
<twig:path namespace="foo_bar">%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
405-
</twig:config>
406-
</container>
407-
408-
.. code-block:: php
409-
410-
# config/packages/twig.php
411-
$container->loadFromExtension('twig', [
412-
// ...
413-
'paths' => [
414-
'%kernel.project_dir%/vendor/acme/foo-bar/templates' => 'foo_bar',
415-
],
416-
]);
417-
418-
This option is useful to not mess with the default template directories defined
419-
by Symfony. Besides, it simplifies how you refer to those templates:
420-
421-
.. code-block:: text
422-
423-
@foo_bar/template_name.html.twig
377+
Read more about :ref:`template directories and namespaces <templates-namespaces>`.
424378

425379
strict_variables
426380
~~~~~~~~~~~~~~~~
@@ -432,3 +386,4 @@ attribute or method doesn't exist. If set to ``false`` these errors are ignored
432386
and the non-existing values are replaced by ``null``.
433387

434388
.. _`the optimizer extension`: https://twig.symfony.com/doc/2.x/api.html#optimizer-extension
389+
.. _`XSS attacks`: https://en.wikipedia.org/wiki/Cross-site_scripting

0 commit comments

Comments
 (0)
0