root / trunk / web / dojo / dojox / dtl / README @ 12
History | View | Annotate | Download (10.7 KB)
| 1 |
------------------------------------------------------------------------------- |
|---|---|
| 2 |
DojoX Django Template Language |
| 3 |
------------------------------------------------------------------------------- |
| 4 |
Version 0.0 |
| 5 |
Release date: 09/20/2007 |
| 6 |
------------------------------------------------------------------------------- |
| 7 |
Project state: experimental/feature incomplete |
| 8 |
------------------------------------------------------------------------------- |
| 9 |
Project authors |
| 10 |
Neil Roberts (pottedmeat@dojotoolkit.org) |
| 11 |
------------------------------------------------------------------------------- |
| 12 |
Project description |
| 13 |
|
| 14 |
The Django Template language uses a system of templates that can be compiled |
| 15 |
once and rendered indefinitely afterwards. It uses a simple system of tags |
| 16 |
and filters. |
| 17 |
|
| 18 |
This is a 1:1 match with the Django Template Language as outlined in |
| 19 |
http://www.djangoproject.com/documentation/templates/. All applicable tags and |
| 20 |
filters have been implemented (see below), along with new filters and tags as |
| 21 |
necessary (see below). |
| 22 |
|
| 23 |
The Django Template Language is intended within Django to only handle text. |
| 24 |
Our implementation is able to handle HTML in addition to text. Actually, the |
| 25 |
text and HTML portions of dojox.dtl are two separate layers, the HTML layer |
| 26 |
sits on top of the text layer (base). It's also been implemented in such a way |
| 27 |
that you have little to fear when moving your code from Django to dojox.dtl. |
| 28 |
Your existing templates should work, and will benefit from the massive |
| 29 |
performance gain of being able to manipulate nodes, rather than having to do |
| 30 |
clunky innerHTML swaps you would have to do with a text-only system. It also |
| 31 |
allows for new HTML-centric abilities, outlined below. |
| 32 |
|
| 33 |
Despite having two levels of complexity, if you write your tags correctly, they |
| 34 |
will work in both environments. |
| 35 |
------------------------------------------------------------------------------- |
| 36 |
Dependencies |
| 37 |
|
| 38 |
Base: |
| 39 |
dojox.string.Builder |
| 40 |
|
| 41 |
Date filters and tags: |
| 42 |
dojox.date.php |
| 43 |
|
| 44 |
Widget: |
| 45 |
dijit._Widget |
| 46 |
dijit._Container |
| 47 |
------------------------------------------------------------------------------- |
| 48 |
Installation instructions |
| 49 |
|
| 50 |
Grab the following from the Dojo SVN Repository: |
| 51 |
http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/dtl.js |
| 52 |
http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/dtl/* |
| 53 |
|
| 54 |
Install into the following directory structure: |
| 55 |
/dojox/dtl/ |
| 56 |
|
| 57 |
...which should be at the same level as your Dojo checkout. |
| 58 |
------------------------------------------------------------------------------- |
| 59 |
What's Been Done |
| 60 |
|
| 61 |
Note: HTML Unit Tests should only be around for the oddities of HTML, tag/filter |
| 62 |
code is the same for each environment with minor exceptions. Cloning of all tags |
| 63 |
should be tested inside a for loop. |
| 64 |
|
| 65 |
| Implemented | Tag | Text Unit Test | HTML Unit Test | |
| 66 |
| X | block | X | | |
| 67 |
| X | comment | X | | |
| 68 |
| X | cycle | X | | |
| 69 |
| X | debug | X | | |
| 70 |
| X | extends | X | | |
| 71 |
| X | filter | X | | |
| 72 |
| X | firstof | X | | |
| 73 |
| X | for | X | | |
| 74 |
| X | if | X | | |
| 75 |
| X | ifchanged | X | X | |
| 76 |
| X | ifequal | X | | |
| 77 |
| X | ifnotequal | X | | |
| 78 |
| X | include | X | X | |
| 79 |
| X | load | X | | |
| 80 |
| X | now | X | | |
| 81 |
| X | regroup | X | | |
| 82 |
| X | spaceless | X | X | |
| 83 |
| X | ssi | X | X | |
| 84 |
| X | templatetag | X | | |
| 85 |
| N/A | url | | | |
| 86 |
| X | widthratio | X | | |
| 87 |
| X | with | X | | |
| 88 |
|
| 89 |
| Implemented | Filter | Text Unit Test | HTML Unit Test | |
| 90 |
| X | add | X | | |
| 91 |
| X | addslashes | X | | |
| 92 |
| X | capfirst | X | | |
| 93 |
| X | center | X | | |
| 94 |
| X | cut | X | | |
| 95 |
| X | date | X | | |
| 96 |
| X | default | X | | |
| 97 |
| X | default_if_none | X | | |
| 98 |
| X | dictsort | X | | |
| 99 |
| X | dictsort_reversed | X | | |
| 100 |
| X | divisibleby | X | | |
| 101 |
| X | escape | X | | |
| 102 |
| X | filesizeformat | X | | |
| 103 |
| X | first | X | | |
| 104 |
| X | fix_ampersands | X | | |
| 105 |
| X | floatformat | X | | |
| 106 |
| X | get_digit | X | | |
| 107 |
| X | iriencode | X | | |
| 108 |
| X | join | X | | |
| 109 |
| X | length | X | | |
| 110 |
| X | length_is | X | | |
| 111 |
| X | linebreaks | X | | |
| 112 |
| X | linebreaksbr | X | | |
| 113 |
| X | linenumbers | X | | |
| 114 |
| X | ljust | X | | |
| 115 |
| X | lower | X | | |
| 116 |
| X | make_list | X | | |
| 117 |
| X | phone2numeric | X | | |
| 118 |
| X | pluralize | X | | |
| 119 |
| X | pprint | X | | |
| 120 |
| X | random | X | | |
| 121 |
| X | removetags | X | | |
| 122 |
| X | rjust | X | | |
| 123 |
| X | slice | X | | |
| 124 |
| X | slugify | X | | |
| 125 |
| X | stringformat | X | | |
| 126 |
| X | striptags | X | | |
| 127 |
| X | time | X | | |
| 128 |
| X | timesince | X | | |
| 129 |
| X | timeuntil | X | | |
| 130 |
| X | title | X | | |
| 131 |
| X | truncatewords | X | | |
| 132 |
| X | truncatewords_html | X | | |
| 133 |
| X | unordered_list | X | | |
| 134 |
| X | upper | X | | |
| 135 |
| X | urlencode | X | | |
| 136 |
| X | urlize | X | | |
| 137 |
| X | urlizetrunc | X | | |
| 138 |
| X | wordcount | X | | |
| 139 |
| X | wordwrap | X | | |
| 140 |
| X | yesno | X | | |
| 141 |
------------------------------------------------------------------------------- |
| 142 |
HTML-Specific Additions |
| 143 |
------------------------------------------------------------------------------- |
| 144 |
{%extends "shared:templates/template.html" %}
|
| 145 |
|
| 146 |
When using the {% extends %} tag, we don't always want to replace the parent
|
| 147 |
node in DOM. For example, if we have a list view and a detail view, but both |
| 148 |
share the same base template, we want it to share the parent template. This |
| 149 |
basically means that the same nodes will be used in the parent for both views. |
| 150 |
|
| 151 |
To use this, simply add "shared:" to the beginning of the specified template. |
| 152 |
------------------------------------------------------------------------------- |
| 153 |
<!--{% commented markup %}-->
|
| 154 |
|
| 155 |
Some browsers treat comment nodes as full fledged nodes. If performance is |
| 156 |
important to you, you can wrap your markup in comments. The comments will be |
| 157 |
automatically stripped for browsers that cannot support this. |
| 158 |
------------------------------------------------------------------------------- |
| 159 |
Attribute Tags |
| 160 |
|
| 161 |
If a tag name begins with "attr:" then it will be able to inject an object |
| 162 |
into the parsed template. (See dojox.dtl.tag.event.EventNode) |
| 163 |
|
| 164 |
onclick/onmouseover/etc attributes work by attaching to the rendering object. |
| 165 |
|
| 166 |
tstyle attribute allows for styles to be changed dynamically. Use them just |
| 167 |
like a "style" attribute. |
| 168 |
|
| 169 |
attach attribute attaches the node to the rendering object. |
| 170 |
------------------------------------------------------------------------------- |
| 171 |
New Context Functions |
| 172 |
|
| 173 |
setThis() and getThis() returns the object "in charge" of the current rendering. |
| 174 |
This is used so that we can attach events. |
| 175 |
|
| 176 |
mixin() and filter() clone the current context, and either add to or reduce |
| 177 |
the keys in the context. |
| 178 |
------------------------------------------------------------------------------- |
| 179 |
Buffers |
| 180 |
|
| 181 |
Both the base and HTML versions of dojox.dtl use buffers. The base version uses |
| 182 |
dojox.string.Builder and the HTML version uses dojox.dtl.DomBuffer. |
| 183 |
|
| 184 |
The HTML buffer has several calls important to rendering: |
| 185 |
|
| 186 |
setParent/getParent/concat/remove: |
| 187 |
|
| 188 |
setParent and concat are used in order to render our HTML. As we move through |
| 189 |
the parsed template, different nodes change the parent or add on to the |
| 190 |
current parent. getParent is useful in things like the attribute tags, since |
| 191 |
they can use getParent to find the node that they're an attribute on. remove is |
| 192 |
used during unrendering. |
| 193 |
|
| 194 |
setAttribute: |
| 195 |
|
| 196 |
Sets an attribute on the current parent |
| 197 |
------------------------------------------------------------------------------- |
| 198 |
Tags Need clone/unrender Functions. |
| 199 |
|
| 200 |
One of the biggest challenges of getting dojox.dtl to work in an HTML |
| 201 |
environment was logic blocks. Nodes and objects inside a for loop need to be |
| 202 |
cloned, they can't simply be re-rendered, especially if they involve a Node. |
| 203 |
Also, in the case of an if/else block, we need to be able to not just render |
| 204 |
one of the blocks, but also unrender the second. |
| 205 |
|
| 206 |
This is really simple code, a good example is the dojox.dtl.DomNode |
| 207 |
object. Each function in this object is only one line long. |