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¶
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¶
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 davariable
. Se a variável é uma string, o Django irá usá-la como o nome do template pai. Se a variável for um objetoTemplate
, 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 %}
.
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.
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 %}
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/
.
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.
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¶
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<
>
é convertido para>
'
(aspas simples) é convertido para'
"
(aspas duplas) é convertido para"
&
é convertido para&
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
.
escapejs¶
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¶
Substitui comecial (&) pela entidade &
.
Por exemplo:
{{ value|fix_ampersands }}
Se value
é Tom & Jerry
, a saída será Tom & 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¶
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¶
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.
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"
.
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>.
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.