Writing and Registering Tags and Filters
The actual filter functions are identical in terms of structure to the way they are implemented in Django. What this means is that Django's documentation is great for learning how to write a filter, and doesn't need to be rewritten here
Tags work in the following way: a registered tag is passed the parser object, and the tag string, and is tasked with returning an object that obeys a specific interface. This is how they are implemented in Django, so once again, their documentation will go a long way toward understanding how to write a tag.
The one distinct difference between the two system is rendering a NodeList. The expected behavior would be to pass it the context and buffer objects that the render function accepts, but you must also pass its own instance (this) as the third parameter. Without this, there could be unexpected behavior when rendering in an HTML environment. You should also clone nodelists and then render them, rather than taking the re-rending approach of Django's normal system. Because the rendering in HTML results in a DOM tree, re-rendering without cloning would change the same nodes over and over.
As mentioned earlier, there is a new tag type in the HTML version of the compiler. If you've registered an attribute-based tag, you will be passed a null parser object, and the string contents of the attribute tag are prefixed with the attribute name. What this means is that, for example, in the case of an attach attribute that looks like attach="varName", the string that is passed is "attach varName". This way, you can register your function with a regular expression, but see exactly what was matched.
The only piece of the interface you have to implement for the text-based version is the render function. If your tag will appear in an HTML environment, you must add an unrender and clone function. The unrender function is tasked with removing a node from the DOM if one was previously added, or to tell the "swallowed" nodes to unrender. The clone function should duplicate the object. Note that the same tags are used in both the text and HTML versions of the compiler, so your functions should be written with this in mind.
Registering tags/filters looks like this:
Obviously, registering a tag would use dojox.dtl.register.tag. The first parameter is the require statement to call if we encounter one of these tags or filters. The second parameter is the base object on which these functions are stored. And the final parameter is an array of function names, or RegExp/function name pairs. Since some words are "reserved words", if we can't find the function on your object, we check for the function name with an underscore on the end of it.
If you write a custom set of tags and filters, the way to use them is exactly the same as in Django: the load tag. At the top of your template, add {% load namespace.tags namespace.filters etc %}
. You should register your tags and filters in the same file as you declare them, and where you put the registration code doesn't matter, it can be before or after your object declarations.
- Printer-friendly version
- Login or register to post comments
- Unsubscribe post
nevermind....
[ comment deleted by author ]