Andrej Cimperšek - diploma

-------------------------------------------------------------------------------

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.