------------------------------------------------------------------------------- DojoX Django Template Language ------------------------------------------------------------------------------- Version 0.0 Release date: 09/20/2007 ------------------------------------------------------------------------------- Project state: experimental/feature incomplete ------------------------------------------------------------------------------- Project authors Neil Roberts (pottedmeat@dojotoolkit.org) ------------------------------------------------------------------------------- Project description The Django Template language uses a system of templates that can be compiled once and rendered indefinitely afterwards. It uses a simple system of tags and filters. This is a 1:1 match with the Django Template Language as outlined in http://www.djangoproject.com/documentation/templates/. All applicable tags and filters have been implemented (see below), along with new filters and tags as necessary (see below). The Django Template Language is intended within Django to only handle text. Our implementation is able to handle HTML in addition to text. Actually, the text and HTML portions of dojox.dtl are two separate layers, the HTML layer sits on top of the text layer (base). It's also been implemented in such a way that you have little to fear when moving your code from Django to dojox.dtl. Your existing templates should work, and will benefit from the massive performance gain of being able to manipulate nodes, rather than having to do clunky innerHTML swaps you would have to do with a text-only system. It also allows for new HTML-centric abilities, outlined below. Despite having two levels of complexity, if you write your tags correctly, they will work in both environments. ------------------------------------------------------------------------------- Dependencies Base: dojox.string.Builder Date filters and tags: dojox.date.php Widget: dijit._Widget dijit._Container ------------------------------------------------------------------------------- Installation instructions Grab the following from the Dojo SVN Repository: http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/dtl.js http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/dtl/* Install into the following directory structure: /dojox/dtl/ ...which should be at the same level as your Dojo checkout. ------------------------------------------------------------------------------- What's Been Done Note: HTML Unit Tests should only be around for the oddities of HTML, tag/filter code is the same for each environment with minor exceptions. Cloning of all tags should be tested inside a for loop. | Implemented | Tag | Text Unit Test | HTML Unit Test | | X | block | X | | | X | comment | X | | | X | cycle | X | | | X | debug | X | | | X | extends | X | | | X | filter | X | | | X | firstof | X | | | X | for | X | | | X | if | X | | | X | ifchanged | X | X | | X | ifequal | X | | | X | ifnotequal | X | | | X | include | X | X | | X | load | X | | | X | now | X | | | X | regroup | X | | | X | spaceless | X | X | | X | ssi | X | X | | X | templatetag | X | | | N/A | url | | | | X | widthratio | X | | | X | with | X | | | Implemented | Filter | Text Unit Test | HTML Unit Test | | X | add | X | | | X | addslashes | X | | | X | capfirst | X | | | X | center | X | | | X | cut | X | | | X | date | X | | | X | default | X | | | X | default_if_none | X | | | X | dictsort | X | | | X | dictsort_reversed | X | | | X | divisibleby | X | | | X | escape | X | | | X | filesizeformat | X | | | X | first | X | | | X | fix_ampersands | X | | | X | floatformat | X | | | X | get_digit | X | | | X | iriencode | X | | | X | join | X | | | X | length | X | | | X | length_is | X | | | X | linebreaks | X | | | X | linebreaksbr | X | | | X | linenumbers | X | | | X | ljust | X | | | X | lower | X | | | X | make_list | X | | | X | phone2numeric | X | | | X | pluralize | X | | | X | pprint | X | | | X | random | X | | | X | removetags | X | | | X | rjust | X | | | X | slice | X | | | X | slugify | X | | | X | stringformat | X | | | X | striptags | X | | | X | time | X | | | X | timesince | X | | | X | timeuntil | X | | | X | title | X | | | X | truncatewords | X | | | X | truncatewords_html | X | | | X | unordered_list | X | | | X | upper | X | | | X | urlencode | X | | | X | urlize | X | | | X | urlizetrunc | X | | | X | wordcount | X | | | X | wordwrap | X | | | X | yesno | X | | ------------------------------------------------------------------------------- HTML-Specific Additions ------------------------------------------------------------------------------- {%extends "shared:templates/template.html" %} When using the {% extends %} tag, we don't always want to replace the parent node in DOM. For example, if we have a list view and a detail view, but both share the same base template, we want it to share the parent template. This basically means that the same nodes will be used in the parent for both views. To use this, simply add "shared:" to the beginning of the specified template. ------------------------------------------------------------------------------- Some browsers treat comment nodes as full fledged nodes. If performance is important to you, you can wrap your markup in comments. The comments will be automatically stripped for browsers that cannot support this. ------------------------------------------------------------------------------- Attribute Tags If a tag name begins with "attr:" then it will be able to inject an object into the parsed template. (See dojox.dtl.tag.event.EventNode) onclick/onmouseover/etc attributes work by attaching to the rendering object. tstyle attribute allows for styles to be changed dynamically. Use them just like a "style" attribute. attach attribute attaches the node to the rendering object. ------------------------------------------------------------------------------- New Context Functions setThis() and getThis() returns the object "in charge" of the current rendering. This is used so that we can attach events. mixin() and filter() clone the current context, and either add to or reduce the keys in the context. ------------------------------------------------------------------------------- Buffers Both the base and HTML versions of dojox.dtl use buffers. The base version uses dojox.string.Builder and the HTML version uses dojox.dtl.DomBuffer. The HTML buffer has several calls important to rendering: setParent/getParent/concat/remove: setParent and concat are used in order to render our HTML. As we move through the parsed template, different nodes change the parent or add on to the current parent. getParent is useful in things like the attribute tags, since they can use getParent to find the node that they're an attribute on. remove is used during unrendering. setAttribute: Sets an attribute on the current parent ------------------------------------------------------------------------------- Tags Need clone/unrender Functions. One of the biggest challenges of getting dojox.dtl to work in an HTML environment was logic blocks. Nodes and objects inside a for loop need to be cloned, they can't simply be re-rendered, especially if they involve a Node. Also, in the case of an if/else block, we need to be able to not just render one of the blocks, but also unrender the second. This is really simple code, a good example is the dojox.dtl.DomNode object. Each function in this object is only one line long.