Skip to content

Commit 15b2141

Browse files
weaverryanweaverryan
committed
Merge pull request #2735 from WouterJ/issue_955
[WIP] Rewrote Templating Docs
2 parents 5acc483 + 7a46d30 commit 15b2141

File tree

11 files changed

+346
-117
lines changed

11 files changed

+346
-117
lines changed

‎components/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ The Components
2424
security/index
2525
serializer
2626
stopwatch
27-
templating
27+
templating/index
2828
yaml/index
2929

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

‎components/map.rst.inc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,9 @@
102102
* :doc:`/components/security/authentication`
103103
* :doc:`/components/security/authorization`
104104

105-
* **Templating**
105+
* :doc:`/components/templating/index`
106106

107-
* :doc:`/components/templating`
107+
* :doc:`/components/templating/introduction`
108108

109109
* :doc:`/components/yaml/index`
110110

‎components/templating.rst

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

‎components/templating/helpers/assetshelper.rst

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
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 assets' 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+
Configure Paths
17+
---------------
18+
19+
By default, the assets helper will prefix all paths with a slash. You can
20+
extend this by configuring a basepath in the first argument of the
21+
constructor::
22+
23+
use Symfony\Component\Templating\Helper\AssetsHelper;
24+
25+
// ...
26+
$templateEngine->set(new AssetsHelper('/foo/bar'));
27+
28+
Now, if you use the helper everything will be prefixed with ``/foo/bar``:
29+
30+
.. code-block:: html+php
31+
32+
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">
33+
<!-- renders as:
34+
<img src="/foo/bar/images/logo.png">
35+
-->
36+
37+
Absolute Urls
38+
-------------
39+
40+
You can also specify a url to use in the second parameter of the constructor::
41+
42+
// ...
43+
$templateEngine->set(new AssetsHelper(null, 'http://cdn.example.com/'));
44+
45+
Now urls are rendered like ``http://cdn.example.com/images/logo.png``.
46+
47+
Versioning
48+
----------
49+
50+
To avoid using the cached resource after updating the old resource, you can
51+
use versions which you bump every time you release a new project. The version
52+
can be specified in the third argument::
53+
54+
// ...
55+
$templateEngine->set(new AssetsHelper(null, null, '328rad75'));
56+
57+
Now, every url is suffixed with ``?328rad75``. If you want to have a different
58+
format, you can specify the new format in fourth argument. It's a string that
59+
is used in :phpfunction:`sprintf`. The first argument is the path and the
60+
second is the version. For instance, ``%s?v=%s`` will be rendered as
61+
``/images/logo.png?v=328rad75``.
62+
63+
Multiple Packages
64+
-----------------
65+
66+
Paths are internally handled by packages. The component provides 2 packages by
67+
default:
68+
69+
* :class:`Symfony\\Component\\Templating\\Asset\\PathPackage`
70+
* :class:`Symfony\\Component\\Templating\\Asset\\UrlPackage`
71+
72+
You can also have multiple packages::
73+
74+
// ...
75+
$templateEngine->set(new AssetsHelper());
76+
77+
$templateEngine->get('assets')->addPackage('images', new PathPackage('/images/'));
78+
$templateEngine->get('assets')->addPackage('scripts', new PathPackage('/scripts/'));
79+
80+
This will setup the assets helper with 3 packages: the default package which
81+
defaults to ``/`` (set by the constructor), the images package which prefixes
82+
it with ``/images/`` and the scripts package which prefixes it with
83+
``/scripts/``.
84+
85+
If you want to set another default package, you can use
86+
:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::setDefaultPackage`.
87+
88+
You can specify which package you want to use in the second argument of
89+
:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::getUrl`:
90+
91+
.. code-block:: php+html
92+
93+
<img src="<?php echo $view['assets']->getUrl('foo.png', 'images') ?>">
94+
<!-- renders as:
95+
<img src="/images/foo.png">
96+
-->
97+
98+
Custom Packages
99+
---------------
100+
101+
You can create your own package by extending
102+
: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: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
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. The static HTML code can be placed in a layout file
9+
and the dynamic sections are replaced by slots, which are filled by the child
10+
template; the layout file decorates the child template.
11+
12+
Displaying Slots
13+
~~~~~~~~~~~~~~~~
14+
15+
The slots are accessible by using the slots helper (``$view['slots']``). Use
16+
:method:`Symfony\\Component\\Templating\\Helper\\SlotsHelper::output` to
17+
display the content of the slot on that place:
18+
19+
.. code-block:: html+php
20+
21+
<!-- views/layout.php -->
22+
<!doctype html>
23+
<html>
24+
<head>
25+
<title><?php $view['slots']->output('title', 'Default title') ?></title>
26+
</head>
27+
<body>
28+
<?php $view['slots']->output('_content') ?>
29+
</body>
30+
</html>
31+
32+
The first argument of the method is the name of the slot. The method has an
33+
optional second argument, which is the default value to use if the slot is not
34+
available.
35+
36+
The ``_content`` slot is a special slot set by the ``PhpEngine``. It contains
37+
the content of the subtemplate.
38+
39+
.. caution::
40+
41+
If you're using the standalone component, make sure you registered the
42+
:class:`Symfony\\Component\\Templating\\Helper\\SlotsHelper`::
43+
44+
use Symfony\Component\Templating\Helper\SlotsHelper;
45+
46+
// ...
47+
$templateEngine->set(new SlotsHelper());
48+
49+
Extending Templates
50+
~~~~~~~~~~~~~~~~~~~
51+
52+
The :method:`Symfony\\Component\\Templating\\PhpEngine::extend` method is called in the
53+
sub-template to set its parent template. Then
54+
:method:`$view['slots']->set()
55+
<Symfony\\Component\\Translation\\Helper\\SlotsHelper::set>` can be used to
56+
set the content of a slot. All content which is not explicitly set in a slot
57+
is in the ``_content`` slot.
58+
59+
.. code-block:: html+php
60+
61+
<!-- views/page.php -->
62+
<?php $view->extend('layout.php') ?>
63+
64+
<?php $view['slots']->set('title', $page->title) ?>
65+
66+
<h1>
67+
<?php echo $page->title ?>
68+
</h1>
69+
<p>
70+
<?php echo $page->body ?>
71+
</p>
72+
73+
.. note::
74+
75+
Multiple levels of inheritance is possible: a layout can extend an other
76+
layout.
77+
78+
For large slots, there is also an extended syntax:
79+
80+
.. code-block:: html+php
81+
82+
<?php $view['slots']->start('title') ?>
83+
Some large amount of HTML
84+
<?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)