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.
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.
Sample usage:
{% autoescape on %}
{{ body }}
{% endautoescape %}
Define um bloco que pode ser sobrescrito por um template filho. Veja Herança de template para mais informações.
Ignora tudo entre dois {% comment %} e {% endcomment %}
In the Django 1.1.X series, this is a no-op tag that returns an empty string for future compatibility purposes. In Django 1.2 and later, it is used for CSRF protection, as described in the documentation for Cross Site Request Forgeries.
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 %}
From then on, you can insert the current value of the cycle wherever you'd like in your template by referencing the cycle name as a context variable. If you want to move the cycle onto the next value, you use the cycle tag again, using the name of the variable. So, the following template:
<tr>
<td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
<tr>
<td class="{% cycle rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
would output:
<tr>
<td class="row1">...</td>
<td class="row1">...</td>
</tr>
<tr>
<td class="row2">...</td>
<td class="row2">...</td>
</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. Any HTML or Javascript code contained in the printed variable will be rendered as-is, which could potentially lead to security issues.
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 mencionamos que você não deve usar esta sintaxe em nenhum novo projeto?
By default, when you use the as keyword with the cycle tag, the usage of {% cycle %} that declares the cycle will itself output the first value in the cycle. This could be a problem if you want to use the value in a nested loop or an included template. If you want to just declare the cycle, but not output the first value, you can add a silent keyword as the last keyword in the tag. For example:
{% for obj in some_list %}
{% cycle 'row1' 'row2' as rowcolors silent %}
<tr class="{{ rowcolors }}">{% include "subtemplate.html " %}</tr>
{% endfor %}
This will output a list of <tr> elements with class alternating between row1 and row2; the subtemplate will have access to rowcolors in it's context that matches the class of the <tr> that encloses it. If the silent keyword were to be omitted, row1 would be emitted as normal text, outside the <tr> element.
When the silent keyword is used on a cycle definition, the silence automatically applies to all subsequent uses of the cycle tag. In, the following template would output nothing, even though the second call to {% cycle %} doesn't specify silent:
{% cycle 'row1' 'row2' as rowcolors silent %}
{% cycle rowcolors %}
Mostra todas as informações carregadas de debug, incluindo o contexto atual e os módulos importados.
Sinal que este template extende um template pai.
Esta tag pode ser usada de duas formas:
Veja Herança de template para mais informações.
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 %}
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 %}
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 |
The for tag can take an optional {% empty %} clause that will be displayed if the given array is empty or could not be found:
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% empty %}
<li>Sorry, no athlete in this list!</li>
{% endfor %}
<ul>
The above is equivalent to -- but shorter, cleaner, and possibly faster than -- the following:
<ul>
{% if athlete_list %}
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
{% else %}
<li>Sorry, no athletes in this list.</li>
{% endif %}
</ul>
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 %}
Existem alguns atletas e absolutamente nenhum treinador.
{% endif %}
Use of both and and or clauses within the same tag is allowed, with and having higher precedence than or e.g.:
{% if athlete_list and coach_list or cheerleader_list %}
will be interpreted like:
if (athlete_list and coach_list) or cheerleader_list
Use of actual brackets in the if tag is invalid syntax. If you need them to indicate precedence, you should use nested if tags.
if tags may also use the operators ==, !=, <, >, <=, >= and in which work as follows:
Equality. Example:
{% if somevar == "x" %}
This appears if variable somevar equals the string "x"
{% endif %}
Inequality. Example:
{% if somevar != "x" %}
This appears if variable somevar does not equal the string "x",
or if somevar is not found in the context
{% endif %}
Less than. Example:
{% if somevar < 100 %}
This appears if variable somevar is less than 100.
{% endif %}
Greater than. Example:
{% if somevar > 0 %}
This appears if variable somevar is greater than 0.
{% endif %}
Less than or equal to. Example:
{% if somevar <= 100 %}
This appears if variable somevar is less than 100 or equal to 100.
{% endif %}
Greater than or equal to. Example:
{% if somevar >= 1 %}
This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}
Contained within. This operator is supported by many Python containers to test whether the given value is in the container. The following are some examples of how x in y will be interpreted:
{% if "bc" in "abcdef" %}
This appears since "bc" is a substring of "abcdef"
{% endif %}
{% if "hello" in greetings %}
If greetings is a list or set, one element of which is the string
"hello", this will appear.
{% endif %}
{% if user in users %}
If users is a QuerySet, this will appear if user is an
instance that belongs to the QuerySet.
{% endif %}
Not contained within. This is the negation of the in operator.
The comparison operators cannot be 'chained' like in Python or in mathematical notation. For example, instead of using:
{% if a > b > c %} (WRONG)
you should use:
{% if a > b and b > c %}
You can also use filters in the if expression. For example:
{% if messages|length >= 100 %}
You have lots of messages today!
{% endif %}
All of the above can be combined to form complex expressions. For such expressions, it can be important to know how the operators are grouped when the expression is evaluated - that is, the precedence rules. The precedence of the operators, from lowest to highest, is as follows:
(This follows Python exactly). So, for example, the following complex if tag:
{% if a == b or c == d and e %}
...will be interpreted as:
(a == b) or ((c == d) and e)
If you need different precedence, you will need to use nested if tags. Sometimes that is better for clarity anyway, for the sake of those who do not know the precedence rules.
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>
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.
Exatamente como ifequal, exceto que testa se os dois argumentos não são iguais.
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:
{{ greeting }}, {{ person|default:"friend" }}!
You can pass additional context to the template using keyword arguments:
{% include "name_snippet.html" with person="Jane" greeting="Hello" %}
If you want to only render the context with the variables provided (or even no variables at all), use the only option:
{% include "name_snippet.html" with greeting="Hi" only %}
Note
The include tag should be considered as an implementation of "render this subtemplate and include the HTML", not as "parse this subtemplate and include its contents as if it were part of the parent". This means that there is no shared state between included templates -- each include is a completely independent rendering process.
Veja também: {% ssi %}.
Carrega um conjunto de tags de template customizadas.
For example, the following template would load all the tags and filters registered in somelibrary and otherlibrary:
{% load somelibrary otherlibrary %}
You can also selectively load individual filters or tags from a library, using the from argument. In this example, the template tags/filters named foo and bar will be loaded from somelibrary:
{% load foo bar from somelibrary %}
Veja Bibliotecas de tags e filtros customizados para mais informações.
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".
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:
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:
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:
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 %}
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 %}
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 %}.
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 | #} |
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 %}
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).
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 %}.
Adiciona o argumento ao valor.
Por exemplo:
{{ value|add:"2" }}
Se value é 4, então a saída será 6.
Adiciona barras antes das aspas. Usual para escapar strings em CSV, por exemplo.
Torna a primeira letra do valor maiúscula.
Centraliza o valor no campo conforme uma dada largura.
Remove todos os valores do argumento de uma dada string.
Por exemplo:
{{ value|cut:" "}}
Se value é "String with spaces", a saída será "Stringwithspaces".
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.
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.
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".
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},
]
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.
Retorna True se o valor é divisível por um argumento.
Por exemplo:
{{ value|divisibleby:"3" }}
Se value é 21, a saída poderia ser True.
Escapa strings HTML. Especificamente, fazendo substituições:
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.
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.
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.
Retorna o primeiro item de uma lista.
Por exemplo:
{{ value|first }}
Se value é a lista ['a', 'b', 'c'], a saída será 'a'.
Substitui comecial (&) pela entidade &.
Por exemplo:
{{ value|fix_ampersands }}
Se value é Tom & Jerry, a saída será Tom & Jerry.
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.
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.
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.
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.
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".
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".
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.
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.
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>.
Converte todas as novas linhas em uma amostra de texto plano para quebras de linhas HTML (<br />).
Mostra o texto com número de linhas.
Converte uma string em minúsculo.
Por exemplo:
{{ value|lower }}
Se value é Still MAD At Yoko, a saída será still mad at yoko.
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].
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.
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" }}.
Um contorno para pprint.pprint -- para debugging, realmente.
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".
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".
Marca uma string que não exige escape de HTML antes da saída. Quando autoscaping está desligado, este filtro não surte efeito.
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" }}
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".
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".
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".
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.
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.
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.
Converte uma string em titlecase.
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 ...".
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.
Recursivamente recebe uma lista auto-aninhada e retorna uma lista HTML não-ordenada -- SEM abrir e fechar tags <ul>.
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', []]]],
Converte uma string em maiúsculo.
Por exemplo:
{{ value|upper }}
Se value é "Joel is a slug", a saída será "JOEL IS A SLUG".
Escapa um valor para ser usado em uma URL.
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>".
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>'.
Retorna o número de palavras.
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
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) |
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 %}.
Um conjunto de filtros de templates Django usuais para adicionar um "toque humano" aos dados. Veja django.contrib.humanize.
Uma coleção de filtros de templates que implementam estas linguagens de marcação comuns:
Veja django.contrib.markup.
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.
Dec 26, 2011