Context Navigation

source: Dev/branches/rest-dojo-ui/client/dojox/dtl/README @ 256

Last change on this file since 256 was 256, checked in by hendrikvanantwerpen, 13 years ago
Reworked project structure based on REST interaction and Dojo library. As soon as this is stable, the old jQueryUI branch can be removed (it's kept for reference).
File size: 10.7 KB

Line
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.

Note: See TracBrowser for help on using the repository browser.

Download in other formats: