10000 Improved the Templating formats article by wouterj · Pull Request #7800 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Improved the Templating formats article #7800

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 3 commits into from
May 12, 2017
Merged

Improved the Templating formats article #7800

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5862c75
Update formats.rst
ibronit Nov 9, 2016
90924db
Used the article example consistently in the example
wouterj Apr 15, 2017
dfe9d11
Mentioned FOSRestBundle's content negotiation
wouterj Apr 15, 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
Prev Previous commit
Next Next commit
Used the article example consistently in the example
  • Loading branch information
@wouterj
wouterj committed Apr 15, 2017
commit 90924db8871ef018a431d02707cb7ca284082cc7
60 changes: 42 additions & 18 deletions templating/formats.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@
How to Work with Different Output Formats in Templates
======================================================

Templates are a generic way to render content in *any* format. And while in
Templates are a generic way to render content in *any* format. While in
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
template name:

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

In reality, this is nothing more than a naming convention and the template
isn't actually rendered differently based on its format.
Expand All @@ -22,38 +22,62 @@ 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 showAction(Request $request, Article $entity)
// ...
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;

class ArticleController extends Controller
{
$format = $request->getRequestFormat();
/**
* @Route("/{slug}")
*/
public function showAction(Request $request, $slug)
{
// retrieve the article based on $slug
$article = ...;

$format = $request->getRequestFormat();

return $this->render('article/index.'.$format.'.twig', [
'entity' => $entity
]);
return $this->render('article/show.'.$format.'.twig', array(
'article' => $article,
));
}
}

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 this
:ref:`Advanced Routing Example <advanced-routing-example>`.
be configured so that ``/about-us`` sets the request format to ``html`` while
``/about-us.xml`` sets the format to ``xml``. This can be achieved by using the
special ``_format`` placeholder in your route definition::

To create links that include the format parameter, include a ``_format``
key in the parameter hash:
/**
* @Route("/{slug}.{_format}", defaults={"_format": "html"})
*/
public function showAction(Request $request, $slug)
{
// ...
}

Now, include the ``_format`` placeholder when generating a route for another
format:

.. configuration-block::

.. code-block:: html+twig

<a href="{{ path('article_show', {'id': 123, '_format': 'pdf'}) }}">
PDF Version
<a href="{{ path('article_show', {'slug': 'about-us', '_format': 'xml'}) }}">
View as XML
</a>

.. code-block:: html+php

<a href="<?php echo $view['router']->generate('article_show', array(
'id' => 123,
'_format' => 'pdf',
'slug' => 'about-us',
'_format' => 'xml',
)) ?>">
PDF Version
View as XML
</a>

.. seealso::

For more information, see this :ref:`Advanced Routing Example <advanced-routing-example>`.
0