Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 15b2141

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

File tree

Expand file treeCollapse file tree

11 files changed

+346
-117
lines changed
Filter options
Expand file treeCollapse file tree

11 files changed

+346
-117
lines changed

‎components/index.rst

Copy file name to clipboardExpand all lines: components/index.rst
+1-1Lines 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

Copy file name to clipboardExpand all lines: components/map.rst.inc
+2-2Lines 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

Copy file name to clipboardExpand all lines: components/templating.rst
-113Lines changed: 0 additions & 113 deletions
This file was deleted.

‎components/templating/helpers/assetshelper.rst

Copy file name to clipboard
+102Lines 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

Copy file name to clipboard
+16Lines 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

Copy file name to clipboard
+2Lines 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

Copy file name to clipboard
+84Lines 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

Copy file name to clipboard
+8Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.