| 2150 |
mathias |
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 aims to be a 1:1 match with the Django Template Language as outlined in
|
|
|
19 |
http://www.djangoproject.com/documentation/templates/. Many common 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 |
| Implemented | Tag | Text Unit Test | HTML Unit Test |
|
|
|
62 |
| X | block | X | |
|
|
|
63 |
| X | comment | X | |
|
|
|
64 |
| X | cycle | X | |
|
|
|
65 |
| X | debug | X | |
|
|
|
66 |
| X | extends | X | |
|
|
|
67 |
| X | filter | X | |
|
|
|
68 |
| | firstof | | |
|
|
|
69 |
| X | for | | |
|
|
|
70 |
| X | if | | |
|
|
|
71 |
| | ifchanged | | |
|
|
|
72 |
| | ifequal | | |
|
|
|
73 |
| | ifnotequal | | |
|
|
|
74 |
| | include | | |
|
|
|
75 |
| | load | | |
|
|
|
76 |
| | now | | |
|
|
|
77 |
| | regroup | | |
|
|
|
78 |
| | spaceless | | |
|
|
|
79 |
| | ssi | | |
|
|
|
80 |
| | templatetag | | |
|
|
|
81 |
| | url | | |
|
|
|
82 |
| | widthratio | | |
|
|
|
83 |
| | with | | |
|
|
|
84 |
|
|
|
85 |
| Implemented | Filter | Text Unit Test | HTML Unit Test |
|
|
|
86 |
| X | add | X | |
|
|
|
87 |
| X | addslashes | X | |
|
|
|
88 |
| X | capfirst | X | |
|
|
|
89 |
| X | center | X | |
|
|
|
90 |
| X | cut | X | |
|
|
|
91 |
| X | date | X | |
|
|
|
92 |
| X | default | X | |
|
|
|
93 |
| X | default_if_none | X | |
|
|
|
94 |
| X | dictsort | X | |
|
|
|
95 |
| X | dictsort_reversed | X | |
|
|
|
96 |
| X | divisibleby | X | |
|
|
|
97 |
| X | escape | X | |
|
|
|
98 |
| X | filesizeformat | X | |
|
|
|
99 |
| X | first | X | |
|
|
|
100 |
| X | fix_ampersands | X | |
|
|
|
101 |
| X | floatformat | X | |
|
|
|
102 |
| X | get_digit | X | |
|
|
|
103 |
| X | iriencode | X | |
|
|
|
104 |
| X | join | X | |
|
|
|
105 |
| X | length | X | |
|
|
|
106 |
| X | length_is | X | |
|
|
|
107 |
| X | linebreaks | X | |
|
|
|
108 |
| X | linebreaksbr | X | |
|
|
|
109 |
| X | linenumbers | X | |
|
|
|
110 |
| X | ljust | X | |
|
|
|
111 |
| X | lower | X | |
|
|
|
112 |
| X | make_list | X | |
|
|
|
113 |
| X | phone2numeric | X | |
|
|
|
114 |
| X | pluralize | X | |
|
|
|
115 |
| X | pprint | X | |
|
|
|
116 |
| X | random | X | |
|
|
|
117 |
| X | removetags | X | |
|
|
|
118 |
| X | rjust | X | |
|
|
|
119 |
| X | slice | X | |
|
|
|
120 |
| X | slugify | X | |
|
|
|
121 |
| X | stringformat | X | |
|
|
|
122 |
| X | striptags | X | |
|
|
|
123 |
| X | time | X | |
|
|
|
124 |
| X | timesince | X | |
|
|
|
125 |
| X | timeuntil | X | |
|
|
|
126 |
| X | title | X | |
|
|
|
127 |
| X | truncatewords | X | |
|
|
|
128 |
| X | truncatewords_html | X | |
|
|
|
129 |
| X | unordered_list | X | |
|
|
|
130 |
| X | upper | X | |
|
|
|
131 |
| X | urlencode | X | |
|
|
|
132 |
| X | urlize | X | |
|
|
|
133 |
| X | urlizetrunc | X | |
|
|
|
134 |
| X | wordcount | X | |
|
|
|
135 |
| X | wordwrap | X | |
|
|
|
136 |
| X | yesno | X | |
|
|
|
137 |
-------------------------------------------------------------------------------
|
|
|
138 |
HTML-Specific Additions
|
|
|
139 |
-------------------------------------------------------------------------------
|
|
|
140 |
{%extends "shared:templates/template.html" %}
|
|
|
141 |
|
|
|
142 |
When using the {% extends %} tag, we don't always want to replace the parent
|
|
|
143 |
node in DOM. For example, if we have a list view and a detail view, but both
|
|
|
144 |
share the same base template, we want it to share the parent template. This
|
|
|
145 |
basically means that the same nodes will be used in the parent for both views.
|
|
|
146 |
|
|
|
147 |
To use this, simply add "shared:" to the beginning of the specified template.
|
|
|
148 |
-------------------------------------------------------------------------------
|
|
|
149 |
<!--{% commented markup %}-->
|
|
|
150 |
|
|
|
151 |
Some browsers treat comment nodes as full fledged nodes. If performance is
|
|
|
152 |
important to you, you can wrap your markup in comments. The comments will be
|
|
|
153 |
automatically stripped for browsers that cannot support this.
|
|
|
154 |
-------------------------------------------------------------------------------
|
|
|
155 |
Attribute Tags
|
|
|
156 |
|
|
|
157 |
If a tag name begins with "attr:" then it will be able to inject an object
|
|
|
158 |
into the parsed template. (See dojox.dtl.tag.event.EventNode)
|
|
|
159 |
|
|
|
160 |
onclick/onmouseover/etc attributes work by attaching to the rendering object.
|
|
|
161 |
|
|
|
162 |
tstyle attribute allows for styles to be changed dynamically. Use them just
|
|
|
163 |
like a "style" attribute.
|
|
|
164 |
|
|
|
165 |
attach attribute attaches the node to the rendering object.
|
|
|
166 |
-------------------------------------------------------------------------------
|
|
|
167 |
New Context Functions
|
|
|
168 |
|
|
|
169 |
setThis() and getThis() returns the object "in charge" of the current rendering.
|
|
|
170 |
This is used so that we can attach events.
|
|
|
171 |
|
|
|
172 |
mixin() and filter() clone the current context, and either add to or reduce
|
|
|
173 |
the keys in the context.
|
|
|
174 |
-------------------------------------------------------------------------------
|
|
|
175 |
Buffers
|
|
|
176 |
|
|
|
177 |
Both the base and HTML versions of dojox.dtl use buffers. The base version uses
|
|
|
178 |
dojox.string.Builder and the HTML version uses dojox.dtl.HtmlBuffer.
|
|
|
179 |
|
|
|
180 |
The HTML buffer has several calls important to rendering:
|
|
|
181 |
|
|
|
182 |
setParent/getParent/concat/remove:
|
|
|
183 |
|
|
|
184 |
setParent and concat are used in order to render our HTML. As we move through
|
|
|
185 |
the parsed template, different nodes change the parent or add on to the
|
|
|
186 |
current parent. getParent is useful in things like the attribute tags, since
|
|
|
187 |
they can use getParent to find the node that they're an attribute on. remove is
|
|
|
188 |
used during unrendering.
|
|
|
189 |
|
|
|
190 |
setAttribute:
|
|
|
191 |
|
|
|
192 |
Sets an attribute on the current parent
|
|
|
193 |
-------------------------------------------------------------------------------
|
|
|
194 |
Tags Need clone/unrender Functions.
|
|
|
195 |
|
|
|
196 |
One of the biggest challenges of getting dojox.dtl to work in an HTML
|
|
|
197 |
environment was logic blocks. Nodes and objects inside a for loop need to be
|
|
|
198 |
cloned, they can't simply be re-rendered, especially if they involve a Node.
|
|
|
199 |
Also, in the case of an if/else block, we need to be able to not just render
|
|
|
200 |
one of the blocks, but also unrender the second.
|
|
|
201 |
|
|
|
202 |
This is really simple code, a good example is the dojox.dtl.HtmlNode
|
|
|
203 |
object. Each function in this object is only one line long.
|