Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit a9648e8

Browse files
weaverryanweaverryan
committedMay 6, 2014
feature #3742 [2.5][Templating] Add documentation about generating versioned URLs (romainneutron)
This PR was merged into the master branch. Discussion ---------- [2.5][Templating] Add documentation about generating versioned URLs | Q | A | ------------- | --- | Doc fix? | no | New docs? | symfony/symfony#10593 | Applies to | 2.5+ Commits ------- f6af251 [Templating] Add documentation about generating versioned URLs
2 parents be6c79d + f6af251 commit a9648e8

File tree

3 files changed

+102
-71
lines changed

3 files changed

+102
-71
lines changed
 

‎book/templating.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1007,6 +1007,25 @@ If you need absolute URLs for assets, you can set the third argument (or the
10071007

10081008
<img src="<?php echo $view['assets']->getUrl('images/logo.png', null, true) ?>" alt="Symfony!" />
10091009

1010+
.. versionadded:: 2.5
1011+
Versioned URLs for assets were introduced in Symfony 2.5.
1012+
1013+
If you need versioned URLs for assets, you can set the fourth argument (or the
1014+
``version`` argument) to the desired version:
1015+
1016+
.. configuration-block::
1017+
1018+
.. code-block:: html+jinja
1019+
1020+
<img src="{{ asset('images/logo.png', version=3.0) }}" alt="Symfony!" />
1021+
1022+
.. code-block:: html+php
1023+
1024+
<img src="<?php echo $view['assets']->getUrl('images/logo.png', null, false, '3.0') ?>" alt="Symfony!" />
1025+
1026+
If you dont give a version or pass ``null``, the default package version will
1027+
be used. If you pass ``false``, versioned URL will be deactivated.
1028+
10101029
.. index::
10111030
single: Templating; Including stylesheets and JavaScripts
10121031
single: Stylesheets; Including stylesheets

‎components/templating/helpers/assetshelper.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,18 @@ is used in :phpfunction:`sprintf`. The first argument is the path and the
8080
second is the version. For instance, ``%s?v=%s`` will be rendered as
8181
``/images/logo.png?v=328rad75``.
8282

83+
.. versionadded:: 2.5
84+
On-demand versioned URLs for assets were introduced in Symfony 2.5.
85+
86+
You can also generate a versioned URL using the fourth argument of the helper:
87+
88+
.. code-block:: html+php
89+
90+
<img src="<?php echo $view['assets']->getUrl('images/logo.png', null, false, '3.0') ?>">
91+
<!-- renders as:
92+
<img src="/images/logo.png?v=3.0">
93+
-->
94+
8395
Multiple Packages
8496
-----------------
8597

‎reference/twig_reference.rst‎

Lines changed: 71 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -20,77 +20,77 @@ Functions
2020
.. versionadded:: 2.4
2121
The ``expression`` function was introduced in Symfony 2.4.
2222

23-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
24-
| Function Syntax | Usage |
25-
+=======================================================+============================================================================================+
26-
| ``render(uri, options = {})`` | This will render the fragment for the given controller or URL |
27-
| ``render(controller('B:C:a', {params}))`` | For more information, see :ref:`templating-embedding-controller`. |
28-
| ``render(path('route', {params}))`` | |
29-
| ``render(url('route', {params}))`` | |
30-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
31-
| ``render_esi(controller('B:C:a', {params}))`` | This will generate an ESI tag when possible or fallback to the ``render`` |
32-
| ``render_esi(url('route', {params}))`` | behavior otherwise. For more information, see :ref:`templating-embedding-controller`. |
33-
| ``render_esi(path('route', {params}))`` | |
34-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
35-
| ``render_hinclude(controller(...))`` | This will generates an Hinclude tag for the given controller or URL. |
36-
| ``render_hinclude(url('route', {params}))`` | For more information, see :ref:`templating-embedding-controller`. |
37-
| ``render_hinclude(path('route', {params}))`` | |
38-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
39-
| ``controller(attributes = {}, query = {})`` | Used along with the ``render`` tag to refer to the controller that you want to render. |
40-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
41-
| ``asset(path, packageName = null, absolute = false)`` | Get the public path of the asset, more information in |
42-
| | ":ref:`book-templating-assets`". |
43-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
44-
| ``asset_version(packageName = null)`` | Get the current version of the package, more information in |
45-
| | ":ref:`book-templating-assets`". |
46-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
47-
| ``form(view, variables = {})`` | This will render the HTML of a complete form, more information in |
48-
| | in :ref:`the Twig Form reference<reference-forms-twig-form>`. |
49-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
50-
| ``form_start(view, variables = {})`` | This will render the HTML start tag of a form, more information in |
51-
| | in :ref:`the Twig Form reference<reference-forms-twig-start>`. |
52-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
53-
| ``form_end(view, variables = {})`` | This will render the HTML end tag of a form together with all fields that |
54-
| | have not been rendered yet, more information |
55-
| | in :ref:`the Twig Form reference<reference-forms-twig-end>`. |
56-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
57-
| ``form_enctype(view)`` | This will render the required ``enctype="multipart/form-data"`` attribute |
58-
| | if the form contains at least one file upload field, more information in |
59-
| | in :ref:`the Twig Form reference <reference-forms-twig-enctype>`. |
60-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
61-
| ``form_widget(view, variables = {})`` | This will render a complete form or a specific HTML widget of a field, |
62-
| | more information in :ref:`the Twig Form reference <reference-forms-twig-widget>`. |
63-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
64-
| ``form_errors(view)`` | This will render any errors for the given field or the "global" errors, |
65-
| | more information in :ref:`the Twig Form reference <reference-forms-twig-errors>`. |
66-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
67-
| ``form_label(view, label = null, variables = {})`` | This will render the label for the given field, more information in |
68-
| | :ref:`the Twig Form reference <reference-forms-twig-label>`. |
69-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
70-
| ``form_row(view, variables = {})`` | This will render the row (the field's label, errors and widget) of the given |
71-
| | field, more information in :ref:`the Twig Form reference <reference-forms-twig-row>`. |
72-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
73-
| ``form_rest(view, variables = {})`` | This will render all fields that have not yet been rendered, more |
74-
| | information in :ref:`the Twig Form reference <reference-forms-twig-rest>`. |
75-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
76-
| ``csrf_token(intention)`` | This will render a CSRF token. Use this function if you want CSRF protection without |
77-
| | creating a form |
78-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
79-
| ``is_granted(role, object = null, field = null)`` | This will return ``true`` if the current user has the required role, more |
80-
| | information in ":ref:`book-security-template`" |
81-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
82-
| ``logout_path(key)`` | This will generate the relative logout URL for the given firewall |
83-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
84-
| ``logout_url(key)`` | Equal to ``logout_path(...)`` but this will generate an absolute URL |
85-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
86-
| ``path(name, parameters = {})`` | Get a relative URL for the given route, more information in |
87-
| | ":ref:`book-templating-pages`". |
88-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
89-
| ``url(name, parameters = {})`` | Equal to ``path(...)`` but it generates an absolute URL |
90-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
91-
| ``expression(expression)`` | Creates an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` in Twig. See |
92-
| | ":ref:`Template Expressions <book-security-template-expression>`". |
93-
+-------------------------------------------------------+--------------------------------------------------------------------------------------------+
23+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
24+
| Function Syntax | Usage |
25+
+=======================================================================+============================================================================================+
26+
| ``render(uri, options = {})`` | This will render the fragment for the given controller or URL |
27+
| ``render(controller('B:C:a', {params}))`` | For more information, see :ref:`templating-embedding-controller`. |
28+
| ``render(path('route', {params}))`` | |
29+
| ``render(url('route', {params}))`` | |
30+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
31+
| ``render_esi(controller('B:C:a', {params}))`` | This will generate an ESI tag when possible or fallback to the ``render`` |
32+
| ``render_esi(url('route', {params}))`` | behavior otherwise. For more information, see :ref:`templating-embedding-controller`. |
33+
| ``render_esi(path('route', {params}))`` | |
34+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
35+
| ``render_hinclude(controller(...))`` | This will generates an Hinclude tag for the given controller or URL. |
36+
| ``render_hinclude(url('route', {params}))`` | For more information, see :ref:`templating-embedding-controller`. |
37+
| ``render_hinclude(path('route', {params}))`` | |
38+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
39+
| ``controller(attributes = {}, query = {})`` | Used along with the ``render`` tag to refer to the controller that you want to render. |
40+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
41+
| ``asset(path, packageName = null, absolute = false, version = null)`` | Get the public path of the asset, more information in |
42+
| | ":ref:`book-templating-assets`". |
43+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
44+
| ``asset_version(packageName = null)`` | Get the current version of the package, more information in |
45+
| | ":ref:`book-templating-assets`". |
46+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
47+
| ``form(view, variables = {})`` | This will render the HTML of a complete form, more information in |
48+
| | in :ref:`the Twig Form reference<reference-forms-twig-form>`. |
49+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
50+
| ``form_start(view, variables = {})`` | This will render the HTML start tag of a form, more information in |
51+
| | in :ref:`the Twig Form reference<reference-forms-twig-start>`. |
52+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
53+
| ``form_end(view, variables = {})`` | This will render the HTML end tag of a form together with all fields that |
54+
| | have not been rendered yet, more information |
55+
| | in :ref:`the Twig Form reference<reference-forms-twig-end>`. |
56+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
57+
| ``form_enctype(view)`` | This will render the required ``enctype="multipart/form-data"`` attribute |
58+
| | if the form contains at least one file upload field, more information in |
59+
| | in :ref:`the Twig Form reference <reference-forms-twig-enctype>`. |
60+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
61+
| ``form_widget(view, variables = {})`` | This will render a complete form or a specific HTML widget of a field, |
62+
| | more information in :ref:`the Twig Form reference <reference-forms-twig-widget>`. |
63+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
64+
| ``form_errors(view)`` | This will render any errors for the given field or the "global" errors, |
65+
| | more information in :ref:`the Twig Form reference <reference-forms-twig-errors>`. |
66+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
67+
| ``form_label(view, label = null, variables = {})`` | This will render the label for the given field, more information in |
68+
| | :ref:`the Twig Form reference <reference-forms-twig-label>`. |
69+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
70+
| ``form_row(view, variables = {})`` | This will render the row (the field's label, errors and widget) of the given |
71+
| | field, more information in :ref:`the Twig Form reference <reference-forms-twig-row>`. |
72+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
73+
| ``form_rest(view, variables = {})`` | This will render all fields that have not yet been rendered, more |
74+
| | information in :ref:`the Twig Form reference <reference-forms-twig-rest>`. |
75+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
76+
| ``csrf_token(intention)`` | This will render a CSRF token. Use this function if you want CSRF protection without |
77+
| | creating a form |
78+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
79+
| ``is_granted(role, object = null, field = null)`` | This will return ``true`` if the current user has the required role, more |
80+
| | information in ":ref:`book-security-template`" |
81+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
82+
| ``logout_path(key)`` | This will generate the relative logout URL for the given firewall |
83+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
84+
| ``logout_url(key)`` | Equal to ``logout_path(...)`` but this will generate an absolute URL |
85+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
86+
| ``path(name, parameters = {})`` | Get a relative URL for the given route, more information in |
87+
| | ":ref:`book-templating-pages`". |
88+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
89+
| ``url(name, parameters = {})`` | Equal to ``path(...)`` but it generates an absolute URL |
90+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
91+
| ``expression(expression)`` | Creates an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` in Twig. See |
92+
| | ":ref:`Template Expressions <book-security-template-expression>`". |
93+
+-----------------------------------------------------------------------+--------------------------------------------------------------------------------------------+
9494

9595
Filters
9696
-------

0 commit comments

Comments
 (0)
Please sign in to comment.