This is an old revision of the document!

Creating and Using Templates

TL;DR

Templates typically live in app/Resources/views/.
Third-party bundle templates live in path/to/bundle/Resources/views/. (Command line generator puts them here too it seems; also seems not a best practice.)

{# == 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!" />

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

    {% for article in articles %}
        {{ include('article/article_details.html.twig', { 'article': article }) }}
    {% endfor %}

Embedding Controllers

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)
        );
    }
}

with a template

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 %}

and the embed using the controller() call:

app/Resources/views/base.html.twig

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

Asynchronous Content with hinclude.js

?

Linking to Pages

{# 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>

Linking to Assets

Use the asset() function:

<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!" />

Including Stylesheets and JavaScripts in Twig

Consider using Assetic.

With Twig, assuming you have a parent:

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

in a child you can add to the assets defined in the parent:

{% extends 'base.html.twig' %}
{% block stylesheets %}
    {{ parent() }}
    <link href="{{ asset('css/contact.css') }}" rel="stylesheet" />
{% endblock %}
{# ... #}

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”.).

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

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

TODO

Overriding Bundle Templates

TODO

Overriding Core Templates

TODO

Three-level Inheritance

TODO

Output Escaping

Output escaping is on by default in Twig, so you're protected. In PHP, output escaping is not automatic, meaning you'll need to manually escape where necessary.

Output Escaping in Twig

TODO

Output Escaping in PHP

TODO

Debugging

dump() is your friend.

In PHP:

src/AppBundle/Controller/ArticleController.php

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

In Twig:

app/Resources/views/article/recent_list.html.twig

{{ dump(articles) }}
{% for article in articles %}
    <a href="/article/{{ article.slug }}">
        {{ article.title }}
    </a>
{% endfor %}

To dump() in Twig, its 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:

# By filename:
$ php app/console lint:twig path/to/your_tempalte.html.twig
 
# By directory:
$ php app/console lint:twig app/Resources/views

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:

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

(See the Advanced Example in Routing.)

Create format links thus:

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

Mithat Konar (the wiki)

Table of Contents

Creating and Using Templates

TL;DR

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

Embedding Controllers

Asynchronous Content with hinclude.js

Linking to Pages

Linking to Assets

Including Stylesheets and JavaScripts in Twig

Global Template Variables

Configuring and Using the templating Service

Overriding Bundle Templates

Overriding Core Templates

Three-level Inheritance

Output Escaping

Output Escaping in Twig

Output Escaping in PHP

Debugging

Syntax Checking

Template Formats