Blame | Last modification | View Log | RSS feed
-------------------------------------------------------------------------------DojoX Django Template Language-------------------------------------------------------------------------------Version 0.0Release date: 09/20/2007-------------------------------------------------------------------------------Project state: experimental/feature incomplete-------------------------------------------------------------------------------Project authorsNeil Roberts (pottedmeat@dojotoolkit.org)-------------------------------------------------------------------------------Project descriptionThe Django Template language uses a system of templates that can be compiledonce and rendered indefinitely afterwards. It uses a simple system of tagsand filters.This aims to be a 1:1 match with the Django Template Language as outlined inhttp://www.djangoproject.com/documentation/templates/. Many common tags andfilters have been implemented (see below), along with new filters and tags asnecessary (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, thetext and HTML portions of dojox.dtl are two separate layers, the HTML layersits on top of the text layer (base). It's also been implemented in such a waythat you have little to fear when moving your code from Django to dojox.dtl.Your existing templates should work, and will benefit from the massiveperformance gain of being able to manipulate nodes, rather than having to doclunky innerHTML swaps you would have to do with a text-only system. It alsoallows for new HTML-centric abilities, outlined below.Despite having two levels of complexity, if you write your tags correctly, theywill work in both environments.-------------------------------------------------------------------------------DependenciesBase:dojox.string.BuilderDate filters and tags:dojox.date.phpWidget:dijit._Widgetdijit._Container-------------------------------------------------------------------------------Installation instructionsGrab the following from the Dojo SVN Repository:http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/dtl.jshttp://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| 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 | || | firstof | | || X | for | | || X | if | | || | ifchanged | | || | ifequal | | || | ifnotequal | | || | include | | || | load | | || | now | | || | regroup | | || | spaceless | | || | ssi | | || | templatetag | | || | url | | || | widthratio | | || | with | | || 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 parentnode in DOM. For example, if we have a list view and a detail view, but bothshare the same base template, we want it to share the parent template. Thisbasically 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.-------------------------------------------------------------------------------<!--{% commented markup %}-->Some browsers treat comment nodes as full fledged nodes. If performance isimportant to you, you can wrap your markup in comments. The comments will beautomatically stripped for browsers that cannot support this.-------------------------------------------------------------------------------Attribute TagsIf a tag name begins with "attr:" then it will be able to inject an objectinto 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 justlike a "style" attribute.attach attribute attaches the node to the rendering object.-------------------------------------------------------------------------------New Context FunctionssetThis() 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 reducethe keys in the context.-------------------------------------------------------------------------------BuffersBoth the base and HTML versions of dojox.dtl use buffers. The base version usesdojox.string.Builder and the HTML version uses dojox.dtl.HtmlBuffer.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 throughthe parsed template, different nodes change the parent or add on to thecurrent parent. getParent is useful in things like the attribute tags, sincethey can use getParent to find the node that they're an attribute on. remove isused 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 HTMLenvironment was logic blocks. Nodes and objects inside a for loop need to becloned, 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 renderone of the blocks, but also unrender the second.This is really simple code, a good example is the dojox.dtl.HtmlNodeobject. Each function in this object is only one line long.