Skip to content

Update formats.rst #7128

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

Closed
wants to merge 5 commits into from
Closed

Update formats.rst #7128

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ce319c3
Update formats.rst
ibronit Nov 9, 2016
24190e4
Update formats.rst
ibronit Nov 9, 2016
9b29cb6
Update formats.rst
ibronit Nov 9, 2016
e8d7e46
Update formats.rst
ibronit Jan 6, 2017
63ecd78
Update formats.rst
ibronit Jan 6, 2017
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
35 changes: 22 additions & 13 deletions templating/formats.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ most cases you'll use templates to render HTML content, a template can just
as easily generate JavaScript, CSS, XML or any other format you can dream of.

For example, the same "resource" is often rendered in several formats.
To render an article index page in XML, simply include the format in the
To render a contact index page in XML, simply include the format in the
template name:

* *XML template name*: ``article/index.xml.twig``
* *XML template name*: ``contact/index.xml.twig``
* *XML template filename*: ``index.xml.twig``

In reality, this is nothing more than a naming convention and the template
Expand All @@ -22,18 +22,30 @@ In many cases, you may want to allow a single controller to render multiple
different formats based on the "request format". For that reason, a common
pattern is to do the following::

public function indexAction(Request $request)
{
$format = $request->getRequestFormat();
.. configuration-block::

.. code-block:: php-annotations

/**
* @Route("/{_format}", name="contact_list", defaults={"_format": "html"}, requirements={"_format": "html|xml|pdf"})
*
* @param Request $request
*
* @return Response
*/
public function indexAction(Request $request)
{
$format = $request->getRequestFormat();

return $this->render('article/index.'.$format.'.twig');
}
return $this->render('contact/index.'.$format.'.twig');
}


The ``getRequestFormat`` on the ``Request`` object defaults to ``html``,
but can return any other format based on the format requested by the user.
The request format is most often managed by the routing, where a route can
be configured so that ``/contact`` sets the request format to ``html`` while
``/contact.xml`` sets the format to ``xml``. For more information, see the
``/contact/xml`` sets the format to ``xml``. For more information, see the
:ref:`Advanced Example in the Routing chapter <advanced-routing-example>`.

To create links that include the format parameter, include a ``_format``
Expand All @@ -43,17 +55,14 @@ key in the parameter hash:

.. code-block:: html+twig

<a href="{{ path('article_show', {'id': 123, '_format': 'pdf'}) }}">
<a href="{{ path('contact_list', {'_format': 'pdf'}) }}">
PDF Version
</a>

.. code-block:: html+php

<!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
had to use generate(). -->
<a href="<?php echo $view['router']->path('article_show', array(
'id' => 123,
'_format' => 'pdf',
)) ?>">
<a href="<?php echo $view['router']->path('contact_list', ['_format' => 'pdf']) ?>">
PDF Version
</a>