Reference¶
Overview¶
TTag replaces the normal method of creating custom template tags. It
uses a custom template Node
subclass called Tag
which handles all of
the relevant aspects of a tag: defining and parsing arguments, handling
validation, resolving variables from the context, and rendering output.
Tag¶
-
class
ttag.
Tag
¶ A representation of a template tag. For example:
class Welcome(ttag.Tag): def output(self, data): return "Hi there!"
Meta options¶
-
class
Tag.
Meta
¶ A
Tag
takes options via aMeta
inner class:class Welcome(ttag.Tag): class Meta: name = "hi"
-
name
¶ Explicitly choose a name for the tag. If not given, the tag’s name will be created by taking the class’s name and converting it from CamelCase to under_score format. For example,
AmazingStuff
would turn into{% amazing_stuff %}
.
-
register
¶ Register the tag in a tag library.
Alternatively, a tag can still be rendered the standard way:
some_library.tag(ThisTag)
.
-
block
¶ Retrieve subsequent template nodes until
{% end[tagname] %}
, adding them toself.nodelists
.
-
end_block
¶ An alternative ending block node. Defaults to
'end%(name)s'
.
-
output¶
If your tag does not modify the output, override this method to change the output of this tag.
render¶
As an alternative to overriding the output
method, a TemplateTag
subclass may directly override the render
method. This is useful for
when you want to alter the context.
-
Tag.
render
(context)¶ Parameters: context – The current template context. render
must return a unicode string.If your tag doesn’t return anything (e.g., it only manipulates the context),
render
should simply return an empty string.
To retrieve the values of the tag’s arguments, if any, use the following method
inside render
:
-
Tag.
resolve
(context)¶ Retrieve the values of the tag’s arguments.
Parameters: context – The current template context. Returns: A data dictionary containing the values of the tag’s arguments.
Arguments¶
Arguments can be either positional or named. They are specified as properties of the tag class, in a similar way to Django’s forms and models.
If the property name clashes with a append a trailing slash - it will be
removed from the argument’s name
. For example, pay attention to the as_
argument in the tag below:
class Set(ttag.Tag):
value = ttag.Arg()
as_ = ttag.BasicArg()
def render(self, context):
data = self.resolve(context)
as_var = data['as']
context[as_var] = data['value']
return ''
Positional arguments¶
By default, an argument is considered positional:
class Positional(ttag.Tag):
first = ttag.Arg()
second = ttag.Arg()
This would result in a tag named positional
which took two required
arguments, which would be assigned to 'first'
and 'second'
items
of the data dictionary returned by the resolve
method.
Use the ConstantArg
for simple required string-based arguments which
assist readability:
class Measure(ttag.Tag):
start = ttag.Arg()
to = ttag.ConstantArg()
finish = ttag.Arg()
Named arguments¶
Named arguments can appear in any order in a tag’s arguments, after the positional arguments.
The standard type of named argument uses space separation:
class Named(ttag.Tag):
limit = ttag.Arg(named=True)
offset = ttag.Arg(named=True)
This would create a tag named named
which took two named arguments,
limit
and offset
. They could be specified in any order:
{% named limit 15 offset 42 %}
{% named offset 4 limit 12 %}
Alternatively, named arguments can use “keyword” style named arguments::
you can use the keyword
parameter:
class Named(ttag.Tag):
limit = ttag.Arg(keyword=True)
offset = ttag.Arg(keyword=True)
- Which would be used by:
- {% named offset 4 limit 12 %}
If an optional argument is not specified in the template, it will not be
added to the data dictionary. Alternately, use default
to have a default
value added to the data dictionary if an argument is not provided:
class NamedTag(ttag.Tag):
limit = ttag.Arg(default=100)
offset = ttag.Arg(required=False)
Argument Types¶
Arg
and its subclasses provide various other levels of parsing and
validation.
Arg¶
-
class
ttag.
Arg
(required=True, default=None, null=False, keyword=False, named=False)¶ A standard argument in a
Tag
. Used as a base class for all other argument classes.Parameters: - required –
Whether the argument is required as part of the tag definition in the template. Required positional arguments can not occur after optional ones.
Defaults to
True
. - default –
The default value for this argument if it is not specified.
If
None
and the field is required, an exception will be raised when the template is parsed.Defaults to
None
. - null –
Determines whether a value of
None
is an acceptable value for the argument resolution.When set to
False
, a value ofNone
or a missing context variable will cause aTemplateTagValidationError
when this argument is cleaned.Defaults to
False
. - keyword –
Make this a named argument, using an equals to separate the value from the argument name, for example,
{% tag limit=10 %}
.Defaults to
False
. - named –
Make this a named argument, using an space to separate the argument name from its value, for example,
{% tag limit 10 %}
.Defaults to
False
.
The
named
andkeyword
parameters can not both be set toTrue
.- required –
Casting Arguments¶
-
class
ttag.
IntegerArg
¶ Tries to cast the argument value to an integer, throwing a template error if this fails.
-
class
ttag.
StringArg
¶ Tries to cast the argument value to unicode, throwing a template error if this fails.
Validation Arguments¶
-
class
ttag.
IsInstanceArg
(..., cls, cls_name)¶ Validates that the argument is an instance of the provided class (
cls
), otherwise throws a a template error, using thecls_name
in the error message.For example:
date = IsInstanceArg(cls=datetime.date, cls_name=_('Date'))
-
class
ttag.
DateTimeArg
¶ Validates that the argument is a
datetime
instance, otherwise throws a template error.
-
class
ttag.
DateArg
¶ Validates that the argument is a
date
instance, otherwise throws a template error.
-
class
ttag.
TimeArg
¶ Validates that the argument is a
time
instance, otherwise throws a template error.
-
class
ttag.
ModelInstanceArg
(..., model)¶ Validates that the passed in value is an instance of the specified
Model
class. It requires a single additional named argument.Parameters: model – The Model
class you want to validate against.
Other Arguments¶
-
class
ttag.
BooleanArg
¶ A “flag” argument which doesn’t consume any additional tokens.
If it is not defined in the tag, the argument value will not exist in the resolved data dictionary.
For example:
class Cool(ttag.Tag) cool = ttag.BooleanArg() def output(self, data): if 'cool' in data: return "That's cool!" else: return "Uncool."
-
class
ttag.
BasicArg
¶ A simpler argument which doesn’t compile its value as a
FilterExpression
.Example usage:
class GetUsers(ttag.Tag): as_ = ttag.BasicArg() def render(self, context): data = self.resolve(data) context[data['as']] = Users.objects.all() return ''
-
class
ttag.
ConstantArg
¶ An argument which expects it’s value to be a constant (non-compiled) value, usually used to enhance tag readability.
Cannot be a named or keyword argument.
Example usage:
class Range(ttag.Tag): start = ttag.IntegerArg() to_ = ttag.ConstantArg() finish = ttag.IntegerArg() def output(self, data): start = data['start'] finish = data['finish'] + 1 return ', '.join([str(num) for num in range(start, finish)])
-
class
ttag.
MultiArg
¶ Greedily parses all remaining positional arguments.
Stops when all the tag tokens tokens are consumed or named keyword argument is hit. For example:
class DotConcat(ttag.Tag): bits = ttag.MultiArg() default = ttag.Arg(named=True, required=False) def output(self, data): bits = [] default = data.get('default', '') for bit in data['bits']: bits.append([force_text(bit) or default]) return '.'.join(bits)
This tag could be used like this:
{% dot_concat "a" "" "c" default "X" %}
Resulting in
a.X.c
.
-
class
ttag.
KeywordsArg
(..., compact=True, verbose=False, compile_values=True)¶ Parses one or more additional tokens as keywords.
Parameters: - compact –
Use compact format. For example:
{% compact with foo=1 bar=2 %}
- verbose –
Use verbose format:
{% verbose with 1 as foo and 2 as bar %}
In verbose mode, the
and
is required for multiple arguments unlesscompact
is also set toTrue
(in which case theand
is optional). - compile_values – Compile keyword values as template variables (defaults to
True
).
If
verbose
andcompact
are set toTrue
, then either (or even both) formats are allowed. This is usually only used for backwards compatibility:{% mixed with foo=1 bar=2 %} {% mixed with 1 as foo and 2 as bar %} {% mixed with foo=1 and 2 as bar %}
- compact –