Skip to content

[2.7] Update Twig docs for asset features #5574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 9, 2016
Merged

[2.7] Update Twig docs for asset features #5574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc18ff1
Updated Twig template to take into account asset() function changes
javiereguiluz Apr 13, 2015
0cd7e6c
Correctly document new twig functions
wouterj Jul 28, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 4 additions & 38 deletions book/templating.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1067,46 +1067,12 @@ assets won't be loaded from cache after being deployed. For example, ``/images/l
look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version`
configuration option.

.. _`book-templating-version-by-asset`:
If you need absolute URLs for assets, use the ``absolute_url()`` Twig function
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it make sense to add a warning that this is not supported? Otherwise, people who use old links might get lost as the anchor wouldn't match anymore.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say yes

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean adding an admonition about this in the docs? I don't like that, it'll put completely unrelated text in the documentation (also, anyone linking to this currently wouldn't read the warning anyways)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Honestly, I cannot remember anymore what I had in mind back then.

as follows:

If you need to set a version for a specific asset, you can set the ``version`` argument
if you are using Twig (or the fourth argument if you are using PHP) to the desired version:
.. code-block:: html+jinja

.. configuration-block::

.. code-block:: html+jinja

<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,
false,
'3.0'
) ?>" alt="Symfony!" />

If you don't give a version or pass ``null``, the default package version
(from :ref:`reference-framework-assets-version`) will be used. If you pass ``false``,
versioned URL will be deactivated for this asset.

If you need absolute URLs for assets, you can use the ``absolute_url`` function
if you are using Twig (or the third argument if you are using PHP) to ``true``:

.. configuration-block::

.. code-block:: html+jinja

<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />

.. code-block:: html+php

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

.. index::
single: Templating; Including stylesheets and JavaScripts
Expand Down
4 changes: 0 additions & 4 deletions reference/configuration/framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1081,10 +1081,6 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
this feature, you **must** manually increment the ``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 `version_format`_
option.

Expand Down
37 changes: 25 additions & 12 deletions reference/twig_reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,8 @@ asset

Returns a public path to ``path``, which takes into account the base path
set for the package and the URL path. More information in
:ref:`book-templating-assets`. For asset versioning, see :ref:`reference-framework-assets-version`.
:ref:`book-templating-assets`. For asset versioning, see
:ref:`reference-framework-assets-version`.

assets_version
~~~~~~~~~~~~~~
Expand Down Expand Up @@ -362,8 +363,8 @@ information in :ref:`book-templating-pages`.
absolute_url
~~~~~~~~~~~~

.. versionadded:: 2.6
The ``absolute_url`` function was introduced in Symfony 2.7
.. versionadded:: 2.7
The ``absolute_url()`` function was introduced in Symfony 2.7.

.. code-block:: jinja

Expand All @@ -372,18 +373,23 @@ absolute_url
``path``
**type**: ``string``

Returns the absolute URL for the given absolute path. This is useful to convert
an existing path:
Returns the absolute URL from the passed relative path. For example, assume
you're on the following page in your app:
``http://example.com/products/hover-board``.

.. code-block:: jinja

{{ absolute_url(asset(path)) }}
{{ absolute_url('/human.txt') }}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we could also add the current URL here:

{# assume the current URL is http://example.com/products/hover-board #}

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doing it twice seems a bit duplicated to me. I've not included it in the PR, but feel free to make this change during merging if you feel it makes things better.

{# http://example.com/human.txt #}

{{ absolute_url('products_icon.png') }}
{# http://example.com/products/products_icon.png #}

relative_path
~~~~~~~~~~~~~

.. versionadded:: 2.6
The ``relative_path`` function was introduced in Symfony 2.7
.. versionadded:: 2.7
The ``relative_path()`` function was introduced in Symfony 2.7.

.. code-block:: jinja

Expand All @@ -392,10 +398,17 @@ relative_path
``path``
**type**: ``string``

Returns a relative path for the given absolute path (based on the current
request path). For instance, if the current path is
``/article/news/welcome.html``, the relative path for ``/article/image.png`` is
``../images.png``.
Returns the relative path from the passed absolute URL. For example, assume
you're on the following page in your app:
``http://example.com/products/hover-board``.

.. code-block:: jinja

{{ relative_path('http://example.com/human.txt') }}
{# ../human.txt #}

{{ relative_path('http://example.com/products/products_icon.png') }}
{# products_icon.png #}

expression
~~~~~~~~~~
Expand Down