minor #3837 More asset version details (weaverryan)

weaverryan · weaverryan · commit 00f60a8c622d · 2014-05-12T10:26:44.000-05:00
This PR was merged into the master branch. Discussion ---------- More asset version details | Q | A | ------------- | --- | Doc fix? | no | New docs? | no, but follows after #3742 | Applies to | 2.5+ Hi guys! This adds some further tweaks to the new feature and docs from #3742: * moved the absolute asset URL generation part below the new asset versioning feature in the `book/templating` page so that we talk about the "global asset versioning" (i.e. the config option in config.yml) and this new feature right next to each other. * Added some additional details to make it clear that there is a "global" asset version, and then the ability to override on an asset by asset basis. I think it's all small details, but @romainneutron if you have a quick chance to look this over, that would be awesome too. Thanks! Commits ------- 4eafdbd [#3837] Fixes thanks to stof and WouterJ 560e010 Adding more details to be clear that you can set asset version globally or locally on an asset
diff --git a/book/templating.rst b/book/templating.rst
@@ -991,40 +991,43 @@ assets won't be cached when deployed. For example, ``/images/logo.png`` might
 look like ``/images/logo.png?v2``. For more information, see the :ref:`ref-framework-assets-version`
 configuration option.
 
+.. _`book-templating-version-by-asset`:
+
 .. versionadded:: 2.5
-    Absolute URLs for assets were introduced in Symfony 2.5.
+    Setting versioned URLs on an asset-by-asset basis was introduced in Symfony 2.5.
 
-If you need absolute URLs for assets, you can set the third argument (or the
-``absolute`` argument) to ``true``:
+If you need to set a version for a specific asset, you can set the fourth
+argument (or the ``version`` argument) to the desired version:
 
 .. configuration-block::
 
     .. code-block:: html+jinja
 
-        <img src="{{ asset('images/logo.png', absolute=true) }}" alt="Symfony!" />
+        <img src="{{ asset('images/logo.png', version='3.0') }}" alt="Symfony!" />
 
     .. code-block:: html+php
 
-        <img src="<?php echo $view['assets']->getUrl('images/logo.png', null, true) ?>" alt="Symfony!" />
+        <img src="<?php echo $view['assets']->getUrl('images/logo.png', null, false, '3.0') ?>" alt="Symfony!" />
+
+If you dont give a version or pass ``null``, the default package version
+(from :ref:`ref-framework-assets-version`) will be used. If you pass ``false``,
+versioned URL will be deactivated for this asset.
 
 .. versionadded:: 2.5
-    Versioned URLs for assets were introduced in Symfony 2.5.
+    Absolute URLs for assets were introduced in Symfony 2.5.
 
-If you need versioned URLs for assets, you can set the fourth argument (or the
-``version`` argument) to the desired version:
+If you need absolute URLs for assets, you can set the third argument (or the
+``absolute`` argument) to ``true``:
 
 .. configuration-block::
 
     .. code-block:: html+jinja
 
-        <img src="{{ asset('images/logo.png', version=3.0) }}" alt="Symfony!" />
+        <img src="{{ asset('images/logo.png', absolute=true) }}" alt="Symfony!" />
 
     .. code-block:: html+php
 
-        <img src="<?php echo $view['assets']->getUrl('images/logo.png', null, false, '3.0') ?>" alt="Symfony!" />
-
-If you dont give a version or pass ``null``, the default package version will
-be used. If you pass ``false``, versioned URL will be deactivated.
+        <img src="<?php echo $view['assets']->getUrl('images/logo.png', null, true) ?>" alt="Symfony!" />
 
 .. index::
    single: Templating; Including stylesheets and JavaScripts
diff --git a/components/templating/helpers/assetshelper.rst b/components/templating/helpers/assetshelper.rst
@@ -83,7 +83,8 @@ second is the version. For instance, ``%s?v=%s`` will be rendered as
 .. versionadded:: 2.5
     On-demand versioned URLs for assets were introduced in Symfony 2.5.
 
-You can also generate a versioned URL using the fourth argument of the helper:
+You can also generate a versioned URL on an asset-by-asset basis using the
+fourth argument of the helper:
 
 .. code-block:: html+php
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -392,6 +392,10 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
 this feature, you **must** manually increment the ``assets_version`` value
 before each deployment so that the query parameters change.
 
+It's also possible to set the version value on an asset-by-asset basis (instead
+of using the global version - e.g. ``v2`` - set here). See
+:ref:`Versioning by Asset <book-templating-version-by-asset>` for details.
+
 You can also control how the query string works via the `assets_version_format`_
 option.
 
