This is an old revision of the document!
Table of Contents
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
By default, the output escaping assumes that content is being escaped for HTML output. To bypass escaping, use the raw filter:
{{ article.body|raw }}
You can also disable output escaping inside a {% block %} area or for an entire template. See Output Escaping in the Twig documentation.
Output Escaping in PHP
Use escape()
:
Hello <?php echo $view->escape($name) ?> // HTML escapting by default var myMsg = 'Hello <?php echo $view->escape($name, 'js') ?>'; // Specify context
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>