Django v1.0 documentation

Tags e filtros de template embutidos (Built-in)

Este documento descreve as tags e filtros de templates embutidos do Django. É recomendado o uso da documentação automática, se disponível, que irá incluir a documentação de qualquer tag ou filtro personalizado instalado.

Referência de tags nativas

autoescape

Novo no Django 1.0.

Controla o comportamento de auto-scaping atual. Esta tag tem que receber on ou off como um argumento que determina se o auto-scaping surtirá efeito dentro do bloco.

Quando o auto-scaping surte efeito, todo conteúdo de variável tem seu HTML escapado, antes do resultado ser jogado para saída (mas depois dos filtros serem aplicados). Isto equivale a você aplicar manualmente o filtro escape em cada variável.

A única exceção são variáveis que já estão marcadas como “safe”, que atráves de código foram povoadas, ou porque tem os filtros safe ou escape aplicados.

block

Define um bloco que pode ser sobrescrito por um template filho. Veja Herança de template para mais informações.

comment

Ignora tudo entre dois {% comment %} e {% endcomment %}

cycle

Alterado no Django 1.0: Ciclo entre dadas strings ou variáveis a cada vez que esta tag é encontrada.

Dentro de um loop, ciclos entre dadas strings a cada volta dentro do loop:

{% for o in some_list %}
    <tr class="{% cycle 'row1' 'row2' %}">
        ...
    </tr>
{% endfor %}

Você pode usar variáveis, também. Por exemplo, se você tem duas variáveis de template, rowvalue1 e rowvalue2, você pode montar ciclos entre seus valores desta forma:

{% for o in some_list %}
    <tr class="{% cycle rowvalue1 rowvalue2 %}">
        ...
    </tr>
{% endfor %}

Sim, você pode mesclar variáveis e strings:

{% for o in some_list %}
    <tr class="{% cycle 'row1' rowvalue2 'row3' %}">
        ...
    </tr>
{% endfor %}

Em alguns casos você pode querer referenciar o próximo valor de um ciclo de fora de um loop. Para fazer isto, é só ter uma tag {% cycle %}, usando "as", desta forma:

{% cycle 'row1' 'row2' as rowcolors %}

A partir daqui, você pode inserir o valor atual de um ciclo onde você quiser dentro do seu template:

<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>

Você pode usar qualquer número de valores em uma tag {% cycle %}, separados por espaços. Os valores colocados dentro de aspas simples (') ou duplas (") são tratados como strings, enquanto que valores sem aspas serão tratados como variáveis de template.

Perceba que as variáveis incluídas no cycle não serão escapadas. Isto porque a tag de template não escapa seus conteúdos. Se você deseja escapar as variáveis no cycle, você deve fazê-lo explicitamente:

{% filter force_escape %}
    {% cycle var1 var2 var3 %}
{% endfilter %}

Para retro-compatibilidade, a tag {% cycle %} suporta a mais antiga sintaxe vinda de versões antigas do Django. Você não deve usar isto em qualquer novo projeto, porém, para saúde das pessoas que ainda estão usando-o, aqui está a a forma antiga de se usar:

{% cycle row1,row2,row3 %}

Nesta sintaxe, cada valor é interpretado como uma string, e não há meios de especificar valores de variáveis. Ou vígulas de fato. Ou espaços. Nós mensionamos que você não deve usar esta sintaxe em nenhum novo projeto?

debug

Mostra todas as informações carregadas de debug, incluindo o contexto atual e os módulos importados.

extends

Sinal que este template extende um template pai.

Esta tag pode ser usada de duas formas:

  • {% extends "base.html" %} (sem aspas) usa o valor literal "base.html" como o nome do template pai a ser extendido.
  • {% extends variable %} usa o valor da variable. Se a variável é uma string, o Django irá usá-la como o nome do template pai. Se a variável for um objeto Template, o Django irá usar o objeto como o template pai.

Veja Template inheritance para mais informações.

filter

Filtra os conteúdos da variável através da variável filtros.

Filtros podem também ser combinados entre eles, e eles podem ter argumentos -- assim como na sintaxe de variáveis.

Exemplo de uso:

{% filter force_escape|lower %}
    Este texto terá o HTML escapado, e irá aparecer todo em minúsculo.
{% endfilter %}

firstof

Mostra a primeira variável passada que não for False, sem escape.

Não mostra nada se todas as variáveis recebidas forem False.

Exemplo de uso:

{% firstof var1 var2 var3 %}

Isto é equivalente a:

{% if var1 %}
    {{ var1|safe }}
{% else %}{% if var2 %}
    {{ var2|safe }}
{% else %}{% if var3 %}
    {{ var3|safe }}
{% endif %}{% endif %}{% endif %}

Você pode também usar uma string como um valor de segurança no caso de todas as variáveis passadas serem False:

{% firstof var1 var2 var3 "valor de segurança" %}

Note que as variáveis incluídas na tag firstof não serão escapadas. Isto porque as tags de template não são escapam seus conteúdos. Se você deseja escapar o conteúdo das variáveis da tag firstof, você deve fazê-lo explicitamente:

{% filter force_escape %}
    {% firstof var1 var2 var3 "fallback value" %}
{% endfilter %}

for

Faz um loop sobre cada item de um array. Por exemplo, para mostrar uma lista de atletas vindos de athlete_list:

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% endfor %}
</ul>

Você pode iterar a lista ao contrário usando {% for obj in list reversed %}.

Novo no Django 1.0.

Se você precisa iterar uma lista de listas, você pode descompactar os valores de cada sub-lista em variáveis individuais. Por exemplo, se seu contexto contém uma lista de coordenadas (x,y) chamada points, você poderia usar a seguinte saída de lista de pontos:

{% for x, y in points %}
    Este é um ponto em {{ x }},{{ y }}
{% endfor %}

Isso também pode ser útil se você precisa acessar os ítens de um dicionário. Por exemplo, se seu contexto contém um dicionário data, o seguinte código irá mostrar as chaves e valores do dicionário:

{% for key, value in data.items %}
    {{ key }}: {{ value }}
{% endfor %}

O loop for cria algumas variáveis dentro do loop:

Variável Descrição
forloop.counter A iteração atual do loop (começando de 1)
forloop.counter0 A iteração atual do loop (começando de 0)
forloop.revcounter O número de iterações começando do final do loop (começando do 1)
forloop.revcounter0 O número de iterações começando do final do loop (começando do 0)
forloop.first True se esta é a primeira volta do loop
forloop.last True se esta é a última volta do loop
forloop.parentloop Para loops aninhados, este é o loop "acima" do loop atual

if

A tag {% if %} avalia uma variável, e se a variável for "verdadeira" (i.e. existe, não está vazia, e não tem um valor booleano falso) o conteúdo do bloco é mostrado:

{% if athlete_list %}
    Número de atletas: {{ athlete_list|length }}
{% else %}
    Não há atletas.
{% endif %}

Acima, se athlete_list não for vazio, o numero de atletas será mostrado pela variável {{ athlete_list|length }}.

Como você pode ver, a tag if pode ter uma clausula opcional {% else %} que será mostrado se o teste falhar.

As tags if podem usar and, or ou not para testar um várias variáveis ou para negá-las:

{% if athlete_list and coach_list %}
    Ambos, atletas e treinadores estão disponíveis.
{% endif %}

{% if not athlete_list %}
    Não há atletas.
{% endif %}

{% if athlete_list or coach_list %}
    Há alguns atletas ou alguns treinadores.
{% endif %}

{% if not athlete_list or coach_list %}
    Não á atletas ou há alguns treinadores (OK, escrever lógica
    booleana em português parece idiota. Mas não é falha nossa.
    Escreveram isso em ingês antes, hehehe).
{% endif %}

{% if athlete_list and not coach_list %}
    There are some athletes and absolutely no coaches.
    Não há qualquer atleta e absolutamente nenhum treinador.
{% endif %}

As tags if não permitem clausulas and e or dentro da mesma tag, pois a ordem da lógica pode ser ambígua. Por exemplo, isto é inválido:

{% if athlete_list and coach_list or cheerleader_list %}

Se você precisa combinar and e or para lógica avançada, use as tags if aninhadas. Por exemplo:

{% if athlete_list %}
    {% if coach_list or cheerleader_list %}
        Nós temos atletas, e também treinadores ou líderes de torcida!
    {% endif %}
{% endif %}

Múltiplos usos do mesmo operador lógico são bons, desde que você use o mesmo operador. Por exemplo, istó é válido:

{% if athlete_list or coach_list or parent_list or teacher_list %}

ifchanged

Checa se o valor mudou desde a última iteração de um loop.

O tag de bloco 'ifchanged' é usada dentro de um loop. Existem duas possibilidades de uso.

  1. Checa seu próprio conteúdo renderizado contra seu estado anterior e somente mostra o conteúdo se ele mudou. Por exemplo, isto mostra uma lista de dias, somente mostrando o mês se ele muda:

    <h1>Archive for {{ year }}</h1>
    
    {% for date in days %}
        {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
        <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
    {% endfor %}
    
  2. Para uma determinada variável, checa e essa variável mudou. Por exemplo, a seguinte código mostra a data toda vez que ela muda, mas somente mostra a hora se ambos, hora e data, tiverem mudado:

    {% for date in days %}
        {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
        {% ifchanged date.hour date.date %}
            {{ date.hour }}
        {% endifchanged %}
    {% endfor %}
    

A tag ifchanged pode também ter uma cláusula opicional {% else %} que será mostrada se o valor não mudou:

{% for match in matches %}
    <div style="background-color:
        {% ifchanged match.ballot_id %}
            {% cycle "red" "blue" %}
        {% else %}
            grey
        {% endifchanged %}
    ">{{ match }}</div>

ifequal

Mostra os conteúdos do bloco se os dois argumentos forem iguais entre si.

Exemplo:

{% ifequal user.id comment.user_id %}
    ...
{% endifequal %}

Assim como na tag {% if %}, uma clausula {% else %}` é opcional.

Os argumentos podem ser strings hard-coded, então o seguinte é válido:

{% ifequal user.username "adrian" %}
    ...
{% endifequal %}

Somente é possível comparar um argumentos que sejam variáveis de template ou strings. Você não pode checar a igualdade entre objetos Python com True ou False. Se você precisa testar se algo é verdadeiro ou falso, use a tag if.

ifnotequal

Exatamente como ifequal, exceto que testa se os dois argumentos não são iguais.

include

Carrega um template e o renderiza com o contexto atual. Este é o meio que se tem para "incluir" um template dentro do outro.

O nome do template pode ser tanto uma variável quanto uma string entre aspas, simples ou duplas.

Este exemplo incluí o conteúdo do template "foo/bar.html":

{% include "foo/bar.html" %}

Este exemplo incluí o conteúdo do template cujo o nome está contido na variável template_name:

{% include template_name %}

Um template incluído é renderizado com o contexto do template que o incluí. Este exemplo produz uma saída "Hello, John":

  • Context: variável person é setada para "john".

  • Template:

    {% include "name_snippet.html" %}
    
  • O template name_snippet.html:

    Hello, {{ person }}
    

Veja também: {% ssi %}.

load

Carrega um conjunto de tags de template customizadas.

Veja Bibliotecas de tags e filtros customizados para mais informações.

now

Mostra a data, formatada de acordo com a string dada.

Usa o mesmo formato da função date() do PHP (http://php.net/date) com algumas extensões customizadas.

Formatos de string disponíveis:

Caractere de formatação Descrição Exemplo de saída
a 'a.m.' ou 'p.m.' (Note que isso é um pouco diferente de uma saída do PHP, pois ela incluí períodos para corresponder ao estilo Associated Press.) 'a.m.'
A 'AM' ou 'PM'. 'AM'
b Mês, textual, 3 letras, em minúsculo. 'jan'
B Não implementado.  
d Dia do mês, 2 dígitos com zeros na frente '01' até '31'
D Dia da semana, textual 3 letras. 'Fri'
f Tempo, em 12-horas e minutos, os minutos não aparecem se forem zero. Extensão proprietária. '1', '1:30'
F Mẽs, textual, longo. 'January'
g Hora, formato 12-horas sem zero na frente zeros. '1' até '12'
G Hora, formato 24-horas sem zero na frente '0' até '23'
h Hora, formato 12-horas. '01' até '12'
H Hora, formato 24-horas. '00' até '23'
i Minutos. '00' até '59'
I Não implementado.  
j Dia do mês sem zero na frente. '1' até '31'
l Dia da semana, textual, longo. 'Friday'
L Boolean para saber se é um ano bissexto. True ou False
m Mês, 2 digitos com zero na frente. '01' até '12'
M Mês, textual, 3 letras. 'Jan'
n Mês sem zeros na frente. '1' até '12'
N Mês abreviação no estilo Associated Press Extensão proprietária. 'Jan.', 'Feb.', 'March', 'May'
O Diferença para Greenwich em horas. '+0200'
P Tempo, no formato 12-horas, minutos e 'a.m.'/'p.m.', sem os minutos se forem zero e em caso especial strings 'midnight' e 'noon' se for apropriado. Extensão proprietária. '1 a.m.', '1:30 p.m.', 'midnight', 'noon', '12:30 p.m.'
r Data formatada seguindo RFC 2822. 'Thu, 21 Dec 2000 16:01:07 +0200'
s Segundos, 2 digitos com zero na frente. '00' até '59'
S Sufixo ordinal inglês para dia do mês, 2 caracteres. 'st', 'nd', 'rd' or 'th'
t Numero de dias em um dado mês. 28 até 31
T Fuso-horário desta máquina. 'EST', 'MDT'
U Não implementado.  
w Dia da semana, digitos sem zeros na frente. '0' (Sunday) até '6' (Saturday)
W Número da semana do ano segundo o padrão ISO-8601 com semanas começando na Segunda-feira. 1, 53
y Ano, 2 digitos. '99'
Y Ano, 4 digitos. '1999'
z Dia do ano. 0 até 365
Z Compensação de fuso-horários em segundos. A compensação de fuso-horários a oeste de UTC é sempre negativa, e para aqueles que estão a leste é sempre positiva. -43200 até 43200

exemplo:

It is {% now "jS F Y H:i" %}

Note que você pode escapar uma string de formatação utilizando contra-barra (\), isso se você quiser usar um valor "cru". Neste exemplo, "f" é escapado com contra-barra, pois "f" é um formato que mostra o tempo.

It is the {% now "jS of F" %}

Isto geraria uma saída "It is the 4th of September".

regroup

Agrupar uma lista de objetos similares por um atributo comum.

Esta tag complexa é melhor ilustrada em uso num exemplo: digamos que people é uma lista de pessoas representadas em um dicionário com as chaves first_name, last_name, e gender:

people = [
    {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
    {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
    {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
    {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
    {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
]

...e você gostaria de mostrar uma lista hierarquica ordenada por gender, como esta:

  • Male:
    • George Bush
    • Bill Clinton
  • Female:
    • Margaret Thatcher
    • Condoleezza Rice
  • Unknown:
    • Pat Smith

Você pode usar a tag {% regroup %} para agrupar a lista de pessoas por gender. O fragmento de template poderia efetuar isto:

{% regroup people by gender as gender_list %}

<ul>
{% for gender in gender_list %}
    <li>{{ gender.grouper }}
    <ul>
        {% for item in gender.list %}
        <li>{{ item.first_name }} {{ item.last_name }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Vamos examinar este exemplo. {% regroup %} recebe três argumentos: a lista que você quer agrupar, o atributo ao qual será agrupado, e o nome da lista resultante. Aqui, nós estamos agrupando a lista de people pelo atributo gender e chmando o resultado de gender_list.

{% regroup %} produz uma lista (neste caso, gender_list) de objetos grupo. Cada objeto grupo possui dois atributos:

  • grouper -- o item que foi agrupado por (e.g., a string "Male" ou "Female").
  • list -- uma lista de todos os ítens deste grupo (e.g., uma lista de todos as pessoas com gender='Male').

Note que {% regroup %} não ordena sua entrada! Nosso exemplo se basea no fato de que a lista people foi ordenada por gender, em primeiro lugar. Se a lista people não foi ordenada por gender, o agrupamento poderia ingenuamente gerar uma lista com mais de um grupo com um único gender. Por exemplo, digamos que a lista people foi setada desta forma (note que os males não foram agrupados):

people = [
    {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
    {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
    {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
    {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
    {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
]

Com esta entrada para people, o exemplo de código de template {% regroup %} acima, poderia resultar na seguinte saída:

  • Male:
    • Bill Clinton
  • Unknown:
    • Pat Smith
  • Female:
    • Margaret Thatcher
  • Male:
    • George Bush
  • Female:
    • Condoleezza Rice

A solução mais fácil para este problema é ter certeza de que seu código no view ordenou a data de acordo com o que você deseja exibir.

Outra solução é classificar os dados no template usando o filtro dictsort, se seus dados estão em um dicionário:

{% regroup people|dictsort:"gender" by gender as gender_list %}

spaceless

Remove espaços em branco entre tags HTML. Isto incluí tabs e novas linhas.

exemplo de uso:

{% spaceless %}
    <p>
        <a href="foo/">Foo</a>
    </p>
{% endspaceless %}

Este exemplo poderia retornar este HTML:

<p><a href="foo/">Foo</a></p>

Somente espaços entre tags são removidos -- não espaços entre tags e textos. Neste exemplo, o espaço ao redor de Hello não foi removido:

{% spaceless %}
    <strong>
        Hello
    </strong>
{% endspaceless %}

ssi

Mostra os conteúdos de um dado arquivo dentro da página.

Como uma simples tag "include", {% ssi %} incluí o conteúdo de outro arquivo -- que devem ser especificados usando um caminho absoluto -- na página atual:

{% ssi /home/html/ljworld.com/includes/right_generic.html %}

Se o parâmetro opcional "parsed" for informado, o conteúdo do arquivo incluído será validado como código de template, dentro do contexto atual:

{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}

Note que se você usar {% ssi %}, você precisará definir ALLOWED_INCLUDE_ROOTS nas suas configurações do Django, como uma medida de segurança.

Veja também: {% include %}.

templatetag

Mostra um dos caracteres de sintaxe usados para compor tags de template.

Uma vez que o sistema de template não tem nenhum conceito de "escape", para mostrar um pouco do que está em uso nas tags de template, você deve usar a tag {% templatetag %}.

O argumento diz qual parte do template deve ser mostrado:

Argumento Saídas
openblock {%
closeblock %}
openvariable {{
closevariable }}
openbrace {
closebrace }
opencomment {#
closecomment #}

url

Retorna uma URL absoluta (i.e, uma URL sem o nome do domínio) combinando uma certa função view e parametros opcionais. Esta é uma forma de gerar links sem violar os principios do DRY, ao escrever na mão as URLs nos seus templates:

{% url path.to.some_view arg1,arg2,name1=value1 %}

O primeiro argumento é um caminho para uma função view no formato package.package.module.function. Argumentos adicionais são opcionais e devem ser separados por vírgula, pois serão usados como argumentos posicionais e nomeados na URL. Todos os argumentos obrigatórios pelo URLConf devem estar presentes.

Por exemplo, suponha que voce tem um view, app_views.client, cujo URLConf recebe um client ID (aqui, client() é um método dentro do arquivo view app_views.py). A linha do URLConf pode parecer com isso:

('^client/(\d+)/$', 'app_views.client')

Se o URLConf desta applicação está incluido no URLConf do projeto com um caminho como este:

('^clients/', include('project_name.app_name.urls'))

...então, em um template, você pode criar um link para este view desta forma:

{% url app_views.client client.id %}

A tag do template gerará uma string /clients/client/123/.

Novo no Django 1.0.

Se você está usando padrões de URL nomeados, você pode referenciar o nome do padrão na tag url ao invés de usar o caminho do view.

Note que se a URL que você está revertendo não existe, você irá receber uma exceção NoReverseMatch, que fará seu site mostrar uma página de erro.

Novo no Django 1.0.

Se você gostaria de receber uma URL sem mostrá-la, você pode usar uma chamada ligeiramente diferente:

{% url path.to.view arg, arg2 as the_url %}

<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>

Esta sintaxe {% url ... as var %} não causará um erro se o view não existir. Na pratica você usará isto para linkar views que são opcionais:

{% url path.to.view as the_url %}
{% if the_url %}
  <a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}

widthratio

Para criar barras de gráficos e tal, esta tag calcula a razão entre um dado valor e o máximo valor, e então aplica esta proporção a uma constante.

Por exemplo:

<img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />

Acima, se this_value é 175 e max_value é 200, a imagem do exemplo acima terá 88 pixels de largura (porque 175/200 = .875; .875 * 100 = 87.5 que é arredondado para cima, 88).

with

Novo no Django 1.0.

Cacheia uma variável complexa sob um simples nome. Isto é usual quando se acessa um método muito "custoso" (e.g, um que consulta o banco de dados) múltiplas vezes.

Por exemplo:

{% with business.employees.count as total %}
    {{ total }} employee{{ total|pluralize }}
{% endwith %}

A variável populada (do exemplo acima, total) somente está disponível entre as tags {% with %} e {% endwith %}.

Referência de filtros embutidos

add

Adiciona o argumento ao valor.

Por exemplo:

{{ value|add:"2" }}

Se value é 4, então a saída será 6.

addslashes

Adiciona barras antes das aspas. Usual para escapar strings em CSV, por exemplo.

capfirst

Torna a primeira letra do valor maiúscula.

center

Centraliza o valor no campo conforme uma dada largura.

cut

Remove todos os valores do argumento de uma dada string.

Por exemplo:

{{ value|cut:" "}}

Se value é "String with spaces", a saída será "Stringwithspaces".

date

Formata a data de acordo com o formato dado (o mesmo que a tag now).

Por exemplo:

{{ value|date:"D d M Y" }}

Se value é um objeto datetime (e.g., o resultado de datetime.datetime.now()), a saída será a string 'Wed 09 Jan 2008'.

Quando usado sem uma string de formatação:

{{ value|date }}

...a string de formatação definida na configuração DATE_FORMAT será utilizada.

default

Se o valor é False, usa o dado padrão, Do contrário, usa o valor.

Por exemplo:

{{ value|default:"nothing" }}

Se value é "" (uma string vazia), a saída será nothing.

default_if_none

Se (e somente se) o valor for None, use o dado padrão. Do contrário, use o valor.

Note que se uma string vazia for passada, o valor padrão não será usado. Use o filtro default se você quiser suportar strings vazias.

Por exemplo:

{{ value|default_if_none:"nothing" }}

Se value é None, a saída será a string "nothing".

dictsort

Recebe uma lista de dicionários e retorna a lista ordenada por uma chave forncecida no argumento.

Por exemplo:

{{ value|dictsort:"name" }}

Se value é:

[
    {'name': 'zed', 'age': 19},
    {'name': 'amy', 'age': 22},
    {'name': 'joe', 'age': 31},
]

então a saída poderia ser:

[
    {'name': 'amy', 'age': 22},
    {'name': 'joe', 'age': 31},
    {'name': 'zed', 'age': 19},
]

dictsortreversed

Recebe uma lista de dicionários e retorna uma lista ordenada reversamente, por uma chave fornecida em um argumento. Este funciona exatamente igual ao filtro acima, mas o valor retornado será na ordem contrária.

divisibleby

Retorna True se o valor é divisível por um argumento.

Por exemplo:

{{ value|divisibleby:"3" }}

Se value é 21, a saída poderia ser True.

escape

Escapa strings HTML. Especificamente, fazendo substituições:

  • < é convertido para &lt;
  • > é convertido para &gt;
  • ' (aspas simples) é convertido para &#39;
  • " (aspas duplas) é convertido para &quot;
  • & é convertido para &amp;

O escape é somente aplicado quando a string é exibida, então não importa onde, dentro de uma sequência encadeada de filtros, você coloca escape: ele sempre será aplicado como se fosse o último filtro. Se você deseja que o escape seja aplicado imediatamente, use o filtro force_escape.

Aplicando escape para uma variável que normalmente teria aplicado um auto-escaping no seu conteúdo, somente resultará em uma rodada de escape a ser feita. Então é seguro usar esta função mesmo em ambientes que possuem escape automático. Se você deseja multiplicar os passes do escape a serem aplicados, use o filtro force_escape.

Alterado no Django 1.0: Devido ao auto-escape, o comportamento deste filtro foi ligeiramente mudado. As substituições são feitas somente uma vez, depois de todos os outros filtros -- incluíndo os filtros antes e depois dele.

escapejs

Novo no Django 1.0.

Escapa caracteres para uso em strings de JavaScript. Ele não cria a string pronta para usar em HTML, mas proteje você de erros de sintaxe quando são usados templates para gerar JavaScript/JSON.

filesizeformat

Formata o valor como um tamanho de arquivo 'legível por humanos' (i.e. '13 KB', '4.1 MB', '102 bytes', etc).

Por exemplo:

{{ value|filesizeformat }}

Se value é 123456789, a saída poderia ser 117.7 MB.

first

Retorna o primeiro item de uma lista.

Por exemplo:

{{ value|first }}

Se value é a lista ['a', 'b', 'c'], a saída será 'a'.

fix_ampersands

Alterado no Django 1.0: Este raramente é útil pois comerciais (&) são automaticamente escapados agora. Veja escape para mais informações.

Substitui comecial (&) pela entidade &amp;.

Por exemplo:

{{ value|fix_ampersands }}

Se value é Tom & Jerry, a saída será Tom &amp; Jerry.

floatformat

Quando usado sem um argumento, arredonda um número em ponto flutuante para uma casa decimal -- mas somente se houver uma parte decimal para ser mostrada. Por exemplo:

value Template Saída
34.23234 {{ value|floatformat }} 34.2
34.00000 {{ value|floatformat }} 34
34.26000 {{ value|floatformat }} 34.3

Se usado com um argumento numérico inteiro, floatformat arredonda um número para várias casas decimais. Por exemplo:

value Template Saída
34.23234 {{ value|floatformat:3 }} 34.232
34.00000 {{ value|floatformat:3 }} 34.000
34.26000 {{ value|floatformat:3 }} 34.260

Se o argumento passado para floatformat é negativo, ele irá arredondar o número para muitas casas decimais -- mas comente se houver uma parte decimal a ser mostrada. Por exemplo:

value Template Saída
34.23234 {{ value|floatformat:"-3" }} 34.232
34.00000 {{ value|floatformat:"-3" }} 34
34.26000 {{ value|floatformat:"-3" }} 34.260

Usando floatformat sem argumento é equivalente a usar floatformat com um argumento -1.

force_escape

Novo no Django 1.0.

Escapa o HTML para uma string (veja o filtro escape para detalhes). Este filtro é aplicado imediatamente e retorna uma nova, string escapada. Ele é usual em raros casos onde você precisa dar múltiplos escapes ou quer aplicar outros filtros sobre resultados escapados. Normalmente, você quer usar o filtro escape.

get_digit

Dado um número inteiro, retorna o dígito requisitado, onde 1 é o dígito mais a direita, 2 é o segundo mais a direita, etc. Retorna o valor original no caso de entradas inválidas (se a entrada ou argumento não for um inteiro, ou se o argumento é menor que 1). Todo caso, a saída será sempre um inteiro.

Por exemplo:

{{ value|get_digit:"2" }}

Se value é 123456789, a saída será 8.

iriencode

Converte uma IRI (Internationalized Resource Identifier) para uma string que é adequada para uma URL. Isto é necessário se você está tentando usar strings que possuem caracteres não ASCII na URL.

É seguro usar este filtro em uma string que também passou pelo filtro urlencode.

join

Junta uma lista em uma string, como o str.join(list) do Python.

Por exemplo:

{{ value|join:" // " }}

Se value é a lista ['a', 'b', 'c'], a saída será a string "a // b // c".

last

Novo no Django 1.0.

Retorna o último item de uma lista.

Por exemplo:

{{ value|last }}

Se value é a lista ['a', 'b', 'c', 'd'], a saída será a string "d".

length

Retorna o comprimento de um valor. Ela funciona para ambos strings e listas.

Por exemplo:

{{ value|length }}

Se value é ['a', 'b', 'c', 'd'], a saída será 4.

length_is

Retorna True se o valor do comprimento é o argumento, ou False caso contrário.

Por exemplo:

{{ value|length_is:"4" }}

Se value é ['a', 'b', 'c', 'd'], a saída será True.

linebreaks

Substitui quebras de linha em textos planos pelo HTML apropriado; uma simples quebra de linha se torna uma quebra de linha do HTML (<br />) e uma nova linha seguida por uma linha em branco ser tornará uma parágrafo (</p>).

Por exemplo:

{{ value|linebreaks }}

Se value é Joel\nis a slug, a saída será <p>Joel<br />is a slug</p>.

linebreaksbr

Converte todas as novas linhas em uma amostra de texto plano para quebras de linhas HTML (<br />).

linenumbers

Mostra o texto com número de linhas.

ljust

Alinha a esquerda o valor no campo de uma dada largura.

Argumento: tamanho do campo

lower

Converte uma string em minúsculo.

Por exemplo:

{{ value|lower }}

Se value é Still MAD At Yoko, a saída será still mad at yoko.

make_list

Retorna o valor em uma lista. Para um inteiro, será uma lista de dígitos. Para uma string, será uma lista de caracteres.

Por exemplo:

{{ value|make_list }}

Se value é a string "Joel", a saída poderá ser a lista [u'J', u'o', u'e', u'l']. Se value é 123, a saída será a lista [1, 2, 3].

phone2numeric

Converte um número telefonico (possivelmente contentendo letras) para seu numeral equivalente. Por exemplo, '800-COLLECT' será convertido para '800-2655328'.

A entrada não tem de ser um número de telefone válido. Isto irá converter alegremente qualquer sequência.

pluralize

Retorna o sufixo plural se o valor não é 1. Por padrão, este sufixo é 's'.

Exemplo:

You have {{ num_messages }} message{{ num_messages|pluralize }}.

Para palavras que requerem um outro sufixo que não 's', você pode prover um sufixo alternativo como um paramêtro para o filtro.

Exemplo:

You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}.

Para palavras que não são pluralizadas por sufixos simples, você pode especificar ambos sufixos, singular e plural, separados por virgula.

Exemplo:

You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.

pprint

Um contorno para pprint.pprint -- para debugging, realmente.

random

Retorna um item randômico de uma lista.

Por exemplo:

{{ value|random }}

Se value é a lista ['a', 'b', 'c', 'd'], a saída poderá ser "b".

removetags

Remove uma lista de tags [X]HTML separadas por espaços da saída.

Por exemplo:

{{ value|removetags:"b span"|safe }}

Se value é "<b>Joel</b> <button>is</button> a <span>slug</span>" a saída será "Joel <button>is</button> a slug".

rjust

Alinha a direita o valor no campo de uma dada largura.

Argumento: tamanho do campo

safe

Marca uma string que não exige escape de HTML antes da saída. Quando autoscaping está desligado, este filtro não surte efeito.

slice

Retorna um pedaço da lista.

Usa a mesma sintaxe do fatiamento de listas do Python. Veja http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice para uma introdução

Exemplo:

{{ some_list|slice:":2" }}

slugify

Converts to lowercase, removes non-word characters (alphanumerics and underscores) and converts spaces to hyphens. Also strips leading and trailing whitespace.

Por exemplo:

{{ value|slugify }}

Se value é "Joel is a slug", a saída será "joel-is-a-slug".

stringformat

Formata a variável de acordo com o argumento, um especificador de formatação de strings. Este especificador usa a sintaxe de formatação de strings do Python, com a exceção de não usar o guia "%".

Veja See http://docs.python.org/library/stdtypes.html#string-formatting-operations para documentação de formatação de strings do Python.

Por exemplo:

{{ value|stringformat:"s" }}

Se value é "Joel is a slug", a saída será "Joel is a slug".

striptags

Mostra todas as tags [X]HTML.

Por exemplo:

{{ value|striptags }}

Se value é "<b>Joel</b> <button>is</button> a <span>slug</span>", a saída será "Joel is a slug".

time

Formata um tempo de acordo com o formato dado (o mesmo que a tag now). O filtro time somente aceitará paramêtros no formato de string relacionados a hora do dia, não a data (por razões obvias). Se vocÊ precisa formatar uma data, use o filtro date.

Por exemplo:

{{ value|time:"H:i" }}

Se value é equivalente a datetime.datetime.now(), a saída será a string "01:23".

When used without a format string:

{{ value|time }}

...the formatting string defined in the TIME_FORMAT setting will be used.

timesince

Formata a data como o tempo desde essa data (e.g., "4 days, 6 hours").

Recebe um argumento opcional que é uma variável contento a data para ser usada como ponto de comparação (sem o argumento, o ponto de comparação é now). Por exemplo, se blog_date é uma instancia de date reprensentando meia-noite em 1 de Junho de 2006, e comment_date é uma instancia de date para 08:00 em 1 Junho de 2006, então {{ blog_date|timesince:comment_date }} retornaria "8 hours".

Comparando datetimes offset-naive e offset-ware irão retornar uma string vazia.

Minutos é a menor unidade usada, e "0 minutes" será retornado por qualquer date que está num futuro relativo ao ponto de comparação.

timeuntil

Similar ao timesince, exceto que ele mede o tempo de agora até a data ou datetime dada. Por exemplo, se hoje é 1 June 2006 e conference_date é uma instância de date marcando 29 June 2006, então {{ conference_date|timeuntil}} retornará "4 semanas".

Recebe um argumento opcional que é uma variável contendo a data a ser usada como o ponto de comparação (ao invés de now). Se from_date contém 22 June 2006, então {{ conference_date|timeuntil:from_date }} retornará "1 week".

Comparing offset-naive and offset-aware datetimes will return an empty string.

Minutos são a menor unidade usada, e "0 minutos" será retornado por qualquer data que estiver num passado relativo ao ponto de comparação.

title

Converte uma string em titlecase.

truncatewords

Trunca uma string depois de um certo número de palavras.

Argumento: Número de palavras para trucar depois.

Por exemplo:

{{ value|truncatewords:2 }}

Se value é "Joel is a slug", a saída será "Joel is ...".

truncatewords_html

Semelhante ao truncatewords, exceto que ele se preocupa com as tags HTML. Qualquer tag que estiver aberta na string, e não foi fechada antes do ponto de corte, serão fechadas imediatamente após o truncament.

Isto é menos eficiente que truncatewords, então deve ser usado somente quando estiver sendo passado textos HTML.

unordered_list

Recursivamente recebe uma lista auto-aninhada e retorna uma lista HTML não-ordenada -- SEM abrir e fechar tags <ul>.

Alterado no Django 1.0: O formato aceito por unordered_list mudou para facilitar o entendimento.

A lista é para ser assumida no formato correto. Por exemplo, se var contém ['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']], então {{ var|unordered_list }} retornaria:

<li>States
<ul>
        <li>Kansas
        <ul>
                <li>Lawrence</li>
                <li>Topeka</li>
        </ul>
        </li>
        <li>Illinois</li>
</ul>
</li>

Nota: o formato anterior mais restritivo e verboso ainda é suportado: ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]],

upper

Converte uma string em maiúsculo.

Por exemplo:

{{ value|upper }}

Se value é "Joel is a slug", a saída será "JOEL IS A SLUG".

urlencode

Escapa um valor para ser usado em uma URL.

urlize

Converte URLs em texto plano dentro de links clicáveis.

Note que se urlize é aplicado em um texto que já contém marcação HTML, as coisas não irão funcionar como esperado. Aplique este filtro somente no texto plano.

Por exemplo:

{{ value|urlize }}

Se value é "Check out www.djangoproject.com", a saída será "Check out <a href="http://www.djangoproject.com">www.djangoproject.com</a>".

urlizetrunc

Converte URLs dentro de links clicáveis, truncando URLs mais longas que um determinado limite de caracteres.

Como em urlize, este filtro deve ser somente aplicado em texto plano.

Argumento: Comprimento que as URLs devem ter

Por exemplo:

{{ value|urlizetrunc:15 }}

Se value é "Check out www.djangoproject.com", a saída seria 'Check out <a href="http://www.djangoproject.com">www.djangopr...</a>'.

wordcount

Retorna o número de palavras.

wordwrap

Quebra palavras em um comprimento de linha específico.

Argumento: número de caracteres em que ocorrerá a quebra do texto

Por exemplo:

{{ value|wordwrap:5 }}

Se value é Joel is a slug, a saída seria:

Joel
is a
slug

yesno

Dada uma string de mapeamento de valores true, false e (opcionalmente) None, retorna uma destas strings, de acordo com o valor:

Valor Argumento Saída
True "yeah,no,maybe" yeah
False "yeah,no,maybe" no
None "yeah,no,maybe" maybe
None "yeah,no" "no" (converte None para False se nenhum mapeamento para None for dado)

Outras bibliotecas de tags e filtros

O Django vem com algumas outras bibliotecas de tags de templates, que você tem de habilitar explicitamente em seu INSTALLED_APPS e habilitar em seu template com a tag {% load %}.

django.contrib.humanize

Um conjunto de filtros de templates Django usuais para adicionar um "toque humano" aos dados. Veja django.contrib.humanize.

django.contrib.markup

Uma coleção de filtros de templates que implementam estas linguagens de marcação comuns:

  • Textile
  • Markdown
  • ReST (ReStructured Text)

Veja markup.

django.contrib.webdesign

Uma coleção de tags de template que podem ser úteis quando se faz o design de um website, como um gerador de texto Lorem Ipsum. Veja django.contrib.webdesign.