Skip to content

Commit d695cad

Browse files
weaverryanweaverryan
committed
Merge branch '2.3'
2 parents 871b340 + 434a98d commit d695cad

File tree

11 files changed

+353
-117
lines changed

11 files changed

+353
-117
lines changed

‎components/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ The Components
2525
security/index
2626
serializer
2727
stopwatch
28-
templating
28+
templating/index
2929
yaml/index
3030

3131
.. include:: /components/map.rst.inc

‎components/map.rst.inc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,9 +109,9 @@
109109
* :doc:`/components/security/authentication`
110110
* :doc:`/components/security/authorization`
111111

112-
* **Templating**
112+
* :doc:`/components/templating/index`
113113

114-
* :doc:`/components/templating`
114+
* :doc:`/components/templating/introduction`
115115

116116
* :doc:`/components/yaml/index`
117117

‎components/templating.rst

Lines changed: 0 additions & 113 deletions
This file was deleted.

‎components/templating/helpers/assetshelper.rst

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
.. index::
2+
single: Templating Helpers; Assets Helper
3+
4+
Assets Helper
5+
=============
6+
7+
The assets helper's main purpose is to make your application more portable by
8+
generating asset paths:
9+
10+
.. code-block:: html+php
11+
12+
<link href="<?php echo $view['assets']->getUrl('css/style.css') ?>" rel="stylesheet">
13+
14+
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">
15+
16+
The assets helper can then be configured to render paths to a CDN or modify
17+
the paths in case your assets live in a sub-directory if your host (e.g. ``http://example.com/app``).
18+
19+
Configure Paths
20+
---------------
21+
22+
By default, the assets helper will prefix all paths with a slash. You can
23+
configure this by passing a base assets path as the first argument of the
24+
constructor::
25+
26+
use Symfony\Component\Templating\Helper\AssetsHelper;
27+
28+
// ...
29+
$templateEngine->set(new AssetsHelper('/foo/bar'));
30+
31+
Now, if you use the helper, everything will be prefixed with ``/foo/bar``:
32+
33+
.. code-block:: html+php
34+
35+
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">
36+
<!-- renders as:
37+
<img src="/foo/bar/images/logo.png">
38+
-->
39+
40+
Absolute Urls
41+
-------------
42+
43+
You can also specify a url to use in the second parameter of the constructor::
44+
45+
// ...
46+
$templateEngine->set(new AssetsHelper(null, 'http://cdn.example.com/'));
47+
48+
Now urls are rendered like ``http://cdn.example.com/images/logo.png``.
49+
50+
Versioning
51+
----------
52+
53+
To avoid using the cached resource after updating the old resource, you can
54+
use versions which you bump every time you release a new project. The version
55+
can be specified in the third argument::
56+
57+
// ...
58+
$templateEngine->set(new AssetsHelper(null, null, '328rad75'));
59+
60+
Now, every url is suffixed with ``?328rad75``. If you want to have a different
61+
format, you can specify the new format in fourth argument. It's a string that
62+
is used in :phpfunction:`sprintf`. The first argument is the path and the
63+
second is the version. For instance, ``%s?v=%s`` will be rendered as
64+
``/images/logo.png?v=328rad75``.
65+
66+
Multiple Packages
67+
-----------------
68+
69+
Asset path generation is handled internally by packages. The component provides
70+
2 packages by default:
71+
72+
* :class:`Symfony\\Component\\Templating\\Asset\\PathPackage`
73+
* :class:`Symfony\\Component\\Templating\\Asset\\UrlPackage`
74+
75+
You can also use multiple packages::
76+
77+
// ...
78+
$templateEngine->set(new AssetsHelper());
79+
80+
$templateEngine->get('assets')->addPackage('images', new PathPackage('/images/'));
81+
$templateEngine->get('assets')->addPackage('scripts', new PathPackage('/scripts/'));
82+
83+
This will setup the assets helper with 3 packages: the default package which
84+
defaults to ``/`` (set by the constructor), the images package which prefixes
85+
it with ``/images/`` and the scripts package which prefixes it with
86+
``/scripts/``.
87+
88+
If you want to set another default package, you can use
89+
:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::setDefaultPackage`.
90+
91+
You can specify which package you want to use in the second argument of
92+
:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::getUrl`:
93+
94+
.. code-block:: php+html
95+
96+
<img src="<?php echo $view['assets']->getUrl('foo.png', 'images') ?>">
97+
<!-- renders as:
98+
<img src="/images/foo.png">
99+
-->
100+
101+
Custom Packages
102+
---------------
103+
104+
You can create your own package by extending
105+
:class:`Symfony\\Component\\Templating\\Package\\Package`.

‎components/templating/helpers/index.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. index::
2+
single: Templating; Templating Helpers
3+
4+
The Templating Helpers
5+
======================
6+
7+
.. toctree::
8+
:hidden:
9+
10+
slotshelper
11+
assetshelper
12+
13+
The Templating Component comes with some useful helpers. These helpers contain
14+
functions to ease some common tasks.
15+
16+
.. include:: map.rst.inc

‎components/templating/helpers/map.rst.inc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
* :doc:`/components/templating/helpers/slotshelper`
2+
* :doc:`/components/templating/helpers/assetshelper`

‎components/templating/helpers/slotshelper.rst

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
.. index::
2+
single: Templating Helpers; Slots Helper
3+
4+
Slots Helper
5+
============
6+
7+
More often than not, templates in a project share common elements, like the
8+
well-known header and footer. Using this helper, the static HTML code can
9+
be placed in a layout file along with "slots", which represent the dynamic
10+
parts that will change on a page-by-page basis. These slots are then filled
11+
in by different children template. In other words, the layout file decorates
12+
the child template.
13+
14+
Displaying Slots
15+
----------------
16+
17+
The slots are accessible by using the slots helper (``$view['slots']``). Use
18+
:method:`Symfony\\Component\\Templating\\Helper\\SlotsHelper::output` to
19+
display the content of the slot on that place:
20+
21+
.. code-block:: html+php
22+
23+
<!-- views/layout.php -->
24+
<!doctype html>
25+
<html>
26+
<head>
27+
<title><?php $view['slots']->output('title', 'Default title') ?></title>
28+
</head>
29+
<body>
30+
<?php $view['slots']->output('_content') ?>
31+
</body>
32+
</html>
33+
34+
The first argument of the method is the name of the slot. The method has an
35+
optional second argument, which is the default value to use if the slot is not
36+
available.
37+
38+
The ``_content`` slot is a special slot set by the ``PhpEngine``. It contains
39+
the content of the subtemplate.
40+
41+
.. caution::
42+
43+
If you're using the standalone component, make sure you registered the
44+
:class:`Symfony\\Component\\Templating\\Helper\\SlotsHelper`::
45+
46+
use Symfony\Component\Templating\Helper\SlotsHelper;
47+
48+
// ...
49+
$templateEngine->set(new SlotsHelper());
50+
51+
Extending Templates
52+
-------------------
53+
54+
The :method:`Symfony\\Component\\Templating\\PhpEngine::extend` method is called in the
55+
sub-template to set its parent template. Then
56+
:method:`$view['slots']->set()
57+
<Symfony\\Component\\Translation\\Helper\\SlotsHelper::set>` can be used to
58+
set the content of a slot. All content which is not explicitly set in a slot
59+
is in the ``_content`` slot.
60+
61+
.. code-block:: html+php
62+
63+
<!-- views/page.php -->
64+
<?php $view->extend('layout.php') ?>
65+
66+
<?php $view['slots']->set('title', $page->title) ?>
67+
68+
<h1>
69+
<?php echo $page->title ?>
70+
</h1>
71+
<p>
72+
<?php echo $page->body ?>
73+
</p>
74+
75+
.. note::
76+
77+
Multiple levels of inheritance is possible: a layout can extend another
78+
layout.
79+
80+
For large slots, there is also an extended syntax:
81+
82+
.. code-block:: html+php
83+
84+
<?php $view['slots']->start('title') ?>
85+
Some large amount of HTML
86+
<?php $view['slots']->stop() ?>

‎components/templating/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Templating
2+
==========
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
helpers/index

0 commit comments

Comments
 (0)