.. django-meio-easytags documentation master file, created by
sphinx-quickstart on Tue Feb 22 22:55:42 2011.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
django-meio-easytags
====================
An easy way to create custom template tags for Django's templating system.
EasyNode will take care of the template tag's parsing, resolving variable
and inspecting if the parameters are ok with the ``render_context`` signature.
It's almost like calling methods in Python.
Basic usage
-----------
Just subclass the EasyNode and create the method ``render_context`` and register
the template tag::
from django.template import Library
from easytags.node import EasyNode
register = Library()
class BasicNode(EasyNode):
def render_context(self, context):
return 'basic template tag'
register.tag('basic', BasicNode.parse)
Then load your template tags in your template and use it::
{% load my_template_tags %}
{% basic %}
Ok. It's easy to do with built-in django's ``Node``. In fact this case uses
almost nothing of the django-meio-easytags power. Let's take a look at a
more complex example.
EasyLibrary usage
-----------------
The ``easytags.EasyLibrary`` is a subclass of Django's default ``django.template.Library``.
It adds a method to create easy tags just defining a function very similar to the
``render_context`` above. Just do this::
from easytags import EasyLibrary
register = EasyLibrary()
def basic(context):
return u'basic template tag'
register.easytag(basic)
That's it. We just created our template tag. Pay atention that our register is an instance
of ``easytags.EasyLibrary``, not of ``django.template.Library``.
Custom template tag name
........................
You may set a custom name for your template tag just like you do with ordinary ``register.tag``::
register.easytag('my_fancy_name', basic)
register.easytag as decorator
.............................
You can register easy tags with decorators::
@register.easytag
def decorated(context):
return u'decorated'
And define the tag name inside the decorator::
@register.easytag(name='fancy_decorated')
def decorated(context):
return u'fancy decorated'
Accepts parameters
------------------------------------------------
You can also create a template tag that receives one or more parameters and
set default values to it like you do in Python methods::
from easytags import EasyLibrary
register = EasyLibrary()
def sum(context, arg1, arg2, arg3=0):
return int(arg1) + int(arg2) + int(arg3)
register.easytag(sum)
In this case, your template tag have two mandatory parameters (``arg1`` and
``arg2``) and one optional parameter (``arg3``) that defaults to ``0``. You
can use this template tag in any of these ways::
{% sum "1" "2" %}
{% sum "1" arg2="2" %}
{% sum arg1="1" arg2="2" %}
{% sum "1" "2" "3" %}
{% sum arg2="2" arg1="1 %}
That is the way you are already used to do in Python. The django-meio-easytags
parser will take care of verifying if your template tag accepts the parameters
defined and if it doesn't, it will raise a ``TemplateSyntaxError``. You don't
need to define anywere else which parameters your template tag accepts except
for the ``render_context`` signature definition.
Resolving context variable
..........................
Pay atention that in the example above, all parameters are defined as absolute
values, that is, inside double quotes. This is needed because django-meio-easytags
allows you to create template tags that accepts context variables as default::
{% sum variable1 "2" %}
The code above will resolve ``variable1`` in the context and use as first parameter
for the ``sum`` template tag.
Accepts *args
-------------
There's a very nice feature in python that makes it possible to create methods
that accepts infinite parameters. In django-meio-easytags it's possible too::
from easytags import EasyLibrary
register = EasyLibrary()
def join_lines(context, *args):
return u'
'.join(args)
register.easytag(join_lines)
With this tag you can join as many lines as you want::
{% join_lines "line1" %} # Outputs "line1"
{% join_lines "line1" "line2" %} # Outputs "line1
line2"
{% join_lines "line1" "line2" "lineN" %} # Outputs "line1
line2
lineN"
Accepts **kwargs
----------------
In python you may create methods that receives any named parameter and
django-meio-easytags supports it too::
from easytags import EasyLibrary
register = EasyLibrary()
def querystring(context, **kwargs):
return u'&'.join(u'%s=%s' % (k,v) for k, v in kwargs.items())
register.easytag(querystring)
With this tag you can build a querystring defining each key and value::
{% querystring key1="1" key2="2" %} # Outputs "key1=1&key2=2
Using `as` parameter
--------------------
Thats a common usage in template tags construction to use a parameter to define a
variable to receive the content generated by the rendering of the template tag. In
django-meio-easytags you can use `EasyAsNode` to achieve such a behavior. Just
override the `EasyAsNode` instead of `EasyNode` and use it in your templates like
this::
from django.template import Library
from easytags.node import EasyAsNode
register = Library()
class BasicAsNode(EasyAsNode):
def render_context(self, context):
return 'basic content to variable'
register.tag('basic', BasicAsNode.parse)
Then load your template tags in your template and use it::
{% load my_template_tags %}
{% basic as varname %}
And the Node will store the returning value from `render_context` in a context
variable name `varname`. Nice, but what about all the library stuff? I can't use
the `as` parameter and register it in EasyLibrary? Yes you can! Just create your
method and register it as an `easyastag`::
from easytags import EasyLibrary
register = EasyLibrary()
def basic(context):
return 'basic content to variable'
register.easyastag(basic)