-
{% for user in users %}
- {{ user.username }} {% else %}
- No users found {% endfor %}
{% block body %}{% endblock %}
.. code-block:: php
output('body') ?>
.. note::
Apesar da discussão sobre herança de template ser em termos do Twig,
a filosofia é a mesma entre templates Twig e PHP.
Este template define o esqueleto do documento base HTML de um página simples
de duas colunas. Neste exemplo, três áreas ``{% block %}`` são definidas (``title``,
``sidebar`` e ``body``). Cada bloco pode ser sobreposto por um template filho
ou largado com sua implementação padrão. Esse template poderia também ser processado
diretamente. Neste caso os blocos ``title``, ``sidebar`` e ``body`` blocks deveriam
simplesmente reter os valores padrão neste template.
Um template filho poderia ser como este:
.. configuration-block::
.. code-block:: html+jinja
{# src/Acme/BlogBundle/Resources/views/Blog/index.html.twig #}
{% extends '::base.html.twig' %}
{% block title %}My cool blog posts{% endblock %}
{% block body %}
{% for entry in blog_entries %}
{{ entry.title }}
{{ entry.body }}
{% endfor %} {% endblock %} .. code-block:: php extend('::base.html.php') ?> set('title', 'My cool blog posts') ?> start('body') ?>getTitle() ?>
getBody() ?>
stop() ?> .. note:: O template pai é idenficado por uma sintaxe especial de string (``::base.html.twig``) que indica que o template reside no diretório ``app/Resources/views`` do projeto. Essa convenção de nomeamento é explicada inteiramente em :ref:`template-naming-locations`. A chave para herança template é a tag ``{% extends %}``. Ela avisa o engine de template para primeiro avaliar o template base, que configura o layout e define vários blocos. O template filho é então processado, ao ponto que os blocos ``title`` e ``body`` do template pai sejam substituídos por aqueles do filho. Dependendo do valor de ``blog_entries``, a saída poderia parecer com isso::My first post
The body of the first post.
Another post
The body of the second post.
Table of Contents
... {{ parent() }} {% endblock %} .. index:: single: Templating; Convenções de Nomeação single: Templating; Localização de Arquivos .. _template-naming-locations: Nomeação de Template e Localizações ----------------------------- Por padrão, templates podem residir em duas localizações diferentes: * ``app/Resources/views/``: O diretório de aplicação de ``views`` pode abrigar templates bases para toda a aplicação(ex: os layout de sua aplicação) assim como os tempates que sobrepõem templates de pacote (veja :ref:`overriding-bundle-templates`); application-wide base templates (i.e. your application's layouts) as well as templates that override bundle templates (see :ref:`overriding-bundle-templates`); * ``path/to/bundle/Resources/views/``: Cada pacote abriga as templates dele no diretório ``Resources/views`` (e sub-diretórios). A maioria dos templates irá residir dentro de um pacote. Symfony2 usa a sintaxe de string **bundle**:**controller**:**template** para templates. Isso permite vários tipos diferente de template, cada um residindo em uma localização especifica: * ``AcmeBlogBundle:Blog:index.html.twig``: Esta sintaxe é usada para especificar um template para uma página específica. As três partes do string, cada uma separada por dois pontos, (``:``), signitca o seguinte: * ``AcmeBlogBundle``: (*bundle*) o template reside entro de ``AcmeBlogBundle`` (e.g. ``src/Acme/BlogBundle``); * ``Blog``: (*controller*) indica que o template reside dentro do sub-diretório ``Blog`` de ``Resources/views``; * ``index.html.twig``: (*template*) o verdadeiro nome do arquivo é ``index.html.twig``. Assumindo que o ``AcmeBlogBundle`` reside em ``src/Acme/BlogBundle``, o atalho final para o layout seria ``src/Acme/BlogBundle/Resources/views/Blog/index.html.twig``. * ``AcmeBlogBundle::layout.html.twig``: Essa sintaxe refere ao template base que é específica para ``AcmeBlogBundle``. Since the middle, "controller", portion is missing (e.g. ``Blog``), the template lives at ``Resources/views/layout.html.twig`` inside ``AcmeBlogBundle``. * ``::base.html.twig``: Esta sintaxe refere a uma template base para toda a aplicação ou layout. Perceba que a string começa com dois sinais de dois pontos (``::``), significando que ambas as partes *bundle* *controller* estão faltando. Isto significa que o template não é localizado em qualquer pacote, mas sim na raiz do diretório ``app/Resources/views/``. Na seção :ref:`overriding-bundle-templates`, você irá descobrir como cada template reside dentro do ``AcmeBlogBundle``, por exemplo, pode ser sobreposto ao colocar um template de mesmo nome no diretório ``app/Resources/AcmeBlogBundle/views/``. Isso dá o poder de sobrepor templates de qualquer pacote pago. .. tip:: Esperançosamente, a sintaxe de nomeação de template parece familiar - é a mesma convenção para nomeação usada para referir para :ref:`controller-string-syntax`. Sufixo de Template ~~~~~~~~~~~~~~~ O formato **bundle**:**controller**:**template** de cada template especifica *onde* o arquivo de template está localizado. Cada nome de template também tem duas expressões que especificam o *formato* e *engine* para aquela template. * **AcmeBlogBundle:Blog:index.html.twig** - formato HTML, engine Twig * **AcmeBlogBundle:Blog:index.html.php** - formato HTML, engine PHP * **AcmeBlogBundle:Blog:index.css.twig** - formato CSS, engine Twig Por padrão, qualquer template Symfony2 ou pode ser escrito em Twig ou em PHP, e a última parte da extensão (ex: ``.twig`` ou ``.php``) especifica qual dessas duas *engines* deveria ser usada. A primeira parte da extensão, (ex: ``.html``, ``.css``, etc) é o formato final que o template irá gerar. Ao contrário de engine, que determina como Symfony2 analisa o template, isso é simplesmente uma tática organizacional em caso do mesmo recurso precisar ser transformado como HTML(``index.html.twig``), XML (``index.xml.twig``), ou qualquer outro formato. Para mais informaçõess, leia a seção :ref:`template-formats`. .. note:: As "engines" disponíveis podem ser configurados e até mesmo ter novas engines adicionadas. Veja :ref:`Configuração de Template{{ article.title }}
by {{ article.authorName }}
{{ article.body }}
.. code-block:: phpgetTitle() ?>
by getAuthorName() ?>
getBody() ?>
Incluir este template de qualquer outro template é fácil: .. configuration-block:: .. code-block:: html+jinja {# src/Acme/ArticleBundle/Resources/Article/list.html.twig #} {% extends 'AcmeArticleBundle::layout.html.twig' %} {% block body %}Recent Articles
{% for article in articles %}
{% include 'AcmeArticleBundle:Article:articleDetails.html.twig' with {'article': article} %}
{% endfor %}
{% endblock %}
.. code-block:: php
extend('AcmeArticleBundle::layout.html.php') ?>
start('body') ?>
Recent Articles
render('AcmeArticleBundle:Article:articleDetails.html.php', array('article' => $article)) ?>
stop() ?>
O template é incluído usando a tag ``{% include %}``. Perceba que o
nome do template segue a mesma convenção típica. O template ``articleDetails.html.twig``
usa uma variável ``article``. Isso é passado por um template ``list.html.twig``
usando o comando ``with``.
.. tip::
A sintaxe ``{'article': article}`` é a sintaxe Twig padrão para hash
maps (ex: um array com chaves nomeadas). Se nós precisarmos passá-lo em elementos
múltiplos, ele poderia ser algo como: ``{'foo': foo, 'bar': bar}``.
.. index::
single: Templating; Incorporação de ações
.. _templating-embedding-controller:
Incorporação de Controllers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Em alguns casos, você precisa fazer mais do que incluir um template simples. Suponha
que você tenha uma barra lateral no seu layout que contenha os três artigos mais recentes.
Recuperar os três artigos podem incluir consultar a base de dados ou desempenhar
outra lógica pesada que não pode ser a partir de um template.
A solução é simplesmnte incorporar o resultado de um controller inteiro para
seu template. Primeiro, crie o controller que retorne um certo número de artigos
recentes :
.. code-block:: php
// src/Acme/ArticleBundle/Controller/ArticleController.php
class ArticleController extends Controller
{
public function recentArticlesAction($max = 3)
{
// make a database call or other logic to get the "$max" most recent articles
$articles = ...;
return $this->render('AcmeArticleBundle:Article:recentList.html.twig', array('articles' => $articles));
}
}
A template ``recentList`` é perfeitamente straightforward:
.. configuration-block::
.. code-block:: html+jinja
{# src/Acme/ArticleBundle/Resources/views/Article/recentList.html.twig #}
{% for article in articles %}
{{ article.title }}
{% endfor %}
.. code-block:: php
getTitle() ?>
.. note::
Perceba que nós fizemos uma gambiarra e fizemos um hardcode no artigo URL desse exemplo
(ex: ``/article/*slug*``). Isso é uma prática ruim. Na próxima seção,
você irá aprender como fazer isso corretamente.
Para incluir um controller, você irá precisar referir a ela usando a sintaxe de string
padrão para controllers (isto é, **bundle**:**controller**:**action**):
.. configuration-block::
.. code-block:: html+jinja
{# app/Resources/views/base.html.twig #}
...
.. code-block:: php
...
Sempre quando você pensar que você precisa de uma variável ou uma peça de informação que
você não tenha acesso em um template, considere transformar o controller.
Controllers são rápidos para executar e promovem uma boa organização e utilização do código.
Conteúdo Assíncrono com hinclude.js
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 2.1
suporte ao hinclude.js foi adicionado no Symfony 2.1
Os controladores podem ser incorporados assíncronamente usando a biblioteca javascript hinclude.js_.
Como o conteúdo incorporado vêm de outra página (ou controlador, neste assunto), o Symfony2 usa o
helper padrão ``render`` para configurar tags ``hinclude``:
.. configuration-block::
.. code-block:: jinja
{% render '...:news' with {}, {'standalone': 'js'} %}
.. code-block:: php
render('...:news', array(), array('standalone' => 'js')) ?>
.. note::
hinclude.js_ nprecisa ser incluído em sua página para funcionar.
Conteúdo padrão (enquanto carregar ou se o javascript está desabilitado) pode ser definido globalmente
na configuração da sua aplicação:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
# ...
templating:
hinclude_default_template: AcmeDemoBundle::hinclude.html.twig
.. code-block:: xml
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'templating' => array(
'hinclude_default_template' => array('AcmeDemoBundle::hinclude.html.twig'),
),
));
.. index::
single: Templating; Vinculação às páginas
Vinculação às Páginas
~~~~~~~~~~~~~~~~
Criar links para outras página em sua aplicação é uma das tarefas mais
comuns para um template. Ao invés de fazer um hardcode nas URLs nos templates, use a
função do Twig ``path`` (ou o helper ``router`` no PHP) para gerar URLs baseadas na
configuração de roteamento. Mais tarde, se você quiser modificar a URL de uma página
particular, tudo que você precisará fazer é mudar as configurações de roteamento; os
templates irão automatricamente gerar a nova URL.
Primeiro, vincule a página "_welcome" , que é acessível pela seguinte configuração de
roteamento:
.. configuration-block::
.. code-block:: yaml
_welcome:
pattern: /
defaults: { _controller: AcmeDemoBundle:Welcome:index }
.. code-block:: xml
AcmeDemoBundle:Welcome:index
.. code-block:: php
$collection = new RouteCollection();
$collection->add('_welcome', new Route('/', array(
'_controller' => 'AcmeDemoBundle:Welcome:index',
)));
return $collection;
Para vincular à página, apenas use a função Twig ``path`` e refira para a rota:
.. configuration-block::
.. code-block:: html+jinja
Home
.. code-block:: php
Home
Como esperado, isso irá gerar a URL ``/``. Vamos ver como isso irá funcionar com
uma rota mais complicada:
.. configuration-block::
.. code-block:: yaml
article_show:
pattern: /article/{slug}
defaults: { _controller: AcmeArticleBundle:Article:show }
.. code-block:: xml
AcmeArticleBundle:Article:show
.. code-block:: php
$collection = new RouteCollection();
$collection->add('article_show', new Route('/article/{slug}', array(
'_controller' => 'AcmeArticleBundle:Article:show',
)));
return $collection;
Neste caso, você precisa especificar tanto o nome da rota (``article_show``) como
um valor para o parâmetro ``{slug}``. Usando esta rota, vamos revisitar o
template ``recentList`` da sessão anterior e vincular aos artigos
corretamente:
.. configuration-block::
.. code-block:: html+jinja
{# src/Acme/ArticleBundle/Resources/views/Article/recentList.html.twig #}
{% for article in articles %}
{{ article.title }}
{% endfor %}
.. code-block:: php
getTitle() ?>
.. tip::
Você também pode gerar uma URL absoluta ao usar a função ``url`` do Twig:
.. code-block:: html+jinja
Home
O mesmo pode ser feito em templates PHP ao passar um terceiro argumento ao
método ``generate()``:
.. code-block:: php
Home
.. index::
single: Templating; Vinculando os assets
Vinculando os Assets
~~~~~~~~~~~~~~~~~
Templates podem frequentemente referir a imagens, Javascript, folhas de estilo e outros
recursos. Claro você poderia fazer um hardcode do atalho desses assets (ex: ``/images/logo.png``),
mas Symfony2 providencia uma opção mais dinâmica via função ``assets`` do Twig:
.. configuration-block::
.. code-block:: html+jinja
 }})
.. code-block:: php
 ?>)
O principal propósito da função ``asset`` é tornar sua aplicação mais portátil.
Se sua aplicação reside na raiz do seu host (ex: http://example.com),
então os atalhos interpretados deveriam ser ``/images/logo.png``. Mas se sua aplicação
reside em um sub-diretório (ex: http://example.com/my_app), cada caminho do asset
deveria interpretar com o diretório (e.g. ``/my_app/images/logo.png``). A função
``asset`` toma conta disto ao determinar como sua aplicação está
sendo usada e gerando os atalhos de acordo com o correto.
Adicionalmente, se você usar função asset, Symfony pode automaticamente
anexar uma string de consulta para asset, em detrimento de garantir que assets
estáticos atualizados não serão armazenados quando distribuídos. Por exemplo, ``/images/logo.png`` poderia
parecer como ``/images/logo.png?v2``. Para mais informações, veja a opção de configuração
:ref:`ref-framework-assets-version`.
.. index::
single: Templating; Incluindo folhas de estilo e Javascripts
single: Folhas de estilo; Incluindo folhas de estilo
single: Javascripts; Incluindo Javascripts
Incluindo Folhas de Estilo e Javascript no Twig
---------------------------------------------
Nenhum site seria completo sem incluir arquivos Javascript e folhas de estilo.
Em Symfony, a inclusão desses assets é elegantemente manipulada ao tirar
vantagem das heranças de template do Symfony.
.. tip::
Esta seção irá ensinar você a filosofia por trás disto, incluindo folha de estilo
e asset Javascript em Symfony. Symfony também engloba outra biblioteca,
chamada Assetic, que segue essa filosofia mas também permite você fazer mais coisas
muito interessantes com esses assets. Para mais informações sobre
usar Assetic veja :doc:`/cookbook/assetic/asset_management`.
Comece adicionando dois blocos a seu template base que irá abrigar seus assets:
uma chamada ``stylesheets`` dentro da tag ``head`` e outra chamada ``javascripts``
justamente acima do fechamento da tag ``body``. Esses blocos irão conter todas as
folhas de estilo e Javascripts que você irá precisar através do seu site:
.. code-block:: html+jinja
{# 'app/Resources/views/base.html.twig' #}
{# ... #}
{% block stylesheets %}
{% endblock %}
{# ... #}
{% block javascripts %}
{% endblock %}
Isso é fácil o bastante ! Mas e se você precisar incluir uma folha de estilo ou
Javascript de um template filho ? Por exemplo, suponha que você tenha uma página
de contatos e você precise incluir uma folha de estilo ``contact.css`` *bem* naquela
página. Dentro do template da página de contatos, faça o seguinte:
.. code-block:: html+jinja
{# src/Acme/DemoBundle/Resources/views/Contact/contact.html.twig #}
{# extends '::base.html.twig' #}
{% block stylesheets %}
{{ parent() }}
{% endblock %}
{# ... #}
No template filho, você simplesmente sobrepõe o bloco ``stylesheets`` e
coloca sua nova tag de folha de estilo dentro daquele bloco. Claro, desde que você queira
adicionar ao conteúdo do bloco pai (e realmente não irá *substituí-lo), você
deveria usar a função ``parent()`` do Twig function para incluir tudo do bloco ``stylesheets``
do template base.
Você pode também incluir assets localizados em seus arquivos de pacotes ``Resources/public``.
Você precisará executar o comando``php app/console assets:install target [--symlink]`` ,
que move (ou symlinks) arquivos dentro da localização correta.
(target é sempre por padrão "web).
.. code-block:: html+jinja
O resultado final é uma página que inclui ambas as folhas de estilo
``main.css`` e ``contact.css``.
.. index::
single: Templating; O Serviço de Templating
Configurando e usando o Serviço ``templating``
------------------------------------------------
O coração do sistema de template em Symfony2 é o template ``Engine``.
Este objeto especial é responsável por manipular templates e retornar
o conteúdo deles. Quando você manipula um template em um controller, por exemplo,
você está na verdade usando o serviço do template engine. Por exemplo:
.. code-block:: php
return $this->render('AcmeArticleBundle:Article:index.html.twig');
é equivalente a:
.. code-block:: php
$engine = $this->container->get('templating');
$content = $engine->render('AcmeArticleBundle:Article:index.html.twig');
return $response = new Response($content);
.. _template-configuration:
O engine de template (ou "serviço") é pré-configurada para trabalhar automaticamente
dentro de Symfony2. Ele pode, claro, ser configurado mais adiante no arquivo
de configuração da aplicação:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
# ...
templating: { engines: ['twig'] }
.. code-block:: xml
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'templating' => array(
'engines' => array('twig'),
),
));
Várias opções de configuração estão disponíveis e estão cobertos em
:doc:`Configuration Appendix`.
.. note::
O engine ``twig`` é obrigatório para usar o webprofiler (bem como outros
pacotes de terceiros).
.. index::
single; Template; Sobrepondo templates
.. _overriding-bundle-templates:
Sobrepondo Templates de Pacote
---------------------------
A comunidade Symfony2 orgulha-se de si própria em criar e manter pacotes
de alta qualidade (veja `Symfony2Bundles.org`_) para um grande número de funcionalidades diferentes.
Uma vez que você use um pacote de terceiros, você irá certamente precisar sobrepor e personalizar
um ou mais de seus templates.
Suponha que você incluiu o imaginário open-source ``AcmeBlogBundle`` em seu
projeto (ex: no diretório ``src/Acme/BlogBundle``). E enquanto você estiver
realmente feliz com tudo, você quer sobrepor a página de "lista" do blog para
personalizar a marcação especificamente para sua aplicação. Ao se aprofundar no
controller ``Blog`` eo ``AcmeBlogBundle``, você encontrará o seguinte::
public function indexAction()
{
$blogs = // some logic to retrieve the blogs
$this->render('AcmeBlogBundle:Blog:index.html.twig', array('blogs' => $blogs));
}
Quando ``AcmeBlogBundle:Blog:index.html.twig`` é manipulado, Symfony2 realmente
observa duas diferentes localizações para o template:
#. ``app/Resources/AcmeBlogBundle/views/Blog/index.html.twig``
#. ``src/Acme/BlogBundle/Resources/views/Blog/index.html.twig``
Para sobrepor o template de pacote, só copie o template ``index.html.twig``
do pacote para ``app/Resources/AcmeBlogBundle/views/Blog/index.html.twig``
(o diretório ``app/Resources/AcmeBlogBundle`` não existirão, então você precisará
criá-lo). Você está livre agora para personalizar o template.
Esta lógica também se aplica a templates de pacote base. Suponha também que cada
template em ``AcmeBlogBundle`` herda de um template base chamado
``AcmeBlogBundle::layout.html.twig``. Justo como antes, Symfony2 irá observar os
seguintes dois lugares para o template:
#. ``app/Resources/AcmeBlogBundle/views/layout.html.twig``
#. ``src/Acme/BlogBundle/Resources/views/layout.html.twig``
Uma vez novamente, para sobrepor o template, apenas copie ele para
``app/Resources/AcmeBlogBundle/views/layout.html.twig``. Você agora está livre para
personalizar esta cópia como você quiser.
Se você voltar um passo atrás, verá que Symfony2 sempre começa a observar no
diretório ``app/Resources/{BUNDLE_NAME}/views/`` por um template. Se o
template não existe aqui, ele continua checando dentro do diretório
``Resources/views`` do próprio pacote. Isso significa que todos os templates
do pacote podem ser sobrepostos ao colocá-los no sub-diretório correto
``app/Resources``.
.. _templating-overriding-core-templates:
.. index::
single; Template; Overriding exception templates
Sobrepondo Templates Centrais
~~~~~~~~~~~~~~~~~~~~~~~~~
Como o framework Symfony é um pacote por si só, templates centrais podem ser
sobrepostos da mesma forma. Por exemplo, o núcleo ``TwigBundle`` contém
um númeto de diferentes templates "exception" e "error" que podem ser sobrepostas
ao copiar cada uma do diretório ``Resources/views/Exception`` do ``TwigBundle``
para, você adivinhou, o diretório
``app/Resources/TwigBundle/views/Exception`` .
.. index::
single: Templating; Three-level inheritance pattern
Herança de Três Níveis
-----------------------
Um modo comum de usar herança é usar uma aproximação em três níveis. Este
método trabalha perfeitamente com três tipos diferentes de templates que nós
certamente cobrimos:
* Criar um arquivo ``app/Resources/views/base.html.twig`` que contém o layout
principal para sua aplicação (como nos exemplos anteriores). Internamente, este
template é chamado ``::base.html.twig``;
* Cria um template para cada "seção" do seu site. Por exemplo, um ``AcmeBlogBundle``,
teria um template chamado ``AcmeBlogBundle::layout.html.twig`` que contém somente
elementos específicos para a sessão no blog:
.. code-block:: html+jinja
{# src/Acme/BlogBundle/Resources/views/layout.html.twig #}
{% extends '::base.html.twig' %}
{% block body %}
Blog Application
{% block content %}{% endblock %}
{% endblock %}
* Criar templates individuais para cada página e fazer cada um estender a template
de sessão apropriada. Por exemplo, a página "index" deveria ser chamada de algo
próximo a ``AcmeBlogBundle:Blog:index.html.twig`` e listar os blogs de posts reais.
.. code-block:: html+jinja
{# src/Acme/BlogBundle/Resources/views/Blog/index.html.twig #}
{% extends 'AcmeBlogBundle::layout.html.twig' %}
{% block content %}
{% for entry in blog_entries %}
{{ entry.title }}
Recent Articles
render('AcmeArticleBundle:Article:articleDetails.html.php', array('article' => $article)) ?> stop() ?> O template é incluído usando a tag ``{% include %}``. Perceba que o nome do template segue a mesma convenção típica. O template ``articleDetails.html.twig`` usa uma variável ``article``. Isso é passado por um template ``list.html.twig`` usando o comando ``with``. .. tip:: A sintaxe ``{'article': article}`` é a sintaxe Twig padrão para hash maps (ex: um array com chaves nomeadas). Se nós precisarmos passá-lo em elementos múltiplos, ele poderia ser algo como: ``{'foo': foo, 'bar': bar}``. .. index:: single: Templating; Incorporação de ações .. _templating-embedding-controller: Incorporação de Controllers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Em alguns casos, você precisa fazer mais do que incluir um template simples. Suponha que você tenha uma barra lateral no seu layout que contenha os três artigos mais recentes. Recuperar os três artigos podem incluir consultar a base de dados ou desempenhar outra lógica pesada que não pode ser a partir de um template. A solução é simplesmnte incorporar o resultado de um controller inteiro para seu template. Primeiro, crie o controller que retorne um certo número de artigos recentes : .. code-block:: php // src/Acme/ArticleBundle/Controller/ArticleController.php class ArticleController extends Controller { public function recentArticlesAction($max = 3) { // make a database call or other logic to get the "$max" most recent articles $articles = ...; return $this->render('AcmeArticleBundle:Article:recentList.html.twig', array('articles' => $articles)); } } A template ``recentList`` é perfeitamente straightforward: .. configuration-block:: .. code-block:: html+jinja {# src/Acme/ArticleBundle/Resources/views/Article/recentList.html.twig #} {% for article in articles %} {{ article.title }} {% endfor %} .. code-block:: php getTitle() ?> .. note:: Perceba que nós fizemos uma gambiarra e fizemos um hardcode no artigo URL desse exemplo (ex: ``/article/*slug*``). Isso é uma prática ruim. Na próxima seção, você irá aprender como fazer isso corretamente. Para incluir um controller, você irá precisar referir a ela usando a sintaxe de string padrão para controllers (isto é, **bundle**:**controller**:**action**): .. configuration-block:: .. code-block:: html+jinja {# app/Resources/views/base.html.twig #} ... .. code-block:: php ... Sempre quando você pensar que você precisa de uma variável ou uma peça de informação que você não tenha acesso em um template, considere transformar o controller. Controllers são rápidos para executar e promovem uma boa organização e utilização do código. Conteúdo Assíncrono com hinclude.js ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.1 suporte ao hinclude.js foi adicionado no Symfony 2.1 Os controladores podem ser incorporados assíncronamente usando a biblioteca javascript hinclude.js_. Como o conteúdo incorporado vêm de outra página (ou controlador, neste assunto), o Symfony2 usa o helper padrão ``render`` para configurar tags ``hinclude``: .. configuration-block:: .. code-block:: jinja {% render '...:news' with {}, {'standalone': 'js'} %} .. code-block:: php render('...:news', array(), array('standalone' => 'js')) ?> .. note:: hinclude.js_ nprecisa ser incluído em sua página para funcionar. Conteúdo padrão (enquanto carregar ou se o javascript está desabilitado) pode ser definido globalmente na configuração da sua aplicação: .. configuration-block:: .. code-block:: yaml # app/config/config.yml framework: # ... templating: hinclude_default_template: AcmeDemoBundle::hinclude.html.twig .. code-block:: xml
.. code-block:: php
O principal propósito da função ``asset`` é tornar sua aplicação mais portátil.
Se sua aplicação reside na raiz do seu host (ex: http://example.com),
então os atalhos interpretados deveriam ser ``/images/logo.png``. Mas se sua aplicação
reside em um sub-diretório (ex: http://example.com/my_app), cada caminho do asset
deveria interpretar com o diretório (e.g. ``/my_app/images/logo.png``). A função
``asset`` toma conta disto ao determinar como sua aplicação está
sendo usada e gerando os atalhos de acordo com o correto.
Adicionalmente, se você usar função asset, Symfony pode automaticamente
anexar uma string de consulta para asset, em detrimento de garantir que assets
estáticos atualizados não serão armazenados quando distribuídos. Por exemplo, ``/images/logo.png`` poderia
parecer como ``/images/logo.png?v2``. Para mais informações, veja a opção de configuração
:ref:`ref-framework-assets-version`.
.. index::
single: Templating; Incluindo folhas de estilo e Javascripts
single: Folhas de estilo; Incluindo folhas de estilo
single: Javascripts; Incluindo Javascripts
Incluindo Folhas de Estilo e Javascript no Twig
---------------------------------------------
Nenhum site seria completo sem incluir arquivos Javascript e folhas de estilo.
Em Symfony, a inclusão desses assets é elegantemente manipulada ao tirar
vantagem das heranças de template do Symfony.
.. tip::
Esta seção irá ensinar você a filosofia por trás disto, incluindo folha de estilo
e asset Javascript em Symfony. Symfony também engloba outra biblioteca,
chamada Assetic, que segue essa filosofia mas também permite você fazer mais coisas
muito interessantes com esses assets. Para mais informações sobre
usar Assetic veja :doc:`/cookbook/assetic/asset_management`.
Comece adicionando dois blocos a seu template base que irá abrigar seus assets:
uma chamada ``stylesheets`` dentro da tag ``head`` e outra chamada ``javascripts``
justamente acima do fechamento da tag ``body``. Esses blocos irão conter todas as
folhas de estilo e Javascripts que você irá precisar através do seu site:
.. code-block:: html+jinja
{# 'app/Resources/views/base.html.twig' #}
{# ... #}
{% block stylesheets %}
{% endblock %}
{# ... #}
{% block javascripts %}
{% endblock %}
Isso é fácil o bastante ! Mas e se você precisar incluir uma folha de estilo ou
Javascript de um template filho ? Por exemplo, suponha que você tenha uma página
de contatos e você precise incluir uma folha de estilo ``contact.css`` *bem* naquela
página. Dentro do template da página de contatos, faça o seguinte:
.. code-block:: html+jinja
{# src/Acme/DemoBundle/Resources/views/Contact/contact.html.twig #}
{# extends '::base.html.twig' #}
{% block stylesheets %}
{{ parent() }}
{% endblock %}
{# ... #}
No template filho, você simplesmente sobrepõe o bloco ``stylesheets`` e
coloca sua nova tag de folha de estilo dentro daquele bloco. Claro, desde que você queira
adicionar ao conteúdo do bloco pai (e realmente não irá *substituí-lo), você
deveria usar a função ``parent()`` do Twig function para incluir tudo do bloco ``stylesheets``
do template base.
Você pode também incluir assets localizados em seus arquivos de pacotes ``Resources/public``.
Você precisará executar o comando``php app/console assets:install target [--symlink]`` ,
que move (ou symlinks) arquivos dentro da localização correta.
(target é sempre por padrão "web).
.. code-block:: html+jinja
O resultado final é uma página que inclui ambas as folhas de estilo
``main.css`` e ``contact.css``.
.. index::
single: Templating; O Serviço de Templating
Configurando e usando o Serviço ``templating``
------------------------------------------------
O coração do sistema de template em Symfony2 é o template ``Engine``.
Este objeto especial é responsável por manipular templates e retornar
o conteúdo deles. Quando você manipula um template em um controller, por exemplo,
você está na verdade usando o serviço do template engine. Por exemplo:
.. code-block:: php
return $this->render('AcmeArticleBundle:Article:index.html.twig');
é equivalente a:
.. code-block:: php
$engine = $this->container->get('templating');
$content = $engine->render('AcmeArticleBundle:Article:index.html.twig');
return $response = new Response($content);
.. _template-configuration:
O engine de template (ou "serviço") é pré-configurada para trabalhar automaticamente
dentro de Symfony2. Ele pode, claro, ser configurado mais adiante no arquivo
de configuração da aplicação:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
# ...
templating: { engines: ['twig'] }
.. code-block:: xml
Blog Application
{% block content %}{% endblock %} {% endblock %} * Criar templates individuais para cada página e fazer cada um estender a template de sessão apropriada. Por exemplo, a página "index" deveria ser chamada de algo próximo a ``AcmeBlogBundle:Blog:index.html.twig`` e listar os blogs de posts reais. .. code-block:: html+jinja {# src/Acme/BlogBundle/Resources/views/Blog/index.html.twig #} {% extends 'AcmeBlogBundle::layout.html.twig' %} {% block content %} {% for entry in blog_entries %}{{ entry.title }}
{{ entry.body }}
{% endfor %} {% endblock %} Perceba que este template estende a template de sessão - (``AcmeBlogBundle::layout.html.twig``) que por sua vez estende o layout de aplicação base (``::base.html.twig``). Isso é o modelo comum de herança de três níveis. Quando construir sua aplicação, você pode escolher seguir esse método ou simplesmente tornar cada template de página estender a template de aplicação base diretamente (ex: ``{% extends '::base.html.twig' %}``). O modelo de três templates é o método de melhor prática usado por vendor bundles então aquele template base para um pacote pode ser facilmente sobreposto para propriamente estender seu layout base de aplicação. .. index:: single: Templating; Saída para escape Saída para escape --------------- Quando gerar HTML de um template, sempre há um risco que uma variável de template pode gerar HTML involutário ou codigo do lado cliente perigoso. O resultado é que o conteúdo dinâmico poderia quebrar o HTML de uma página de resultados ou permitir um usuário maldoso realizar um ataque `Cross Site Scripting`_ (XSS). Considere esse exemplo clássico: .. configuration-block:: .. code-block:: jinja Hello {{ name }} .. code-block:: php Hello Imagine que o usuário entre o seguinte código como o nome dele/dela:: Sem qualquer outra saída de escape, o resultado da template irá causar uma caixa de alerta em JavaScript para saltar na tela:: Hello E enquanto isso parece inofensivo, se um usuário pode chegar tão longe, o mesmo usuário deveria também ser capaz de escrever Javascript que realiza ações maliciosas dentro de uma área segura de um usuário legítimo e desconhecido. A resposta para o problema é saída para escape. Sem a saída para escape ativa, o mesmo template irá manipular inofensivamente, e literalmente imprimir a tag ``script`` na tela:: Hello <script>alert('helloe')</script> Os sistemas de templating Twig e PHP aproximam-se do problema de formas diferentes. Se você está usando Twig, saída para escape é ativado por padrão e você está protegido. Em PHP, saída para escape não é automático, significando que você precisará manualmente fazer o escape quando necessário. Saída para escape em Twig ~~~~~~~~~~~~~~~~~~~~~~~~~ Se você está usando templates Twig, então saída para escape é ativado por padrão. Isto significa que você está protegido externamente de consequencias acidentais por código submetido por usuário. Por padrão, a saída para escape assume que o conteúdo está sendo escapado pela saída HTML. Em alguns casos, você precisará desabilitar saída para escape quando você está manipulando uma variável que é confiável e contém marcação que não poderia ter escape. Suponha que usuários administrativos são capazes de escrever artigos que contenham código HTML. Por padrão, Twig irá escapar o corpo do artigo. Para fazê-lo normalamente, adicione o filtro ``raw``: ``{{ article.body | raw }}``. Você pode também desabilitar saída para escape dentro de uma área ``{% block %}`` ou para um template inteiro. Para mais informações, veja `Output Escaping`_ na documentação do Twig. Saída para escape em PHP ~~~~~~~~~~~~~~~~~~~~~~~~ Saída para escape não é automática quando usamos templates PHP. Isso significa que a menos que você escolha escapar uma variável explicitamente, você não está protegido. Para usar saída para escape use o método de view ``escape()``:: Hello escape($name) ?> Por padrão, o método ``escape()`` assume que a variável está sendo manipulada dentro de um contexto HTML (e assim a variável escapa e está segura para o HTML). O segundo argumento deixa você mudar o contexto. Por exemplo, para gerar algo em uma string Javascript, use o contexto ``js`` : .. code-block:: js var myMsg = 'Hello escape($name, 'js') ?>'; .. index:: single: Templating; Formats .. _template-formats: Debugging --------- .. versionadded:: 2.0.9 Esta funcionalidade está disponível no Twig ``1.5.x``, e foi adicionada primeiramente no Symfony 2.0.9. Ao utilizar o PHP, você pode usar o ``var_dump()`` se precisa encontrar rapidamente o valor de uma variável passada. Isso é útil, por exemplo, dentro de seu controlador. O mesmo pode ser conseguido ao usar o Twig com a extensão de depuração. Esta extensão precisa ser ativada na configuração: .. configuration-block:: .. code-block:: yaml # app/config/config.yml services: acme_hello.twig.extension.debug: class: Twig_Extension_Debug tags: - { name: 'twig.extension' } .. code-block:: xml