| 124 | | h3. design should be fun |
|---|
| 125 | | |
|---|
| 126 | | It' is very exciting to think of a new templating language. One of the goals we have is to make the template easily editable by graphic designers. A designer will have to add some ?Lorem ipsum? placeholder text, eventually copied from "lipsum":http://lipsum.com/. If he doesn't, this is what happens : |
|---|
| 127 | | |
|---|
| 128 | | The 'zafu' template |
|---|
| 129 | | |
|---|
| 130 | | <code lang='zafu'><h2><z:show attr=':v_title'/></h2> |
|---|
| 131 | | <z:children> |
|---|
| 132 | | <ul> |
|---|
| 133 | | <z:each><li><z:link/></li></z:each> |
|---|
| 134 | | </ul> |
|---|
| 135 | | </z:children> |
|---|
| 136 | | </code> |
|---|
| 137 | | |
|---|
| 138 | | renders like this in a web browser or wysiwyg editor : |
|---|
| 139 | | |
|---|
| 140 | | <div class='box' style='font-size:small; padding:0;'> |
|---|
| 141 | | <h3 style='margsrc:0;'><z:show attr=':v_title'/></h3> |
|---|
| 142 | | <z:children> |
|---|
| 143 | | <ul> |
|---|
| 144 | | <z:each><li><z:link/></li></z:each> |
|---|
| 145 | | </ul> |
|---|
| 146 | | </z:children> |
|---|
| 147 | | </div> |
|---|
| 148 | | |
|---|
| 149 | | This is not terrible to create stunning designs. |
|---|
| 150 | | |
|---|
| 151 | | The same example with placeholder text instead of empty tags (title, link): |
|---|
| 152 | | |
|---|
| 153 | | <code lang='zafu' class='large'><h3><z:show attr=':v_title'>qui dolorem</z:show></h3> |
|---|
| 154 | | <z:children> |
|---|
| 155 | | <ul> |
|---|
| 156 | | <z:each><li><z:link><a href='#'>ipsum quia</a></z:link></li></z:each> |
|---|
| 157 | | <z:each><li><z:link><a href='#'>dolor sit</a></z:link></li></z:each> |
|---|
| 158 | | </ul> |
|---|
| 159 | | </z:children> |
|---|
| 160 | | </code> |
|---|
| 161 | | |
|---|
| 162 | | becomes : |
|---|
| 163 | | |
|---|
| 164 | | <div class='box' style='font-size:small;'> |
|---|
| 165 | | <h3 style='margsrc:0;'><z:show attr=':v_title'>qui dolorem</z:show></h3> |
|---|
| 166 | | <z:children> |
|---|
| 167 | | <ul> |
|---|
| 168 | | <z:each><li><z:link><a href='#'>ipsum quia</a></z:link></li></z:each> |
|---|
| 169 | | <z:each><li><z:link><a href='#'>dolor sit</a></z:link></li></z:each> |
|---|
| 170 | | </ul> |
|---|
| 171 | | </z:children> |
|---|
| 172 | | </div> |
|---|
| 173 | | |
|---|
| 174 | | *Great !* We can test the template without rendering it ! Now our rendering system must be clever enough to remove the content between 'block' tags (title, link, ...). This seems easy, but what about the multiple 'each' to create the list ? We could skip the second 'each', but this would be bad if we want to render a table of contents followed by the content itself : |
|---|
| 175 | | |
|---|
| 176 | | <code lang='zafu'><z:each><z:show attr=':v_title'/></z:each> |
|---|
| 177 | | <z:each><h3><z:show attr=':v_title'/></h3> |
|---|
| 178 | | <div><z:text/></div></z:each> |
|---|
| 179 | | </code> |
|---|
| 180 | | |
|---|
| 181 | | We will use two tricks to skip content. The @zafu|<z:lorem>@ tag, will remove any content it contains during compilation, and the @zafu|<z:each lorem='true'>@ parameter will transform any block tag (each, children, ...) into a dummy. The first example would then be written as : |
|---|
| 182 | | |
|---|
| 183 | | <code lang='zafu' class='large'><h2><z:show attr=':v_title'>qui dolorem</z:show></h2> |
|---|
| 184 | | <z:children> |
|---|
| 185 | | <ul> |
|---|
| 186 | | <z:each><li><z:link><a href='#'>ipsum quia</a></z:link></li></z:each> |
|---|
| 187 | | <z:each lorem='true'><li> ... ipsum quia ... </li></z:each> |
|---|
| 188 | | <z:lorem><li><a href='#'>adipisci velit</a></li></z:lorem> |
|---|
| 189 | | </ul> |
|---|
| 190 | | </z:children> |
|---|
| 191 | | </code> |
|---|
| 192 | | |
|---|
| 193 | | Which compiles as : |
|---|
| 194 | | |
|---|
| 195 | | <code lang='erb' class='large'> |
|---|
| 196 | | <h3><%= @node.version[:title] %></h3> |
|---|
| 197 | | <% if var1 = @node.children -%> |
|---|
| 198 | | <ul> |
|---|
| 199 | | <% var1.each do |var2| -%><li><%= make_link(var2) %></li><% end -%> |
|---|
| 200 | | </ul> |
|---|
| 201 | | <% end -%> |
|---|
| 202 | | </code> |
|---|
| 203 | | |
|---|
| 204 | | Notice how all the _lorem ipsum_ blah blah has been simply stripped off. |
|---|
| 205 | | |
|---|
| 206 | | h3. templates should include reusable code |
|---|
| 207 | | |
|---|
| 208 | | Let's follow the conventions used in other programming languages. Inserting some template into another is done with the @include@ tag : |
|---|
| 209 | | |
|---|
| 210 | | <code lang='zafu'><z:include template='menu'/> |
|---|
| 211 | | or |
|---|
| 212 | | <z:include template='menu/sub'/> |
|---|
| 213 | | </code> |
|---|
| 214 | | |
|---|
| 215 | | |
|---|
| 216 | | Templates specified by their name or by a path without a leading slash are found in the current template's folder : |
|---|
| 217 | | |
|---|
| 218 | | |
|---|
| 219 | | !<.22.full! |
|---|
| 220 | | |
|---|
| 221 | | * _default_ if rendering __default.html_ |
|---|
| 222 | | * _menu_ if rendering __menu.html_ |
|---|
| 223 | | * _funny_ if rendering __funny.html_ |
|---|
| 224 | | |
|---|
| 225 | | When specifying a template by a path starting with a slash (@zafu|<z:include template='/funny'/>@), the template is searched as a direct child of the _templates_ root node where all the template objects *must* live. |
|---|
| 226 | | |
|---|
| 227 | | |
|---|
| 228 | | h3(clear). sharing templates |
|---|
| 229 | | |
|---|
| 230 | | Visitors can *download* any template node (if they have read access to the node). When downloading a template, Zena creates a tar archive containing the template and all it's descendants. For example, downloading _default_ would provide a folder called _default_ containing the following files : |
|---|
| 231 | | |
|---|
| 232 | | !<.23.full! |
|---|
| 233 | | |
|---|
| 234 | | The main file must have the same name as the folder with a leading underscore. |
|---|
| 235 | | |
|---|
| 236 | | *Uploading* is like creating/editing a document: you upload the tar archive and all the children nodes are created/updated for you (I still have to implement all this.. but that's the goal). |
|---|
| 237 | | |
|---|
| 238 | | You can *edit* the template just like any other node (templates are just text). |
|---|
| 239 | | |
|---|
| 240 | | h3. css ? |
|---|
| 241 | | |
|---|
| 242 | | CSS files are just a special kind of templates. Tags to link to a stylesheet use the same naming conventions as with the include tag. |
|---|
| 243 | | |
|---|
| 244 | | <code lang='zafu' class='large'><z:stylesheet template='/funny/fun'/> |
|---|
| 245 | | will become |
|---|
| 246 | | <link rel='stylesheet' type='text/css' href='/stylesheets/funny_fun.css'/></code> |
|---|
| 247 | | |
|---|
| 248 | | h3. Code, monkey ! |
|---|
| 249 | | |
|---|
| 250 | | This looks great on the 'paper', we hope it will be even more fun in real. |
|---|
| 251 | | |
|---|
| 252 | | *PS:* the 'download/upload' mechanism used for templates could be extended to other groups of documents (images to make a gallery for example). |
|---|
| 253 | | |
|---|
| 254 | | *PPS:* the template should be compiled once for every language to reduce translation calls when rendering. It could be store as 'default.en.rhtml', 'default.fr.rhtml', ... |
|---|
| | 124 | The syntax is inspired by ?subversion?:Subversion_%28software%29 |
|---|
| | 125 | res: "<p>The syntax is inspired by [make_wiki_link title:|subversion| url:|Subversion_%28software%29|]</p>" |
|---|