En este apéndice se listan la mayoría de las etiquetas y filtros utilizados en las plantillas o templates.
Define un bloque que puede ser sobreescrito por las plantillas derivadas. Véase la sección acerca de herencia de plantillas para más información.
Ignora todo lo que aparezca entre {% comment %} y {% endcomment %}.
Rota una cadena de texto entre diferentes valores, cada vez que aparece la etiqueta.
Dentro de un bucle, el valor rota entre los distintos valores disponibles en cada iteración del bucle:
{% for o in some_list %}
<tr class="{% cycle row1,row2 %}">
...
</tr>
{% endfor %}
Fuera de un bucle, hay que asignar un nombre único la primera vez que se usa la etiqueta, y luego hay que incluir ese nombre en las sucesivas llamadas:
<tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
Se puede usar cualquier número de valores, separándolos por comas. Se debe asegurar de no poner espacios entre los valores, sólo comas.
Sirve para indicar que esta plantilla extiende una plantilla padre.
Esta etiqueta se puede usar de dos maneras:
- {% extends "base.html" %} (Con las comillas) interpreta literalmente "base.html" como el nombre de la plantilla a extender.
- {% extends variable %} usa el valor de variable. Si la variable apunta a una cadena de texto, se usará dicha cadena como el nombre de la plantilla padre. Si la variable es un objeto de tipo Template, se usará ese mismo objeto como plantilla base.
Filtra el contenido de una variable.
Los filtros pueden ser encadenados sucesivamente (la salida de uno es la entrada del siguiente), y pueden tener argumentos, como en la sintaxis para variables.
He aquí un ejemplo:
{% filter escape|lower %}
This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}
Presenta como salida la primera de las variables que se le pasen que evalúe como no falsa. La salida será nula si todas las variables pasadas valen False.
He aquí un ejemplo:
{% firstof var1 var2 var3 %}
Equivale a:
{% if var1 %}
{{ var1 }}
{% else %}{% if var2 %}
{{ var2 }}
{% else %}{% if var3 %}
{{ var3 }}
{% endif %}{% endif %}{% endif %}
Itera sobre cada uno de los elementos de un array o lista. Por ejemplo, para mostrar una lista de atletas, cuyos nombres estén en la lista athlete_list, se puede hacer:
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
</ul>
También se puede iterar la lista en orden inverso usando {% for obj in list reversed %}.
Dentro de un bucle, la propia sentencia for crea una serie de variables. A estas variables se puede acceder únicamente dentro del bucle. Las distintas variables se explican en la tabla. Los nombres descriptos son propiedades de la variable forloop, es decir, para el nombre counter, el acceso se realiza a través de forloop.counter.
| Variable | Descripción |
| forloop.counter | El número de vuelta o iteración actual (usando un índice basado en 1). |
| forloop.counter0 | El número de vuelta o iteración actual (usando un índice basado en 0). |
| forloop.revcounter | El número de vuelta o iteración contando desde el fin del bucle (usando un índice basado en 1). |
| forloop.revcounter0 | El número de vuelta o iteración contando desde el fin del bucle (usando un índice basado en 0). |
| forloop.first | true si es la primera iteración. |
| forloop.last | true si es la última iteración. |
| forloop.parentloop | Para bucles anidados, es una referencia al bucle externo. |
La etiqueta {% if %} evalúa una variable. Si dicha variable se evalúa como una expresión “verdadera” (es decir, que el valor exista, no esté vacía y no es el valor booleano false), se muestra el contenido del bloque:
{% if athlete_list %}
Number of athletes: {{ athlete_list|length }}
{% else %}
No athletes.
{% endif %}
Si la lista athlete_list no está vacía, se puede mostrar el número de atletas con la expresión {{ athlete_list|length }}
Además, como se puede ver en el ejemplo, la etiqueta if puede tener un bloque opcional {% else %} que se mostrará en el caso de que la evaluación de falso.
Las etiquetas if pueden usar operadores lógicos como and, or y not para evaluar expresiones más complejas:
{% if athlete_list and coach_list %}
Both athletes and coaches are available.
{% endif %}
{% if not athlete_list %}
There are no athletes.
{% endif %}
{% if athlete_list or coach_list %}
There are some athletes or some coaches.
{% endif %}
{% if not athlete_list or coach_list %}
There are no athletes or there are some coaches (OK, so
writing English translations of Boolean logic sounds
stupid; it's not our fault).
{% endif %}
{% if athlete_list and not coach_list %}
There are some athletes and absolutely no coaches.
{% endif %}
La etiqueta if no admite, sin embargo, mezclar los operadores and y or dentro de la misma comprobación, porque el orden de aplicación de los operadores lógicos sería ambiguo. Por ejemplo, el siguiente código es inválido:
{% if athlete_list and coach_list or cheerleader_list %}
Para combinar operadores and y or, se pueden usar sentencias if anidadas, como en el siguiente ejemplo:
{% if athlete_list %}
{% if coach_list or cheerleader_list %}
We have athletes, and either coaches or cheerleaders!
{% endif %}
{% endif %}
Es perfectamente posible usar varias veces un operador lógico, siempre que sea siempre el mismo. Por ejemplo, el siguiente código es válido:
{% if athlete_list or coach_list or parent_list or teacher_list %}
Comprueba si un valor ha sido cambiado desde la última iteración de un bucle.
La etiqueta ifchanged sólo tiene sentido dentro de un bucle. Tiene dos usos posibles:
- Comprueba su propio contenido mostrado contra su estado anterior, y sólo lo muestra si el contenido ha cambiado. El siguiente ejemplo muestra una lista de días, y sólo aparecerá el nombre del mes si este cambia:
<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 %}
Se le pasa una o más variables, y se comprueba si esas variables han sido cambiadas:
{% for date in days %} {% ifchanged date.date %} {{ date.date }} {% endifchanged %} {% ifchanged date.hour date.date %} {{ date.hour }} {% endifchanged %} {% endfor %}El ejemplo anterior muestra la fecha cada vez que cambia, pero sólo muestra la hora si tanto la hora como el día han cambiado.
Muestra el contenido del bloque si los dos argumentos suministrados son iguales.
He aquí un ejemplo:
{% ifequal user.id comment.user_id %}
...
{% endifequal %}
Al igual que con la etiqueta {% if %}, existe una cláusula {% else %} opcional.
Los argumentos pueden ser cadenas de texto, así que el siguiente código es válido:
{% ifequal user.username "adrian" %}
...
{% endifequal %}
Sólo se puede comprobar la igualdad de variables o cadenas de texto. No se puede comparar con objetos true o false. Para ello, se debe utilizar la etiqueta if directamente.
Es igual que ifequal, excepto que comprueba que los dos parámetros suministrados no sean iguales.
Carga una plantilla y la representa usando el contexto actual. Es una forma de “incluir” una plantilla dentro de otra.
El nombre de la plantilla puede o bien ser el valor de una variable o estar escrita en forma de cadena de texto, rodeada ya sea con comillas simples o comillas dobles, a gusto del lector.
El siguiente ejemplo incluye el contenido de la plantilla "foo/bar.html":
{% include "foo/bar.html" %}
Este otro ejemplo incluye el contenido de la plantilla cuyo nombre sea el valor de la variable template_name:
{% include template_name %}
Carga una biblioteca de plantillas.
Muestra la fecha, escrita de acuerdo a un formato indicado.
Esta etiqueta fue inspirada por la función date() de PHP(), y utiliza el mismo formato que ésta (http://php.net/date). Esta versión tiene, sin embargo, algunos extras.
He aquí un ejemplo:
It is {% now "jS F Y H:i" %}
Se pueden escapar los caracteres de formato con una barra invertida, si se quieren incluir de forma literal. En el siguiente ejemplo, se escapa el significado de la letra “f” con la barra invertida, ya que de otra manera se interpretaría como una indicación de incluir la hora. La “o”, por otro lado, no necesita ser escapada, ya que no es un carácter de formato:
It is the {% now "jS o\f F" %}
El ejemplo mostrará: “It is the 4th of September”.
Reagrupa una lista de objetos similares usando un atributo común.
Para comprender esta etiqueta, es mejor recurrir a un ejemplo. people es una lista de objetos de tipo Person, y los objetos tienen los atributos first_name, last_name y gender. Si se quiere mostrar un listado como el siguiente:
- Male:
- George Bush
- Bill Clinton
- Female:
- Margaret Thatcher
- Condoleezza Rice
- Unknown:
- Pat Smith
el siguiente fragmento de plantilla ilustra cómo realizar esta tarea:
{% regroup people by gender as grouped %}
<ul>
{% for group in grouped %}
<li>{{ group.grouper }}
<ul>
{% for item in group.list %}
<li>{{ item }}</li>
{% endfor %}
</ul>
</li>
{% endfor %}
</ul>
Como se puede observar, {% regroup %} crea una nueva variable, que es una lista de objetos que tienen dos tributos, grouper y list. En grouper se almacena el valor de agrupación, list contiene una lista de los objetos que tenían en común al valor de agrupación. En este caso, grouper podría valer Male, Female y Unknown, y list sería una lista con las personas correspondientes a cada uno de estos sexos.
Hay que destacar que {% regroup %} no funciona correctamente cuando la lista no está ordenada por el mismo atributo que se quiere agrupar. Esto significa que si la lista del ejemplo no está ordenada por el sexo, se debe ordenar antes correctamente, por ejemplo con el siguiente código:
{% regroup people|dictsort:"gender" by gender as grouped %}
Elimina los espacios en blanco entre etiquetas HTML. Ésto incluye tabuladores y saltos de línea.
El siguiente ejemplo:
{% spaceless %}
<p>
<a href="foo/">Foo</a>
</p>
{% endspaceless %}
retornaría el siguiente código HTML:
<p><a href="foo/">Foo</a></p>
Sólo se eliminan los espacios entre las etiquetas, no los espacios entre la etiqueta y el texto. En el siguiente ejemplo, no se quitan los espacios que rodean a la palabra Hello:
{% spaceless %}
<strong>
Hello
</strong>
{% endspaceless %}
Permite representar los caracteres que están definidos como parte del sistema de plantillas.
Como el sistema de plantillas no tiene el concepto de “escapar” el significado de las combinaciones de símbolos que usa internamente, se tiene que recurrir a la etiqueta {% templatetag %} si se ve obligado a representarlos.
Se le pasa un argumento que indica qué combinación de símbolos debe producir. Los valores posibles del argumento se muestran en la tabla.
| Argumento | Salida |
|---|---|
| openblock | {% |
| closeblock | %} |
| openvariable | {{ |
| closevariable | }} |
| openbrace | { |
| closebrace | } |
| opencomment | {# |
| closecomment | #} |
Esta etiqueta es útil para presentar gráficos de barras y similares. Calcula la proporción entre un valor dado y un máximo predefinido, y luego multiplica ese cociente por una constante.
Por ejemplo:
<img src="bar.gif"
height="10"
width="{% widthratio this_value max_value 100 %}" />
Si this_value vale 175 y max_value es 200, la imagen resultante tendrá un ancho de 88 pixels (porque 175/200 = 0.875 y 0.875 * 100 = 87.5, que se redondea a 88).
Ejemplo:
{{ string|addslashes }}
Añade barras invertidas antes de las comillas, ya sean simples o dobles. Es útil para pasar cadenas de texto como JavaScript.
Ejemplo:
{{ value|date:"F j, Y" }}
Formatea una fecha de acuerdo al formato indicado en la cadena de texto (se usa el mismo formato que con la etiqueta now).
Ejemplo:
{{ value|default:"(N/A)" }}
Si value no está definido, se usa el valor del argumento en su lugar.
Ejemplo:
{{ value|default_if_none:"(N/A)" }}
Si value es nulo, se usa el valor del argumento en su lugar.
Ejemplo:
{{ list|dictsort:"foo" }}
Acepta una lista de diccionarios y devuelve una lista ordenada según la propiedad indicada en el argumento.
Ejemplo:
{{ list|dictsortreversed:"foo" }}
Acepta una lista de diccionarios y devuelve una lista ordenada de forma descendente según la propiedad indicada en el argumento.
Ejemplo:
{% if value|divisibleby:"2" %}
Even!
{% else %}
Odd!
{% else %}
Devuelve True si es valor pasado es divisible por el argumento.
Ejemplo:
{{ string|escape }}
Transforma un texto que esté en HTML de forma que se pueda representar en una página web. Concretamente, realiza los siguientes cambios:
- "&" a "&"
- < a "<"
- > a ">"
- '"' (comilla doble) a '"'
- "'" (comillas simple) a '''
Ejemplo:
{{ value|filesizeformat }}
Representa un valor, interpretándolo como si fuera el tamaño de un fichero y humanizando el resultado, de forma que sea fácil de leer. Por ejemplo, las salidas podrían ser '13 KB', '4.1 MB', '102 bytes', etc.
Ejemplo:
{{ string|fix_ampersands }}
Reemplaza los símbolos ampersand con la entidad &.
Ejemplos:
{{ value|floatformat }}
{{ value|floatformat:"2" }}
Si se usa sin argumento, redondea un número en coma flotante a un único dígito decimal (pero sólo si hay una parte decimal que mostrar), por ejemplo:
- 36.123 se representaría como 36.1.
- 36.15 se representaría como 36.2.
- 36 se representaría como 36.
Si se utiliza un argumento numérico, floatformat redondea a ese número de decimales:
- 36.1234 con floatformat:3 se representaría como 36.123.
- 36 con floatformat:4 se representaría como 36.0000.
Si el argumento pasado a floatformat es negativo, redondeará a ese número de decimales, pero sólo si el número tiene parte decimal.
- 36.1234 con floatformat:-3 gets converted to 36.123.
- 36 con floatformat:-4 gets converted to 36.
Usar floatformat sin argumentos es equivalente a usarlo con un argumento de -1.
Ejemplo:
{{ value|get_digit:"1" }}
Dado un número, devuelve el dígito que esté en la posición indicada, siendo 1 el dígito más a la derecha. En caso de que la entrada sea inválida, devolverá el valor original (si la entrada o el argumento no fueran enteros, o si el argumento fuera inferior a 1). Si la entrada es correcta, la salida siempre será un entero.
Ejemplo:
{{ list|join:", " }}
Concatena todos los elementos de una lista para formar una cadena de texto, usando como separador el texto que se le pasa como argumento.
Ejemplo:
{% if list|length_is:"3" %}
...
{% endif %}
Devuelve un valor booleano que será verdadero si la longitud de la entrada coincide con el argumento suministrado.
Ejemplo:
{{ string|linebreaks }}
Convierte los saltos de línea en etiquetas <p> y <br />.
Ejemplo:
{{ string|ljust:"50" }}
Justifica el texto de la entrada a la izquierda utilizando la anchura indicada.
Ejemplo:
{% for i in number|make_list %}
...
{% endfor %}
Devuelve la entrada en forma de lista. Si la entrada es un número entero, se devuelve una lista de dígitos. Si es una cadena de texto, se devuelve una lista de caracteres.
Ejemplo:
The list has {{ list|length }} item{{ list|pluralize }}.
Retorno el sufijo para formar el plural si el valor es mayor que uno. Por defecto el sufijo es 's'.
Ejemplo:
You have {{ num_messages }} message{{ num_messages|pluralize }}.
Para aquellas palabras que requieran otro sufijo para formar el plural, se puede usar una sintaxis alternativa en la que se indique el sufijo que se quiera con un argumento.
Ejemplo:
You have {{ num_walruses }} walrus{{ num_walrus|pluralize:"es" }}.
Para aquellas palabras que forman el plural de forma más compleja que con un simple sufijo, hay otra tercera sintaxis que permite indicar las formas en singular y en plural a partir de una raíz común.
Ejemplo:
You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.
Ejemplo:
{{ string|removetags:"br p div" }}
Elimina de la entrada una o varias clases de etiquetas [X]HTML. Las etiquetas se indican en forma de texto, separando cada etiqueta a eliminar por un espacio.
Ejemplo:
{{ string|rjust:"50" }}
Justifica el texto de la entrada a la derecha utilizando la anchura indicada..
Ejemplo:
{{ string|slugify }}
Convierte el texto a minúsculas, elimina los caracteres que no formen palabras (caracteres alfanuméricos y carácter subrayado), y convierte los espacios en guiones. También elimina los espacios que hubiera al principio y al final del texto.
Ejemplo:
{{ number|stringformat:"02i" }}
Formatea el valor de entrada de acuerdo a lo especificado en el formato que se le pasa como parámetro.
Ejemplo:
{{ value|time:"P" }}
Formatea la salida asumiendo que es una fecha/hora, con el formato indicado como argumento (lo mismo que la etiqueta now).
Ejemplos:
{{ datetime|timesince }}
{{ datetime|timesince:"other_datetime" }}
Representa una fecha como un intervalo de tiempo (por ejemplo, “4 days, 6 hours”).
Acepta un argumento opcional, que es una variable con la fecha a usar como punto de referencia para calcular el intervalo (si no se especifica, la referencia es el momento actual). Por ejemplo, si blog_date es una fecha con valor igual a la medianoche del 1 de junio de 2006, y comment_date es una fecha con valor las 08:00 horas del día 1 de junio de 2006, entonces {{ comment_date|timesince:blog_date }} devolvería “8 hours”.
Ejemplos:
{{ datetime|timeuntil }}
{{ datetime|timeuntil:"other_datetime" }}
Es similar a timesince, excepto en que mide el tiempo desde la fecha de referencia hasta la fecha dada. Por ejemplo, si hoy es 1 de junio de 2006 y conference_date es una fecha cuyo valor es igual al 29 de junio de 2006, entonces {{ conference_date|timeuntil }} devolverá “28 days”.
Acepta un argumento opcional, que es una variable con la fecha a usar como punto de referencia para calcular el intervalo, si se quiere usar otra distinta del momento actual. Si from_date apunta al 22 de junio de 2006, entonces {{ conference_date|timeuntil:from_date }} devolverá “7 days”.
Ejemplo:
{{ string|titlecase }}
Representa una cadena de texto en forma de título, siguiendo las convenciones del idioma inglés (todas las palabras con la inicial en mayúscula).
Ejemplo:
{{ string|truncatewords:"15" }}
Recorta la salida de forma que tenga como máximo el número de palabras que se indican en el argumento.
Ejemplo:
{{ string|truncatewords_html:"15" }}
Es similar a truncatewords, excepto que es capaz de reconocer las etiquetas HTML y, por lo tanto, no deja etiquetas “huérfanas”. Cualquier etiqueta que se hubiera abierto antes del punto de recorte es cerrada por el propio filtro.
Es menos eficiente que truncatewords, así que debe ser usada solamente si se sabe que en la entrada va texto HTML.
Ejemplo:
<ul>
{{ list|unordered_list }}
</ul>
Acepta una lista, e incluso varias listas anidadas, y recorre recursivamente las mismas representándolas en forma de listas HTML no ordenadas, sin incluir las etiquetas de inicio y fin de lista (<ul> y </ul> respectivamente).
Se asume que las listas están en el formato correcto. Por ejemplo, si var contiene ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]], entonces {{ var|unordered_list }} retornará:
<li>States
<ul>
<li>Kansas
<ul>
<li>Lawrence</li>
<li>Topeka</li>
</ul>
</li>
<li>Illinois</li>
</ul>
</li>
Ejemplo:
<a href="{{ link|urlencode }}">linkage</a>
Escapa la entrada de forma que pueda ser utilizado dentro de una URL.
Ejemplo:
{{ string|urlize }}
Transforma un texto de entrada, de forma que si contiene direcciones URL en texto plano, las convierte en enlaces HTML.
Ejemplo:
{{ string|urlizetrunc:"30" }}
Convierte las direcciones URL de un texto en enlaces, recortando la representación de la URL para que el número de caracteres sea como máximo el del argumento suministrado.
Ejemplo:
{{ string|wordwrap:"75" }}
Ajusta la longitud del texto para las líneas se adecúen a la longitud especificada como argumento.
Ejemplo:
{{ boolean|yesno:"Yes,No,Perhaps" }}
Dada una serie de textos que se asocian a los valores de true, false y (opcionalmente) null, devuelve uno de esos textos según el valor de la entrada. Véase la tabla.
| Valor | Argumento | Salida |
|---|---|---|
| true | “yeah,no,maybe” | yeah |
| false | “yeah,no,maybe” | no |
| null | “yeah,no,maybe” | maybe |
| null | “yeah,no” | “no” (considera null como false si no se asigna ningún texto a null. |