Django Templates (editado e resumido)

Postado em: Fevereiro 16, 2008
Tags: django

A linguagem de template do Django foi designada para estabelecer um equilíbrio entre poder e facilidade. Ele foi designado para ser confortável para aqueles que trabalham com HTML. Se você já conhece outras linguagens de template como, Smarty ou CheetahTemplate, você se sentira em casa com os templates do Django.

Templates

O template é um arquivo texto simples. Ele pode gerar um arquivo baseado em texto formatado (HTML, XML, CSV, etc.).
O template contem variáveis, quando o template é avaliado essas variáveis são substituídas por valores, e tags que controlam a lógica do template.

A baixo temos um modelo bem simples que ilustra o básico:

{% extends "base.html" %}

{% block titulo %}{{ sessao.titulo }}{% endblock %}

{% block conteudo %}
<h1>{{ sessao.titulo }}</h1>

{% for noticia in noticia_lista %}
<h2>
  <a href="{{ noticia.get_absolute_url }}">
    {{ noticia.titulo|upper }}
  </a>
</h2>
<p>{{ noticia.texto|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}

Variáveis

Variáveis são assim: {{ variavel }}. Quando um template encontra essa variável ele a avalia e substitui por um valor.
Use um ponto (.) para acessar os atributos.
No exemplo, {{ sessao.titulo }} será substituído pelo atributo titulo do objeto sessão.

Se você usar uma variável que não existe, o sistema do template vai inserir um valor da configuração TEMPLATE_STRING_IF_INVALID com isso ele seta '' (string vazia) por padrão.

Filtros

Você pode modificar as variáveis para serem mostradas usando filtros.

Filtros se parecem com isso: {{ nome|lower }}. Isso mostra o valor da variável {{ nome }} depois de ter sido filtrado pelo filtro lower, isso converte o texto para minúsculas. Use o pipe (|) para aplicar os filtros.

Os filtros podem ser "encadeados". A saída de um filtro é aplicada ao próximo. {{ texto|escape|linebreaks }} escape é comum para textos, e o linebreaks converte as quebras de linhas em <p> tags.

Alguns filtros têm argumentos. Um filtro de argumento parece com isso: {{ bio|truncatewords:30 }}. Isso mostra as primeiras 30 palavras da variável bio.
Os argumentos de filtros que contem espaços devem ser quoted, por exemplo, para inserir em uma lista espaços e virgulas use {{ lista|join:", " }}.

Comentários

Para comentar uma parte de uma linha no template, use a sintaxe: {# #}.
Por exemplo, um template que mostra "ola":

{# mundo #}ola

Um comentário pode conter código, valido ou não. Por exemplo:

{# {% if passou %}parabéns{% else %} #}

Essa sintaxe só pode ser usada em uma linha de comentário. Se você quiser comentar múltiplas linhas use a tag comment que pode ser vista aqui http://www.djangoproject.com/documentation/templates/#comment

Herança de Template

O mais poderoso – e a mais complexa – parte da engine de template do Django é a herança. A herança de template te possibilita criar uma base "esqueleto" de template que contem os elementos mais comuns de um site e elementos de bloco que diz para o template que nessas regiões o código será sobrescrito.

É fácil de se entender como a herança de template funciona, vamos iniciar com um exemplo "base.html":

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />
    <title>{% block titulo %}Meu site{% endblock %}</title>
</head>

<body>
    <div id="sidebar">
        {% block sidebar %}
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
        {% endblock %}
    </div>

<div id="conteudo">
        {% block conteudo %}{% endblock %}
    </div>
</body>
</html>

Esse template, no qual vamos chamar de base.html, define um esqueleto de html simples que é usado para gerar uma pagina de duas colunas. É o trabalho do template "filho" preencher os blocos vazios com conteúdo.
Nesse exemplo, o {% block %} define três colunas no qual o template pode preencher. Todas as tags block dizem para o template filho que essas partes de código podem ser sobrescritas.
O template filho se parece com esse:

{% extends "base.html" %}

{% block titulo %}Meu blog{% endblock %}

{% block conteudo %}
{% for posts in blog_posts %}
    <h2>{{ posts.titulo }}</h2>
    <p>{{ posts.post }}</p>
{% endfor %}
{% endblock %}

A tag {% extends %} é a chave. Ela diz para o template se "estender" ao outro template. Quando o sistema de template avalia esse template, primeiro ele localiza a base, no caso, "base.html"

Até esse ponto, o template avisa que as três tags {% block %} no base.html serão substituídas pelo conteúdo do template filho. Dependendo do valor em blog_posts, a saída se parece com isso:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />
    <title>Meu blog</title>
</head>

<body>
    <div id="sidebar">
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
    </div>

<div id="conteudo">
        <h2>Post titulo</h2>
        <p>Esse é o meu primeiro post.</p>

<h2>Segundo post</h2>
        <p>Esse é o meu segundo post.</p>
    </div>
</body>
</html>

Note que o template filho não define o bloco sidebar, o valor vem do template base. O conteúdo na tag {% block %} no template base sempre será retornado.

No momento é isso, espero que façam bom proveito, para mais detalhes consultem a documentação oficial, tem muito mais coisas, isso foi apenas uma tradução do inicio da documentação, mais adiante abordarei mais detalhes importantes sobre os templates.
Link para a documentação oficial: Django Templates