-------------------------------------------------------------------------------
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.
-------------------------------------------------------------------------------
<!--{% commented markup %}-->

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.