git.pond.sub.org Git - eow/blob - static/dojo-release-1.1.1/dojox/dtl/README

   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.HtmlBuffer.
 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.HtmlNode
 207 object. Each function in this object is only one line long.