{"title":"How to create custom template tags and filters","version":"4.2","locale":"pt-br","docname":"howto/custom-template-tags","url":"/pt-br/4.2/howto/custom-template-tags/","canonical":"https://djangodocs.dev/pt-br/4.2/howto/custom-template-tags/","summary":"A linguagem de templates do Django vem com uma variedade de built-in tags e filtros projetados para atender as necessidades da lógica de apresentação da sua…","html":"
A linguagem de templates do Django vem com uma variedade de built-in tags e filtros projetados para atender as necessidades da lógica de apresentação da sua aplicação. Mesmo assim, talvez precise de uma funcionalidade que não está coberta pelo conjunto das primitivas do template. É possível estender o engine de templates definindo tags e filtros customizados usando Python, e então torná-los disponíveis para seus templates usando a tag {% load %} .
O lugar mais comum para especificar tags e filtros customizados é dentro de uma app Django. Se eles estão relacionados a uma app existente, faz sentido empacotá-los ali; se não eles podem ser adicionados a uma nova app. Quando uma app Django é adicionada ao INSTALLED_APPS, qualquer tag que estiver definida em um local convencional descrito abaixo ficam automaticamente disponíveis para serem carregadas dentro dos templates.
\n
A app deve conter um diretório templatetags, no mesmo nível que o models.py`, ``views.py`, etc. Se este ainda não existe, crie - não esqueça o arquivo ``__init__.py para ter certeza que o diretório é tratado como um pacote Python.
\n\n
As tags e filtros personalizados irão ficar em um módulo dentro do diretório ``templatetags`. O nome do arquivo do módulo é o nome que será usado para carregar as tags mais tarde, então tenha cuidado em escolher um nome que não conflite com tags e filtros customizados de outras apps.
\n
For example, if your custom tags/filters are in a file called\npoll_extras.py, your app layout might look like this:
A app que contém a tag personalizada deve estar em INSTALLED_APPS para que a tag {% load %} funcione. Essa é uma característica de segurança: isso permite servir código Python para muitas bibliotecas de template em uma única máquina servidora sem habilitar acesso cada instalação de Django.
\n
Não há limites de quantos módulos são colocados dentro do pacote templatetags. Apenas mantenha em mente que um comando {% load %} irá carregar tags/filters para o nome do módulo Python, e não o nome da app.
\n
Para ser uma biblioteca de tags válida, o módulo deve conter uma variável do nível do módulo chamado register que é uma instância de template.Library, na qual todas as tags e filtros são registrados. Então, próximo ao topo do seu módulo, coloque o seguinte:
Um alternativa, é que módulos de tags de template podem ser registradas através do argumento 'libraries' do DjangoTemplates. Isso é útil se você quer um “label” diferente para o módulo da tag de quando carregar os templates. Isso também habilita o registro de tags sem instalar a aplicação.
Custom filters are Python functions that take one or two arguments:
\n
\n
O valor da variável (input - de entrada) – não necessariamente uma string.
\n
O valor do argumento – este pode ter um valor padrão, ou ser deixado de fora.
\n
\n
Por exemplo, no filtro {{ var|foo:"bar" }}, ao filtro foo seria passada a variável var e o argumento "bar".
\n
Uma vez que a linguagem de template não fornece manipulação de exceções, qualquer exceção vinda de um filtro de template será exposta como um erro de servidor. Sendo assim, funções de filtros devem evitar enviar exceções se houver um valor substituto razoável para retornar. No caso de uma entrada que representa claramente um bug em um template, enviar uma exceção talvez ainda seja melhor que uma falha silenciosa a qual esconde o bug.
\n
Aqui um exemplo de definição de filtro:
\n
Code
defcut(value, arg):\n """Removes all values of arg from the given string"""\n return value.replace(arg,"")\n
\n
E aqui um exemplo de como aquele filtro poderia ser usado:
\n
Django template
{{somevariable|cut:"0"}}\n
\n
Most filters don’t take arguments. In this case, leave the argument out of your\nfunction:
\n
Code
deflower(value):# Only one argument.\n """Converts a string into all lowercase"""\n return value.lower()\n
Uma vez que tenha escrito sua definição do filtro, é preciso registrá-lo com sua instância de Library, para fazer com que esteja disponível para a linguagem de template do Django.
Se deixar de passar o argumento name, como no segundo exemplo acima, o Django irá usar o nome da função como nome do filtro.
\n
Finalmente, register.filter() também aceita três argumentos nomeados, is_safe, needs_autoescape, e expects_localtime. Estes argumentos são descrito em filters and auto-escaping e filters and time zones abaixo.
Se você está escrevendo um filtro de template que somente aceita uma string como primeiro argumento, deveria usar o decorador stringfilter. Isso irá converter um objeto para seu valor string antes de ser passado pela sua função:
Desta maneira, você será capaz de passar, vamos dizer, um inteiro para este filtro, e isso não irá causar um AttributeError (porque inteiros não possuem os métodos lower()).
Quando estiver escrevendo um filtro customizado, reflita sobre como o filtro irá interagir com o comportamento de auto escape do Django. Note que dois tipos de cadeias de caracteres podem ser passados dentro do código do template.
\n
\n
Raw strings são as cadeias de caracteres nativas do Python. Na saída, elas são escapadas se o auto escapamento estiver ativado, caso contrário, são apresentadas sem mudanças.
\n
Safe strings são strings que tenham sido marcadas como seguras para futuros “escaping” no tempo de saída. Qualquer “escaping” necessário já foi feito. Eles são comumente usados para saídas que contenham HTML puro que se destina a ser interpretado como estão do lado do cliente.
\n
Internally, these strings are of type\nSafeString. You can test for them\nusing code like:
\n
Code
fromdjango.utils.safestringimport SafeString\n\nifisinstance(value, SafeString):\n # Do something with the "safe" string.\n ...\n
\n
\n
\n
Código de filtros de templates caem em um das duas situações:
\n\n
Seu filtro não introduz qualquer caracter HTML inseguro (<, >, ', " or &) no resultado que ainda não foi apresentado. Neste caso, você pode deixar o Django cuidar de toda a manipulação do “auto-espacaping” pra você. Tudo o que precisa é definir a “flag” ìs_safe``para ``True` quando registrar a função do filtro, como:
A “flag” diz ao Django que se uma string “segura” é passada para seu filtro, o resultado ainda será “seguro” e se uma string não segura é passada, Django irá automaticamente fazer o “escape”, se necessário.
\n
Você pode entender isso como “este filtro é seguro – ele não introduz qualquer possibilidade de HTML não seguro”
\n
A razão da necessidade do is_safe é porque existem muitas operações de string normais que irão transformar um objeto SafeData de volta em um objeto str normal e, ao invés de tentar capturar eles todos, o que seria muito difícil, Django repara o dano depois que o filtro é completado.
\n
Por exemplo, suponha que tenha um filtro que adiciona a string xx``ao final de uma entrada. Uma vez que isso não introduz nenhum caracter HTML perigoso para o resultado (além daqueles que já estão presentes), você deveria marcar seu filtro como ``is_safe:
Quando o filtro é usado em um template onde a auto-substituição está habilitada, o Django irá fazer a substituição na saída sempre que a entrada ainda não estiver marcada como “safe”.
\n
Por padrão, is_safe é falso, e você pode omiti-lo em qualquer filtro onde ele não é requerido.
\n
Tenha cuidado quando estiver decidindo se o seu filtro realmente irá deixar strings seguras como “safe”. Se estiver “removendo” caracteres, poderia deixar tags HTML ou entidades incompletas no resultado. Por exemplo, removendo um >``de uma entrada poderia tornar ``<a> em um <a, que poderia ser necessário fazer o “escape” na saída para evitar causar problemas. Similar a isso, removendo um ponto-e-vírgula (;) pode tornar um & amp; em um & amp , o qual não é mais uma entidade válida e assim precisa realizar o “escape”. A maioria dos casos nem chegarão perto de ser complicados assim, mas fique de olho para qualquer problema como este quando revisar seu código.
\n
Fazendo um filtro is_safe obriga que este retorne um valor do tipo string. Se o seu filtro deveria retornar uma boolean ou outro valor que não uma string, marcar isso como is_safe provavelmente terá consequências inexperadas (tal como converter um booleano “False” para a string ‘False’).
\n
\n
Uma alternativa, o código do seu filtro pode manualmente cuidar das substituições necessárias. Isso é necessário quando adicionar uma marcação HTML ao resultado. Você quer marcar a saída como segura de substituições posteriores, então suas marcação HTML não será substituída, e precisará tratar a entrada por conta própria.
Porém, tenha cuidado. É necessário mais que marcar a saída como segura. É necessário ter certeza que isso é realmente seguro, e o que fará depende se a auto-substituição está fazendo efeito. A idéia é escrever filtros que podem operar em templates onde o auto-escaping está ligado ou desligado de modo a tornar as coisas mais fáceis para os autores de templates.
\n
Para que seu filtro saiba o estado corrente do estado da auto-substituição, defina a flag needs_autoescape como True quando registrar o filtro. (se não especificar esa flag, seu valor padrão é False). Esta flag dia ao Django que sua função do filtro quer que seja passado um argumento extra, chamado autoescape`, que é ``True se está em efeito e False``caso contrário. É recomendado definir o padrão do parâmetro ``autoescape para True, então se a função for chamado de um código Python esta terá a substituição habilitada por padrão.
\n
Por exemplo, vamos escrever um filtro que enfatiza o primeiro caracter de uma string:
\n
Code
fromdjangoimport template\nfromdjango.utils.htmlimport conditional_escape\nfromdjango.utils.safestringimport mark_safe\n\nregister = template.Library()\n\n\n@register.filter(needs_autoescape=True)\ndefinitial_letter_filter(text, autoescape=True):\n first, other = text[0], text[1:]\n if autoescape:\n esc = conditional_escape\n else:\n esc =lambda x: x\n result ="<strong>%s</strong>%s"%(esc(first), esc(other))\n return mark_safe(result)\n
\n
The needs_autoescape flag and the autoescape keyword argument mean\nthat our function will know whether automatic escaping is in effect when the\nfilter is called. We use autoescape to decide whether the input data\nneeds to be passed through django.utils.html.conditional_escape or not.\n(In the latter case, we use the identity function as the “escape” function.)\nThe conditional_escape() function is like escape() except it only\nescapes input that is not a SafeData instance. If a SafeData\ninstance is passed to conditional_escape(), the data is returned\nunchanged.
\n
Finalmente, no exemplo acima, relembramos de marcar resultados como seguros assim que o HTML é inserido diretamente no template sem outras substituições.
\n
Não precisa se preocupar com a flag is_safe neste caso (embora inclui-la não faria nenhum mal). Mesmo que trate manualmente a auto-substituição e retorne uma string segura, a flag is_safe não alterará nada de nenhum modo.
Quando esta flag está definida, se o primeiro argumento do seu filtro é uma date-time que leva em consideração o fuso-horário, o Django irá convertê-lo para o fuso-horário corrente antes de passa-lo para o filtro quando apropriado, de acordo com rules for time zones conversions in templates.
Tags são mais complexas que filtros, porque as tags podem fazer qualquer coisa. Django fornece inúmeros atalhos para fazer com que a escrita de várias tags seja mais fácil. Primeiro iremos explorar estes atalhos, e então explicar como escrever uma tag do início para aqueles casos em que os atalhos não são poderosos o suficiente.
Muitas tags de templates recebem inúmeros argumentos – strings ou variáveis de templates – e retornam um resultado depois de fazer algum processamento baseado somente nos argumentos de entrada e alguma informação externa. Por exemplo, uma tag current_time aceitaria uma string de formato e retorna a hora como uma string formatada de acordo.
\n
Para facilitar a criação destes tipos de tags, Django fornece uma função de auxílio, simple_tag. Essa função, a qual é um método de django.template.Library, tem uma função que recebe qualquer número de parâmetros, empacota isso em uma função renderizadora junto com os “bits” mencionados acima e o registra com o sistema de templates.
\n
Nossa função current_time poderia então ser escrita assim:
Algumas coisas para perceber sobre a função de auxílio simple_tag:
\n
\n
A checagem do número de arrgumentos, etc, já foi feito na hora em que a função é chamada, então não precisamos faze-lo.
\n
The quotes around the argument (if any) have already been stripped away,\nso we receive a plain string.
\n
Se o argumento era uma variável de template, é passada par a nossa função o valor atual da variável, e não a própria variável.
\n
\n
Diferente de outras ferramentas de tag, simple_tag passa sua saida através do conditional_escape() se o contexto do tempte está no modo auto-substituição, para assegurar o HTML e proteger da vulnerabilidade XSS.
\n
Se substituições adicionais não são desejadas, é necessário usar mark_safe() se você tem a certeza absoluta que seu código não contém vulnerabilidade XSS. Para construir pequenos fragmentos de HTML, é fortemente recomendado usar format_html() ao invés de mark_safe()
\n
Se a template tag precisa acessar o contexto corrente, você pode usar o argumento takes_context quando registrá-la:
Então no template qualquer número de argumentos, separados por espaços podem ser passados para a atg de template. Como em Python, os valores para argumentos nomeados são definidos usando o sinal de igua (”=”) e devem ser fornecidos depois dos argumentos posicionais. Por exemplo:
É possível armazenar os resultados da tag em uma variável de template ao invés de enviar para a saída diretamente. Isso é feito utilizando o argumento as seguido de um nome de variável. Fazendo isso é possível posicionar o conteúdo onde você achar cabido.
\n
Django template
{%current_time"%Y-%m-%d %I:%M %p"asthe_time%}\n<p>The time is {{the_time}}.</p>\n
Outro tipo de tag de template é o tipo que mostra alguns dados renderizados por outro template. Por exemplo, a interface do Admin do Django usa tags de tempate para mostrar os botões ao longo do final das páginas de formulários “add/change”. Esses botões sempre parecem os mesmos, mas o link de destino mudam dependendo do objeto sendo editado – então são um perfeito caso para usar um template pequeno que é preenchido com detalhes do objeto atual. (No caso do Admin, essa é a tag submit_row.)
\n
Este tipo de Tag são chamadas “tags de inclusão”
\n
Escrever tags de inclusão é provavelmente melhor demonstrado através de exemplos. Vamos escrever uma Tag que devolve uma lista de opções para um dado objeto Poll, tal como o que foi criado no tutorials. Usaremos a tag assim:
Primeiro defina a função que recebe os argumentos e produz um dicionário de dados para o resultado. O ponto importante aqui é que precisamos somente retornar um dicionário, não algo mais complexo. Isso será usado como um contexto para o fragmento de template. Exemplo:
Next, create the template used to render the tag’s output. This template is a\nfixed feature of the tag: the tag writer specifies it, not the template\ndesigner. Following our example, the template is very short:
Agora, crie e registre a tag de inclusão chamando o método inclusion_tag() em um objeto do tipo Library. Seguindo nosso exemplo, se o exemplo acima é um arquivo chamado results.html em um diretório que é procurado pelo template loader, nós regitramos a tag assim:
\n
Code
# Here, register is a django.template.Library instance, as before\n@register.inclusion_tag("results.html")\ndefshow_results(poll):\n ...\n
\n
Alternativamente é possível registrar a tag de inclusão usando uma instância de django.template.Template:
Algumas vezes, sua tag de inclusão requer um número grande de argumentos, tornando uma dor de cabeça para autores dos templates passar todos os argumentos e lembrar sua ordem. Para resolver isso, o Django fornece uma opção takes_context para tags de inclusão. Se o especificado o takes_context na criação da tag de template, a tag não terá argumentos requeridos, e a função Python implícita terá um argumento – o contexto do template quando a tag foi chamada.
\n
Por exemplo, digamos que esteja escrevendo uma tag de inclusão que sempre será usada em um contexto que contém as variásveis home_link e home_title que apontam de volta para a página principal. Aqui como a função Python deveria parecer:
Repare que o primeiro parâmetro para a função deve ser chamado de context.
\n
Na linha register.inclusion_tag(), especificamos o takes_context=True e o nome do template. Aqui o que o template link.html deve se parecer:
\n
Django template
Jump directly to <ahref="{{link}}">{{title}}</a>.\n
\n
Então, qualquer momento que queira usar a tag personalizada, carregue sua biblioteca e chame-a sem nenhum argumento, como:
\n
Django template
{%jump_link%}\n
\n
Repare que quando estiver usando takes_context=True, não tem necessidade de passar argumentos para a tag de template. Esta tem acessa o contexto automaticamente.
\n
O parâmetro padrão para takes_context é False. Quando definido como True, para tag é passado o objeto contexto, como neste exemplo. Este é a única diferença entre este caso e o exemplo inclusion_tag anterior.
\n
Funções inclusion_tag podem aceitar qualquer número de argumentos posicionais ou nomeados. Por exemplo:
Então no template qualquer número de argumentos, separados por espaços podem ser passados para a atg de template. Como em Python, os valores para argumentos nomeados são definidos usando o sinal de igua (”=”) e devem ser fornecidos depois dos argumentos posicionais. Por exemplo:
As vezes as funções básicas para criação das tags de template não são o suficiente. Não se preocupe, o Django lhe dá completo acesso as “coisas”internas requeridas para construir uma tag de template do zero.
O sistema de templates funciona em um processo de 2 passos.: compilação e renderização. Para definir uma tag de template personalizada, é necessário especificar como a compilação funcionar e como a renderização funciona.
\n
When Django compiles a template, it splits the raw template text into\n‘’nodes’’. Each node is an instance of django.template.Node and has\na render() method. A compiled template is a list of Node objects. When\nyou call render() on a compiled template object, the template calls\nrender() on each Node in its node list, with the given context. The\nresults are all concatenated together to form the output of the template.
\n
Então, para definir uma tag de template personalizada, especifique como a tag de template original é convertida em um Nó (a função de compilação), e o que o método ``render()``do nó faz.
Para cada tag de template que o analisador de templates encontra, ele chama uma função Python com o conteúdo da tag e o próprio objeto analisador. Essa função é responsável por retornar uma instância de Node baseada no conteúdo da tag.
\n
For example, let’s write a full implementation of our template tag,\n{% current_time %}, that displays the current date/time, formatted according\nto a parameter given in the tag, in strftime() syntax. It’s a good\nidea to decide the tag syntax before anything else. In our case, let’s say the\ntag should be used like this:
\n
Django template
<p>The time is {%current_time"%Y-%m-%d %I:%M %p"%}.</p>\n
\n
O analisador para essa função deve pegar o parâmetro e criar um objeto Node:
\n
Code
fromdjangoimport template\n\n\ndefdo_current_time(parser, token):\n try:\n # split_contents() knows not to split quoted strings.\n tag_name, format_string = token.split_contents()\n exceptValueError:\n raise template.TemplateSyntaxError(\n "%r tag requires a single argument"% token.contents.split()[0]\n )\n ifnot(format_string[0]== format_string[-1]and format_string[0]in('"',"'")):\n raise template.TemplateSyntaxError(\n "%r tag's argument should be in quotes"% tag_name\n )\n return CurrentTimeNode(format_string[1:-1])\n
\n
Notas:
\n
\n
parser é o objeto analisador do template. Nós não precisamos dele neste exemplo.
\n
token.contents é uma string com o conteúdo original da tag, No nosso exemplo, isso é 'current_time "%Y-%m-%d %I:%M %p"'.
\n
O método token.split_contents() separa os argumentos por espaços enquanto mantém strings entre aspas, juntas. Mais direto o token.contents.split() não seria tão robusto já que ingenuamente dividiria todos os espaços, incluindo aqueles dentro de aspas. É uma boa idéia usar sempre o token.split_contents().
\n
Essa função é responsável for informar o django.template.TemplateSyntaxError, com mensagens de ajuda, para qualquer erro de sintaxe.
\n
As exceções TemplateSyntaxError usam a variável tag_name. Não coloque nomes de tags dentro de suas mensagens de erro, porque isso amarra o nome da tag a sua função. token.contents.split()[0] ‘’sempre’’ será o nome da sua tag – mesmo quando sua tag não tem argumentos.
\n
The function returns a CurrentTimeNode with everything the node needs\nto know about this tag. In this case, it passes the argument –\n"%Y-%m-%d %I:%M %p". The leading and trailing quotes from the\ntemplate tag are removed in format_string[1:-1].
\n
O analisador é muito baixo nível. Os desenvolvedores do Django experimentaram escrever pequenos frameworks baseados no sistema analisador (“parser”), usando técnicas como a gramática EBNF, mas estes experimentos tornaram o motor de template muito lento. É baixo-nível porque é rápido.
__init__() recebe o format_string do do_current_time(). Sempre passar opções/parametros/argumentos para um Node através de seu __init__().
\n
O método render() é onde o trabalho realmente acontece
\n
render() deve geralmente falhar silenciosamente, particularmente no ambiente de produção. Em alguns casos porém, particularmente se context.template.engine.debug for True, este método pode indicar uma exceção para ficar mais fácil debugar. Por exemplo, muitas tags do core inviam django.template.TemplateSyntaxError se eles receberem o número errado ou tipo de argumentos.
\n
\n
Por último, este desacomplamento entre compilação e renderização resulta em um sistema de template mais eficiente, porque o template pode renderizar múltiplos contextos ser ter que ser analisado (“parsed”) múltiplas vezes.
A saída da tag de template não passa automaticamente pelos filtros de auto-escaping (com exceção do simple_tag() , como descrito acima). Porém, ainda existem algumas coisas para se ter em mente ao escrever uma tag de template.
\n
If the render() method of your template tag stores the result in a context\nvariable (rather than returning the result in a string), it should take care\nto call mark_safe() if appropriate. When the variable is ultimately\nrendered, it will be affected by the auto-escape setting in effect at the\ntime, so content that should be safe from further escaping needs to be marked\nas such.
\n
Também, se sua tag cria um novo contexto para realizar algum sub renderização, defina o atributo de auto-substituição para o valor do contexto corrente. O método __init__ da classe Context recebe um parâmetro chamado autoescape que pode ser usado para este propósito. Por exemplo:
\n
Code
fromdjango.templateimport Context\n\n\ndefrender(self, context):\n # ...\n new_context = Context({"var": obj}, autoescape=context.autoescape)\n # ... Do something with new_context ...\n
\n
Isso não é uma situação muito comum, mas é útil se você está renderizando você mesmo o template. Por exemplo:
\n
Code
defrender(self, context):\n t = context.template.engine.get_template("small_fragment.html")\n return t.render(Context({"var": obj}, autoescape=context.autoescape))\n
\n
Se negligenciássemos ao passar o valor no corrente context.autoescape para ao novo Context neste exemplo, os resultados seriam sempre automaticamente substituidos, o que pode não ser o comportamento desejável se a tg de template for usada dentro de um bloco {% autoescape off %} .
Uma vez que o nó tenha sido analisado, seu método render pode ser chamado qualquer número de vezes. Uma vez que o Django roda algumas vezes em ambientes multi-threaded, um nó pode ser renderizado simultaneamente com diferentes contextos em resposta a dois requests diferentes. Por isso, é importante que suas tags de templates são segurara para “threads”.
\n
Para ter certeza que sua tag de template é segura para rodar em threads, nunca deve armazenar informação no próprio nó. Por exemplo, Django fornece a template tag cycle que alterna os intens de uma lista de strings cada vez que é renderizada:
Mas, suponha que temos dois templates renderizando o pedaço de template acima ao mesmo tempo.
\n\n
Thread 1 realiza sua primeira iteração, CycleNode.render() retorna ‘row1’
\n
Thread 2 realiza sua primeira iteração, CycleNode.render() retorna ‘row2’
\n
Thread 1 realiza sua segunda iteração, CycleNode.render() retorna ‘row2’
\n
Thread 2 realiza sua segunda iteração, CycleNode.render() retorna ‘row2’
\n\n
The CycleNode is iterating, but it’s iterating globally. As far as Thread 1\nand Thread 2 are concerned, it’s always returning the same value. This is\nnot what we want!
\n
Para resolver o problema, o Django provê o render_context que associado com o context do template que está correntemente sendo renderizado. O render_context se comporta como um dicionário Python, e deve ser usado para armazenar os estados do Node entre chamadas do método render.
\n
Vamos refatorar nosso implementação do CycleNode para usar o render_context:
Note que é perfeitamente seguro armazenar informação global que não irá se alterar através da vida do Node como um atributo. No caso do CycleNode, o argumento cyclevars não muda depois que Node é instanciado., então não precisamos colocá-lo no render_context. Mas informações do estado que é específica para o template que está sendo renderizado no momento, como a citeração corrente do CycleNode, deve ser armazenado no render_context
Embora você possa passar qualquer número de argumentos para uma tag de template usando token.split_contents(), os argumentos são todos “desempacotados” como strings literais. Um pouco mais de trabalho é requerido para que passe o conteúdo dinamicamente (uma variável de template) para uma tag de template como argumento.
\n
Enquando os exemplos anteriores formataram a hora corrente como string e retornaram uma string, suponha que queira passar um DateTimeField de um objeto e a template tag formate o date-time:
\n
Django template
<p>This post was last updated at {%format_timeblog_entry.date_updated"%Y-%m-%d %I:%M %p"%}.</p>\n
\n
Inicialmente, token.split_contents() irá retornar três valores:
\n\n
A tag chamada format_time.
\n
A string 'blog_entry.date_updated' (sem as aspas).
\n
A string de formatação '"%Y-%m-%d %I:%M %p"'. O valor retornado do split_contents() irá incluir as aspas para string literais como esta.
\n\n
Agora sua tag deve começar a parecer com isso:
\n
Code
fromdjangoimport template\n\n\ndefdo_format_time(parser, token):\n try:\n # split_contents() knows not to split quoted strings.\n tag_name, date_to_be_formatted, format_string = token.split_contents()\n exceptValueError:\n raise template.TemplateSyntaxError(\n "%r tag requires exactly two arguments"% token.contents.split()[0]\n )\n ifnot(format_string[0]== format_string[-1]and format_string[0]in('"',"'")):\n raise template.TemplateSyntaxError(\n "%r tag's argument should be in quotes"% tag_name\n )\n return FormatTimeNode(date_to_be_formatted, format_string[1:-1])\n
\n
Também é necessário alterar o renderizador para retornar o conteúdo atual da propriedade date_update do objeto blog_entry.
\n
To use the Variable class, instantiate it with the name of the variable to\nbe resolved, and then call variable.resolve(context). So, for example:
The above examples output a value. Generally, it’s more flexible if your\ntemplate tags set template variables instead of outputting values. That way,\ntemplate authors can reuse the values that your template tags create.
\n
To set a variable in the context, use dictionary assignment on the context\nobject in the render() method. Here’s an updated version of\nCurrentTimeNode that sets a template variable current_time instead of\noutputting it:
Repare que render() retorna uma string vazia. render() deve sempre retornar uma string como saída. Se tudo que a tag de template faz é definir uma variável, render() deve retornar uma string vazia.
\n
Aqui como você deveria usar esta nova versão da tag:
\n
Django template
{%current_time"%Y-%m-%d %I:%M %p"%}<p>The time is {{current_time}}.</p>\n
\n\n
Mas, tem um problema com CurrentTimeNode2: O nome da variável current_time está “hardecodeada”. Isso significa que tem que ter certeza seu template não usa {{ current_time }} em nenhum outro lugar, porque o {% current_time %} irá redefinir o valor da variável. Uma solução mais limpa é fazer a tag de template especificar o nome da variável de saída, como:
\n
Django template
{%current_time"%Y-%m-%d %I:%M %p"asmy_current_time%}\n<p>The current time is {{my_current_time}}.</p>\n
\n
Para fazer isso, será preciso refatorar a função de compilação e a classe de ``Node`, deste modo:
\n
Code
importre\n\n\nclassCurrentTimeNode3(template.Node):\n def__init__(self, format_string, var_name):\n self.format_string = format_string\n self.var_name = var_name\n\n defrender(self, context):\n context[self.var_name]= datetime.datetime.now().strftime(self.format_string)\n return""\n\n\ndefdo_current_time(parser, token):\n # This version uses a regular expression to parse tag contents.\n try:\n # Splitting by None == splitting by spaces.\n tag_name, arg = token.contents.split(None,1)\n exceptValueError:\n raise template.TemplateSyntaxError(\n "%r tag requires arguments"% token.contents.split()[0]\n )\n m = re.search(r"(.*?) as (\\w+)", arg)\n ifnot m:\n raise template.TemplateSyntaxError("%r tag had invalid arguments"% tag_name)\n format_string, var_name = m.groups()\n ifnot(format_string[0]== format_string[-1]and format_string[0]in('"',"'")):\n raise template.TemplateSyntaxError(\n "%r tag's argument should be in quotes"% tag_name\n )\n return CurrentTimeNode3(format_string[1:-1], var_name)\n
\n
A diferença aqui é que do_current_time() pega a string de formato e o nome da variável passando ambos para CurrenteNode3.
\n
Finalmente, se você precisa ter somente uma sinatxe simples para sua tag de template personalizada que atualiza o contexto, considere usar o atalho simple_tag(), o qual possibilita passar os resultados de uma tag para uma variável de template.
Tags de templates podem trabalhar em tandem. Por exemplo, a tag padrão {% comment %} esconde tudo até {% endcomment %}. Para criar uma tag de template coo esta, use parser.parse() na sua função de compilação.
\n
Aqui como uma tag {% comment %} simplificada pode ser implmentada:
parser.parse() recebe uma tupla de nomes de blocos de tags para parsear. Ele retorna uma instância de django.template.NodeList, que é uma lista de todos os objetos Node que o analisador encontrou “antes” que tenha encontrado qualquer nome de tags na tupla.
\n
Em "nodelist = parser.parse(('endcomment',))" no exemplo acima, nodelist é uma lista de todos os nós entre o``{% comment %}`` e {% endcomment %}, sem contar os próprios {% comment %} e {% endcomment %}.
\n
Depois que parser.parse() é chamado, o analisaor sintático ainda não “consumiu” a tag {% endcomment %}, então o código precisa chamar explicitamente o parser.delete_first_token().
\n
CommentNode.render() returns an empty string. Anything between\n{% comment %} and {% endcomment %} is ignored.
\n\n\n
Analisando sintaticamente até um outro bloco da tag, e armazenando seu conteúdo.Link para este cabeçalho#
\n
No exemplo anterior, do_comment() descartou tudo entre``{% comment %}`` e {% endcomment %}. Ao invés de fazer isso, é possível fazer alguma coisa com o código que está dentro do bloco de tags.
\n
Por exemplo, aqui uma tag de template, {% upper %}, que coloca todas as letras em maiúsculo de tudo entre ela e {% endupper %}.
\n
Uso:
\n
Django template
{%upper%}This will appear in uppercase, {{your_name}}.{%endupper%}\n
\n
Como no exemplo anterior, usaremos parser.parse(). Mas agora, passamos o nodelist resultante para o Node:
\n\n","rootId":"how-to-create-custom-template-tags-and-filters","toc":[{"title":"Layout do código","anchor":"code-layout","children":[]},{"title":"Escrevendo filtros de templates personalizados","anchor":"writing-custom-template-filters","children":[{"title":"Registrando filtros customizados","anchor":"registering-custom-filters","children":[]},{"title":"Filtros de templates que recebem strings","anchor":"template-filters-that-expect-strings","children":[]},{"title":"Filtros e auto-escaping","anchor":"filters-and-auto-escaping","children":[]},{"title":"Filtros e fusos horários","anchor":"filters-and-time-zones","children":[]}]},{"title":"Escrevendo tags de templates personalizadas.","anchor":"writing-custom-template-tags","children":[{"title":"Tags simples","anchor":"simple-tags","children":[]},{"title":"Tags de inclusão","anchor":"inclusion-tags","children":[]},{"title":"Tags personalizadas avançadas","anchor":"advanced-custom-template-tags","children":[]},{"title":"Um rápida visão geral","anchor":"a-quick-overview","children":[]},{"title":"Escrevendo a função de compilação","anchor":"writing-the-compilation-function","children":[]},{"title":"Escrevendo o “renderizador”","anchor":"writing-the-renderer","children":[]},{"title":"Considerações sobre auto-substituição","anchor":"auto-escaping-considerations","children":[]},{"title":"Considerações sobre segurança de “thread”","anchor":"thread-safety-considerations","children":[]},{"title":"Registrando a tag","anchor":"registering-the-tag","children":[]},{"title":"Passando variáveis de template para a tag.","anchor":"passing-template-variables-to-the-tag","children":[]},{"title":"Definindo uma variável no contexto","anchor":"setting-a-variable-in-the-context","children":[]},{"title":"“Parsing” até outra bloco de tag.","anchor":"parsing-until-another-block-tag","children":[]},{"title":"Analisando sintaticamente até um outro bloco da tag, e armazenando seu conteúdo.","anchor":"parsing-until-another-block-tag-and-saving-contents","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"Guias de “como fazer”","url":"/pt-br/4.2/howto/"}],"prev":{"docname":"howto/custom-template-backend","title":"How to implement a custom template backend","url":"/pt-br/4.2/howto/custom-template-backend/"},"next":{"docname":"howto/custom-file-storage","title":"Como escrever uma classe de armazenamento customizada","url":"/pt-br/4.2/howto/custom-file-storage/"},"formats":{"html":"/pt-br/4.2/howto/custom-template-tags/","markdown":"/pt-br/4.2/howto/custom-template-tags.md","json":"/pt-br/4.2/howto/custom-template-tags.json"},"source":"https://github.com/django/django/blob/stable/4.2.x/docs/howto/custom-template-tags.txt","official":"https://docs.djangoproject.com/pt-br/4.2/howto/custom-template-tags/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}