id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
625	[patch] Add template decorators	rjwittams	Adrian Holovaty	"This patch includes two decorators for making template tags easier to create. 

@simple_tag : 

This one is for converting functions that return a string into template tags. eg.

definition:

@simple_tag
def monkey_tag(verb):
    return ""I %s no evil"" % verb

use:

{% monkey_tag ""hear""%}

arguments are resolved using template.resolve_variable -> ie currently limited to variable references and constant strings. 

@inclusion_tag 

This decorator turns a function returning a dictionary into a template tag that renders another template inline using that dictionary as the context. The decorator takes three arguments : 
path - required path to template 
context_class - kwarg to override the default context created 
takes_context - kwarg boolean. If true, the first argument of the function must be called 'context', and the context of the calling template will be passed into this argument. Useful if it is heavily context dependent and there would be a huge number of arguments. 

The point of not just using the parent context is to make it easy to tell which context variables are used in which templates, ie avoid dynamic scoping hell.

eg: 

@inclusion_tag('farming/cow_detail')
def cow_display(cow):
    return {
       'name': cow.name,
       'similar': find_similar_cows(cow)
    }

template : 'farming/cow_detail'
<div>
<h2>{{name}}</h2>
<b> similar cows: </b>
{%for cow in similar %}
   <p>{{cow.name}}</p>
{% end for %}
</div>

use:
{% cow_display cow %}
"	enhancement	new	Template system		normal				Unreviewed	1	0	0	0	0	0