.. .. META INFORMATION OF TRANSLATION .. .. $TranslationStatus: Done, waiting for revision $ .. $OriginalRevision: 11348 $ .. $TranslationAuthors: Robson Mendonça $ .. .. INFO OF THIS FILE (DO NOT EDIT! UPDATED BY SUBVERSION) .. .. $HeadURL: http://django-l10n-portuguese.googlecode.com/svn/branches/docs-1.0.X/ref/templates/builtins.txt $ .. $LastChangedRevision: 517 $ .. $LastChangedBy: robsonmwoc $ .. $LastChangedDate: 2009-08-01 23:09:26 -0300 (Sat, 01 Aug 2009) $ .. .. _ref-templates-builtins: =============================================== Tags e filtros de template embutidos (Built-in) =============================================== Este documento descreve as tags e filtros de templates embutidos do Django. É recomendado o uso da :ref:`documentação automática `, se disponível, que irá incluir a documentação de qualquer tag ou filtro personalizado instalado. .. _ref-templates-builtins-tags: Referência de tags nativas -------------------------- .. highlightlang:: html+django .. templatetag:: autoescape autoescape ~~~~~~~~~~ .. versionadded:: 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. .. templatetag:: block block ~~~~~ Define um bloco que pode ser sobrescrito por um template filho. Veja :ref:`Herança de template ` para mais informações. .. templatetag:: comment comment ~~~~~~~ Ignora tudo entre dois ``{% comment %}`` e ``{% endcomment %}`` .. templatetag:: cycle cycle ~~~~~ .. versionchanged:: 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 %} ... {% 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 %} ... {% endfor %} Sim, você pode mesclar variáveis e strings:: {% for o in some_list %} ... {% 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:: ... ... 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? .. templatetag:: debug debug ~~~~~ Mostra todas as informações carregadas de debug, incluindo o contexto atual e os módulos importados. .. templatetag:: extends 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 :ref:`template-inheritance` para mais informações. .. templatetag:: filter 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 %} .. templatetag:: firstof 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 %} .. templatetag:: for for ~~~ Faz um loop sobre cada item de um array. Por exemplo, para mostrar uma lista de atletas vindos de ``athlete_list``:: Você pode iterar a lista ao contrário usando ``{% for obj in list reversed %}``. .. versionadded:: 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 ========================== ================================================ .. templatetag:: if 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 %} .. templatetag:: ifchanged 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::

Archive for {{ year }}

{% for date in days %} {% ifchanged %}

{{ date|date:"F" }}

{% endifchanged %} {{ date|date:"j" }} {% 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 %}
{{ match }}
.. templatetag:: ifequal 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``. .. templatetag:: ifnotequal ifnotequal ~~~~~~~~~~ Exatamente como ``ifequal``, exceto que testa se os dois argumentos não são iguais. .. templatetag:: include 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 %}``. .. templatetag:: load load ~~~~ Carrega um conjunto de tags de template customizadas. Veja :ref:`Bibliotecas de tags e filtros customizados ` para mais informações. .. templatetag:: now 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 ``'a.m.'`` é um pouco diferente de uma saída do PHP, pois ela incluí períodos para corresponder ao estilo Associated Press.) 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 ``'1'``, ``'1:30'`` não aparecem se forem zero. Extensão proprietária. F Mẽs, textual, longo. ``'January'`` g Hora, formato 12-horas sem zero na frente ``'1'`` até ``'12'`` zeros. 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 ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` Extensão proprietária. O Diferença para Greenwich em horas. ``'+0200'`` P Tempo, no formato 12-horas, minutos e ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` '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. 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, ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` 2 caracteres. 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 ``'0'`` (Sunday) até ``'6'`` (Saturday) frente. W Número da semana do ano segundo o padrão ``1``, ``53`` ISO-8601 com semanas começando na Segunda-feira. 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. ``-43200`` até ``43200`` A compensação de fuso-horários a oeste de UTC é sempre negativa, e para aqueles que estão a leste é sempre positiva. ======================= ========================================== ===================== 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 o\f F" %} Isto geraria uma saída "It is the 4th of September". .. templatetag:: regroup 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``: .. code-block:: python 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 %}
    {% for gender in gender_list %}
  • {{ gender.grouper }}
      {% for item in gender.list %}
    • {{ item.first_name }} {{ item.last_name }}
      • {% endfor %}
    • {% endfor %}
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): .. code-block:: python 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 %} .. templatetag:: spaceless spaceless ~~~~~~~~~ Remove espaços em branco entre tags HTML. Isto incluí tabs e novas linhas. exemplo de uso:: {% spaceless %}

Foo

{% endspaceless %} Este exemplo poderia retornar este HTML::

Foo

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 %} Hello {% endspaceless %} .. templatetag:: ssi 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 :setting:`ALLOWED_INCLUDE_ROOTS` nas suas configurações do Django, como uma medida de segurança. Veja também: ``{% include %}``. .. templatetag:: templatetag 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`` ``#}`` ================== ======= .. templatetag:: url 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: .. code-block:: python ('^client/(\d+)/$', 'app_views.client') Se o URLConf desta applicação está incluido no URLConf do projeto com um caminho como este: .. code-block:: python ('^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/``. .. versionadded:: 1.0 Se você está usando :ref:`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 :exc:`NoReverseMatch`, que fará seu site mostrar uma página de erro. .. versionadded:: 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 %} I'm linking to {{ the_url }} 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 %} Link to optional stuff {% endif %} .. templatetag:: widthratio 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:: 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). .. templatetag:: with with ~~~~ .. versionadded:: 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 %}``. .. _ref-templates-builtins-filters: Referência de filtros embutidos ------------------------------- .. templatefilter:: add add ~~~ Adiciona o argumento ao valor. Por exemplo:: {{ value|add:"2" }} Se ``value`` é ``4``, então a saída será ``6``. .. templatefilter:: addslashes addslashes ~~~~~~~~~~ Adiciona barras antes das aspas. Usual para escapar strings em CSV, por exemplo. .. templatefilter:: capfirst capfirst ~~~~~~~~ Torna a primeira letra do valor maiúscula. .. templatefilter:: center center ~~~~~~ Centraliza o valor no campo conforme uma dada largura. .. templatefilter:: cut 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"``. .. templatefilter:: date 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 :setting:`DATE_FORMAT` será utilizada. .. templatefilter:: default 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``. .. templatefilter:: default_if_none 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"``. .. templatefilter:: dictsort 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`` é: .. code-block:: python [ {'name': 'zed', 'age': 19}, {'name': 'amy', 'age': 22}, {'name': 'joe', 'age': 31}, ] então a saída poderia ser: .. code-block:: python [ {'name': 'amy', 'age': 22}, {'name': 'joe', 'age': 31}, {'name': 'zed', 'age': 19}, ] .. templatefilter:: dictsortreversed 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. .. templatefilter:: divisibleby 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``. .. templatefilter:: escape 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``. .. versionchanged:: 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. .. templatefilter:: escapejs escapejs ~~~~~~~~ .. versionadded:: 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. .. templatefilter:: filesizeformat 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``. .. templatefilter:: first first ~~~~~ Retorna o primeiro item de uma lista. Por exemplo:: {{ value|first }} Se ``value`` é a lista ``['a', 'b', 'c']``, a saída será ``'a'``. .. templatefilter:: fix_ampersands fix_ampersands ~~~~~~~~~~~~~~ .. versionchanged:: 1.0 Este raramente é útil pois comerciais (*&*) são automaticamente escapados agora. Veja escape_ para mais informações. Substitui comecial (*&*) pela entidade ``&``. Por exemplo:: {{ value|fix_ampersands }} Se ``value`` é ``Tom & Jerry``, a saída será ``Tom & Jerry``. .. templatefilter:: floatformat 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``. .. templatefilter:: force_escape force_escape ~~~~~~~~~~~~ .. versionadded:: 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``. .. templatefilter:: get_digit 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``. .. templatefilter:: iriendcode 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``. .. templatefilter:: join 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"``. .. templatefilter:: last last ~~~~ .. versionadded:: 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"``. .. templatefilter:: length 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``. .. templatefilter:: length_is 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``. .. templatefilter:: linebreaks linebreaks ~~~~~~~~~~ Substitui quebras de linha em textos planos pelo HTML apropriado; uma simples quebra de linha se torna uma quebra de linha do HTML (``
``) e uma nova linha seguida por uma linha em branco ser tornará uma parágrafo (``

``). Por exemplo:: {{ value|linebreaks }} Se ``value`` é ``Joel\nis a slug``, a saída será ``

Joel
is a slug

``. .. templatefilter:: linebreaksbr linebreaksbr ~~~~~~~~~~~~ Converte todas as novas linhas em uma amostra de texto plano para quebras de linhas HTML (``
``). .. templatefilter:: linenumbers linenumbers ~~~~~~~~~~~ Mostra o texto com número de linhas. .. templatefilter:: ljust ljust ~~~~~ Alinha a esquerda o valor no campo de uma dada largura. **Argumento:** tamanho do campo .. templatefilter:: lower 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``. .. templatefilter:: make_list 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]``. .. templatefilter:: phone2numeric 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. .. templatefilter:: pluralize 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" }}. .. templatefilter:: pprint pprint ~~~~~~ Um contorno para `pprint.pprint`__ -- para debugging, realmente. __ http://docs.python.org/library/pprint.html .. templatefilter:: random 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"``. .. templatefilter:: removetags removetags ~~~~~~~~~~ Remove uma lista de tags [X]HTML separadas por espaços da saída. Por exemplo:: {{ value|removetags:"b span"|safe }} Se ``value`` é ``"Joel a slug"`` a saída será ``"Joel a slug"``. .. templatefilter:: rjust rjust ~~~~~ Alinha a direita o valor no campo de uma dada largura. **Argumento:** tamanho do campo .. templatefilter:: safe 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. .. templatefilter:: slice 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" }} .. templatefilter:: slugify 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"``. .. templatefilter:: stringformat 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"``. .. templatefilter:: striptags striptags ~~~~~~~~~ Mostra todas as tags [X]HTML. Por exemplo:: {{ value|striptags }} Se ``value`` é ``"Joel a slug"``, a saída será ``"Joel is a slug"``. .. templatefilter:: time 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 :setting:`TIME_FORMAT` setting will be used. .. templatefilter:: timesince 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. .. templatefilter:: timeuntil 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. .. templatefilter:: title title ~~~~~ Converte uma string em titlecase. .. templatefilter:: truncatewords 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 ..."``. .. templatefilter:: truncatewords_html 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. .. templatefilter:: unordered_list unordered_list ~~~~~~~~~~~~~~ Recursivamente recebe uma lista auto-aninhada e retorna uma lista HTML não-ordenada -- SEM abrir e fechar tags
    . .. versionchanged:: 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::
  • States
    • Kansas
      • Lawrence
      • Topeka
    • Illinois
    • Nota: o formato anterior mais restritivo e verboso ainda é suportado: ``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``, .. templatefilter:: upper 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"``. .. templatefilter:: urlencode urlencode ~~~~~~~~~ Escapa um valor para ser usado em uma URL. .. templatefilter:: urlize 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 www.djangoproject.com"``. .. templatefilter:: urlizetrunc 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 www.djangopr...'``. .. templatefilter:: wordcount wordcount ~~~~~~~~~ Retorna o número de palavras. .. templatefilter:: wordwrap 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 .. templatefilter:: yesno 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 :setting:`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 :ref:`ref-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 :ref:`ref-contrib-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 :ref:`ref-contrib-webdesign`.