Skip to content

Commit 865e476

Browse files
javiereguiluzjaviereguiluz
committed
Second round of reviews
1 parent 260293e commit 865e476

File tree

2 files changed

+75
-97
lines changed

2 files changed

+75
-97
lines changed

‎routing.rst

Lines changed: 8 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1256,67 +1256,14 @@ Symfony defines some special controllers to render templates and redirect to
12561256
other routes from the route configuration so you don't have to create a
12571257
controller action.
12581258

1259-
Rendering Templates
1260-
~~~~~~~~~~~~~~~~~~~
1261-
1262-
Use the ``TemplateController`` to render the template whose path is defined in
1263-
the ``template`` option:
1264-
1265-
.. configuration-block::
1266-
1267-
.. code-block:: yaml
1268-
1269-
# config/routes.yaml
1270-
about_us:
1271-
path: /site/about-us
1272-
controller: Symfony\Bundle\FrameworkBundle\Controller\TemplateController::templateAction
1273-
defaults:
1274-
template: 'static_pages/about_us.html.twig'
1275-
1276-
# optionally you can define some arguments passed to the template
1277-
site_name: 'ACME'
1278-
theme: 'dark'
1279-
1280-
.. code-block:: xml
1281-
1282-
<!-- config/routes.xml -->
1283-
<?xml version="1.0" encoding="UTF-8" ?>
1284-
<routes xmlns="http://symfony.com/schema/routing"
1285-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1286-
xsi:schemaLocation="http://symfony.com/schema/routing
1287-
https://symfony.com/schema/routing/routing-1.0.xsd">
1259+
Rendering a Template Directly from a Route
1260+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
12881261

1289-
<route id="about_us" path="/site/about-us"
1290-
controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController::templateAction">
1291-
<default key="template">static_pages/about_us.html.twig</default>
1262+
Read the section about :ref:`rendering a template from a route <templates-render-from-route>`
1263+
in the main article about Symfony templates.
12921264

1293-
<!-- optionally you can define some arguments passed to the template -->
1294-
<default key="site_name">ACME</default>
1295-
<default key="theme">dark</default>
1296-
</route>
1297-
</routes>
1298-
1299-
.. code-block:: php
1300-
1301-
// config/routes.php
1302-
use App\Controller\DefaultController;
1303-
use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
1304-
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1305-
1306-
return function (RoutingConfigurator $routes) {
1307-
$routes->add('about_us', '/site/about-us')
1308-
->controller([TemplateController::class, 'templateAction'])
1309-
->defaults([
1310-
'template' => 'static_pages/about_us.html.twig',
1311-
// optionally you can define some arguments passed to the template
1312-
'site_name' => 'ACME',
1313-
'theme' => 'dark',
1314-
])
1315-
;
1316-
};
1317-
1318-
Redirecting to URLs and Routes
1319-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1265+
Redirecting to URLs and Routes Directly from a Route
1266+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
13201267

13211268
Use the ``RedirectController`` to redirect to other routes (``redirectAction``)
13221269
and URLs (``urlRedirectAction``):
@@ -1901,28 +1848,8 @@ the :class:`Symfony\\Component\\Routing\\Generator\\UrlGeneratorInterface` class
19011848
Generating URLs in Templates
19021849
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19031850

1904-
The Twig template language used in :doc:`Symfony templates </templates>`
1905-
provides some functions to generate both relative and absolute URLs:
1906-
1907-
.. code-block:: html+twig
1908-
1909-
{# generates relative URLs #}
1910-
<a href="{{ path('sign_up') }}">Sign up</a>
1911-
<a href="{{ path('user_profile', {username: app.user.username}) }}">
1912-
View your profile
1913-
</a>
1914-
<a href="{{ path('user_profile', {username: app.user.username, _locale: 'es'}) }}">
1915-
Ver mi perfil
1916-
</a>
1917-
1918-
{# generates absolute URLs #}
1919-
<a href="{{ url('sign_up') }}">Sign up</a>
1920-
<a href="{{ url('user_profile', {username: app.user.username}) }}">
1921-
View your profile
1922-
</a>
1923-
<a href="{{ url('user_profile', {username: app.user.username, _locale: 'es'}) }}">
1924-
Ver mi perfil
1925-
</a>
1851+
Read the section about :ref:`creating links between pages <templates-link-to-pages>`
1852+
in the main article about Symfony templates.
19261853

19271854
Generating URLs in JavaScript
19281855
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎templates.rst

Lines changed: 67 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,11 @@ the first time you see Twig, you probably understand most of it:
2929
<body>
3030
<h1>{{ page_title }}</h1>
3131

32-
{# this is the main navigation menu #}
33-
<ul id="navigation">
34-
{% for item in navigation %}
35-
<li><a href="{{ item.href }}">{{ item.caption }}</a></li>
36-
{% endfor %}
37-
</ul>
32+
{% if user.isLoggedIn %}
33+
Hello {{ user.name }}!
34+
{% endif %}
35+
36+
{# ... #}
3837
</body>
3938
</html>
4039

@@ -74,6 +73,45 @@ to display numbers and dates, the template caching, etc. Read the
7473
Creating Templates
7574
------------------
7675

76+
Before explaining in detail how to create and render templates, look at the
77+
following example for a quick overview of the whole process. First, you need to
78+
create a new file in the ``templates/`` directory to store the template contents:
79+
80+
.. code-block:: html+twig
81+
82+
{# templates/user/notifications.html.twig #}
83+
<h1>Hello {{ user_first_name }}!</h1>
84+
<p>You have {{ notifications|length }} new notifications.</p>
85+
86+
Then, create a :doc:`controller </controller>` that renders this template and
87+
passes to it the needed variables::
88+
89+
// src/Controller/UserController.php
90+
namespace App\Controller;
91+
92+
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
93+
94+
class UserController extends AbstractController
95+
{
96+
// ...
97+
98+
public function notifications()
99+
{
100+
// get the user information and notifications somehow
101+
$userFirstName = '...';
102+
$userNotifications = ['...', '...'];
103+
104+
// the template path is the relative file path from `templates/`
105+
return $this->render('user/notifications.html.twig', [
106+
// this array defines the variables passed to the template,
107+
// where the key is the variable name and the value is the variable value
108+
// (Twig recommends using snake_case variable names: 'foo_bar' instead of 'fooBar')
109+
'user_first_name' => $userFirstName,
110+
'notifications' => $userNotifications,
111+
]);
112+
}
113+
}
114+
77115
Template Naming
78116
~~~~~~~~~~~~~~~
79117

@@ -104,8 +142,9 @@ Template Variables
104142
~~~~~~~~~~~~~~~~~~
105143

106144
A common need for templates is to print the values stored in the templates
107-
passed from the controller or service. That's why Twig provides quick access to
108-
all kinds of PHP variables. Consider the following template:
145+
passed from the controller or service. Variables usually store objects and
146+
arrays instead of strings, numbers and boolean values. That's why Twig provides
147+
quick access to complex PHP variables. Consider the following template:
109148

110149
.. code-block:: html+twig
111150

@@ -256,10 +295,13 @@ You can now use the ``asset()`` function:
256295

257296
.. code-block:: html+twig
258297

298+
{# the image lives at "public/images/logo.png" #}
259299
<img src="{{ asset('images/logo.png') }}" alt="Symfony!"/>
260300

301+
{# the CSS file lives at "public/css/blog.css" #}
261302
<link href="{{ asset('css/blog.css') }}" rel="stylesheet"/>
262303

304+
{# the JS file lives at "public/bundles/acme/js/loader.js" #}
263305
<script src="{{ asset('bundles/acme/js/loader.js') }}"></script>
264306

265307
The ``asset()`` function's main purpose is to make your application more portable.
@@ -334,10 +376,8 @@ gives you access to these variables:
334376
A :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface`
335377
object representing the security token.
336378

337-
.. tip::
338-
339-
In addition to the global ``app`` variable injected by Symfony, you can also
340-
:doc:`inject variables automatically to all Twig templates </templating/global_variables>`.
379+
In addition to the global ``app`` variable injected by Symfony, you can also
380+
:doc:`inject variables automatically to all Twig templates </templating/global_variables>`.
341381

342382
.. _templates-rendering:
343383

@@ -412,6 +452,8 @@ Rendering a Template in Emails
412452

413453
Read the docs about the :ref:`mailer and Twig integration <mailer-twig>`.
414454

455+
.. _templates-render-from-route:
456+
415457
Rendering a Template Directly from a Route
416458
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
417459

@@ -434,7 +476,10 @@ definition. Use the special ``TemplateController`` provided by Symfony::
434476
# special options defined by Symfony to set the page cache
435477
maxAge: 86400
436478
sharedAge: 86400
437-
methods: GET
479+
480+
# optionally you can define some arguments passed to the template
481+
site_name: 'ACME'
482+
theme: 'dark'
438483
439484
.. code-block:: xml
440485
@@ -446,14 +491,17 @@ definition. Use the special ``TemplateController`` provided by Symfony::
446491
447492
<route id="acme_privacy"
448493
path="/privacy"
449-
controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController"
450-
methods="GET">
494+
controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController">
451495
<!-- the path of the template to render -->
452496
<default key="template">static/privacy.html.twig</default>
453497
454498
<!-- special options defined by Symfony to set the page cache -->
455499
<default key="maxAge">86400</default>
456500
<default key="sharedAge">86400</default>
501+
502+
<!-- optionally you can define some arguments passed to the template -->
503+
<default key="site_name">ACME</default>
504+
<default key="theme">dark</default>
457505
</route>
458506
</routes>
459507
@@ -466,14 +514,17 @@ definition. Use the special ``TemplateController`` provided by Symfony::
466514
return function (RoutingConfigurator $routes) {
467515
$routes->add('acme_privacy', '/privacy')
468516
->controller(TemplateController::class)
469-
->methods(['GET'])
470517
->defaults([
471518
// the path of the template to render
472519
'template' => 'static/privacy.html.twig',
473520
474521
// special options defined by Symfony to set the page cache
475522
'maxAge' => 86400,
476523
'sharedAge' => 86400,
524+
525+
// optionally you can define some arguments passed to the template
526+
'site_name' => 'ACME',
527+
'theme' => 'dark',
477528
])
478529
;
479530
};

0 commit comments

Comments
 (0)