Mithat Konar (the wiki)

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Creating and Using Templates ======

===== TL;DR =====
  * Templates typically live in ''app/Resources/views/''.
  * Third-party bundle templates live in ''path/to/bundle/Resources/views/''. (The command line generator puts them here too it seems, which I believe is no longer a best practice.)

<code twig>
{# == basics == #}
{# comment #}
{{ varname }}
{% doSomething %}
{{ varname|filtername }}

{# == inheritance == #}
{# a block defined in the parent: #}
{% block blockname %}
    block content
{% endblock %}

{# can be overridden in child template: #}
{% extends 'parent.html.twig' %}
{% block blockname %}
    new content
    {# get content of parent's block #}
    {{ parent() }}
{% endblock %}

{# create links using path() or url() and route name #} 
<a href="{{ path('route_name', {'varname': value}) }}">Relative link</a>
<a href="{{ url('route_name', {'varname': value}) }}">Absolute link</a>

{# use asset() to get assets #}
<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
<img src="{{ asset('images/logo.png', absolute=true) }}" alt="Symfony!" />
</code>

===== Templates =====
==== Twig Template Caching ====

===== Template Inheritance and Layouts =====

===== Template Naming and Locations =====
==== Referencing Templates in a Bundle ====
==== Template Suffix ====

===== Tags and Helpers =====
==== Including other Templates ====
<code twig>
{% for article in articles %}
    {{ include('article/article_details.html.twig', { 'article': article }) }}
{% endfor %}
</code>

==== Embedding Controllers ====
<file php src/AppBundle/Controller/ArticleController.php>
namespace AppBundle\Controller;

class ArticleController extends Controller
{
    public function recentArticlesAction($max = 3)
    {
        // get the "$max" most recent articles
        $articles = ...;

        return $this->render(
            'article/recent_list.html.twig',
            array('articles' => $articles)
        );
    }
}
</file>
with a template
<file twig app/Resources/views/article/recent_list.html.twig>
{% for article in articles %}
    <a href="/article/{{ article.slug }}">
        {{ article.title }}
    </a>
    {# hardcoded URL above is not a best practice. #}
{% endfor %}
</file>
and the embed using the ''controller()'' call:
<file twig app/Resources/views/base.html.twig>

{# ... #}
<div id="sidebar">
    {{ render(controller(
        'AppBundle:Article:recentArticles',
        { 'max': 3 }
    )) }}
</div>
</file>

==== Asynchronous Content with hinclude.js ====
?

==== Linking to Pages ====
<code twig>
{# relative links with path(): #}
<a href="{{ path('route_name') }}">Home</a>
<a href="{{ path('route_name', {'varname': value}) }}">Dynamic link</a>

{# absolute links with url(): #}
<a href="{{ url('route_name') }}">Home</a>
<a href="{{ url('route_name', {'varname': value}) }}">Dynamic link</a>
</code>

==== Linking to Assets ====
Use the ''asset()'' function:

<code twig>
<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
<link href="{{ asset('css/blog.css') }}" rel="stylesheet" />
<img src="{{ asset('images/logo.png', version='3.0') }}" alt="Symfony!" />
<img src="{{ asset('images/logo.png', absolute=true) }}" alt="Symfony!" />
</code>

===== Including Stylesheets and JavaScripts in Twig =====
Consider using [[http://symfony.com/doc/current/cookbook/assetic/asset_management.html|Assetic]].

With Twig, assuming you have the parent:

<code twig>
<html>
    <head>
        {# ... #}
        {% block stylesheets %}
            <link href="{{ asset('css/main.css') }}" rel="stylesheet" />
        {% endblock %}
        {# ... #}
</code>

in its child you can add to the assets defined in the parent:
<code twig>
{% extends 'base.html.twig' %}
{% block stylesheets %}
    {{ parent() }}
    <link href="{{ asset('css/contact.css') }}" rel="stylesheet" />
{% endblock %}
{# ... #}
</code>

You can also include assets located in your bundles' ''Resources/public'' folder. You will need to run ''php app/console assets:install target [--symlink]'', which moves (or symlinks) files into the correct location (target is by default "web".).

<code twig><link href="{{ asset('bundles/acmedemo/css/contact.css') }}" rel="stylesheet" /></code>

===== Global Template Variables =====
  * ''app.user'': The current user object.
  * ''app.request'': The request object.
  * ''app.session'': The session object.
  * ''app.environment'': The current environment (dev, prod, etc).
  * ''app.debug'': True if in debug mode. False otherwise. 

===== Configuring and Using the templating Service =====
<code php>
return $this->render('article/index.html.twig');
</code>

is equivalent to:

<code php>
use Symfony\Component\HttpFoundation\Response;

$engine = $this->container->get('templating');
$content = $engine->render('article/index.html.twig');

return $response = new Response($content);
</code>

It's preconfigured out of the box. Further config is in:

<file yaml app/config/config.yml>
framework:
    # ...
    templating: { engines: ['twig'] }
</file>
===== Overriding Bundle Templates =====
[[http://symfony.com/doc/current/book/templating.html#overriding-bundle-templates|The source]].

==== Overriding Core Templates ====
[[http://symfony.com/doc/current/book/templating.html#overriding-core-templates|The source]].

===== Three-level Inheritance =====
The three-template model is a best-practice method used by vendor bundles so that the base template for a bundle can be easily overridden to properly extend your application's base layout.

  - Create an ''app/Resources/views/base.html.twig'' file that contains the main layout for your application. Internally, this template is called ''base.html.twig''.
  - Create a template for each "section" of your site. <file php app/Resources/views/blog/layout.html.twig>{% extends 'base.html.twig' %}
{% block body %}
    <h1>Blog Application</h1>
    {% block content %}{% endblock %}
{% endblock %}</file>
  - Create individual templates for each page and make each extend the appropriate section template.<file php app/Resources/views/blog/index.html.twig>{% extends 'blog/layout.html.twig' %}
{% block content %}
    {% for entry in blog_entries %}
        <h2>{{ entry.title }}</h2>
        <p>{{ entry.body }}</p>
    {% endfor %}
{% endblock %}</file>

===== Output Escaping =====
==== Output Escaping in Twig ====
Output escaping is on by default in Twig, so you're protected. By default, the output escaping assumes that content is being escaped for HTML output. To bypass escaping, use the raw filter:

<code twig>{{ article.body|raw }}</code>

You can also disable output escaping inside a ''{% block %}'' area or for an entire template. See [[http://twig.sensiolabs.org/doc/api.html#escaper-extension|Output Escaping]] in the Twig documentation.
==== Output Escaping in PHP ====
In PHP, output escaping is not automatic, meaning you'll need to manually ''escape()'' where necessary:

<code php>
Hello <?php echo $view->escape($name) ?>  // HTML escapting by default
var myMsg = 'Hello <?php echo $view->escape($name, 'js') ?>'; // Specify context
</code>

===== Debugging =====
''dump()'' is your friend.

In PHP:

<file php src/AppBundle/Controller/ArticleController.php>
namespace AppBundle\Controller;
class ArticleController extends Controller
{
    public function recentListAction()
    {
        $articles = ...;
        dump($articles);
        // ...
    }
}
</file>

In Twig:

<file twig app/Resources/views/article/recent_list.html.twig>
{{ dump(articles) }}
{% for article in articles %}
    <a href="/article/{{ article.slug }}">
        {{ article.title }}
    </a>
{% endfor %}
</file>

To ''dump()'' in Twig, Twig's ''debug'' setting (in ''config.yml'') must be ''true'' (which is the case for ''dev'' but not ''prod'').

===== Syntax Checking =====
Check for syntax errors in Twig templates using the ''lint:twig'' console command:
<code bash>
# By filename:
$ php app/console lint:twig path/to/your_tempalte.html.twig

# By directory:
$ php app/console lint:twig app/Resources/views
</code>

===== Template Formats =====
Twig can render *any** format.
  * e.g.: XML ''article/index.xml.twig''.

The ''name.format.twig'' naming format is a convention. Using the convention you can do:

<code php>
public function indexAction(Request $request)
{
    $format = $request->getRequestFormat();
    return $this->render('article/index.'.$format.'.twig');
}
</code>

(See the [[http://symfony.com/doc/current/book/routing.html#advanced-routing-example|Advanced Example]] in Routing.)

Create format links thus:
<code twig>
<a href="{{ path('article_show', {'id': 123, '_format': 'pdf'}) }}">
    PDF Version
</a>
</code>