Permalink
Browse files

updated README

  • Loading branch information...
1 parent fe07e1b commit 45a02e73daec4f494ed3c92489dc06b265c90769 @georgi committed Sep 16, 2008
Showing with 78 additions and 47 deletions.
  1. +78 −47 README.md
View
125 README.md
@@ -2,14 +2,15 @@ Patroon - a Javascript Template Engine
======================================
Patroon is a template engine written in Javascript in about 100 lines
-of code. It takes existing DOM nodes annotated with CSS classes and
-expand a data object according to simple rules. Additionally you may
-use traditional string interpolation inside attribute values and text
-nodes.
+of code. It takes existing DOM nodes annotated with context attributes
+and expand a data object according to simple rules. Additionally you
+may use traditional string interpolation inside attribute values and
+text nodes.
-### Example
+### The Data
-Comments in this blog are stored as a list of JSON objects, I wrote about it [here][1]. So think about a data object like this:
+Comments in this blog are stored as a list of JSON objects, I wrote
+about it [here][1]. So think about a data object like this:
var data = {
comment: [{
@@ -26,86 +27,116 @@ Comments in this blog are stored as a list of JSON objects, I wrote about it [he
};
+### The Template
+
This data will be expanded with help of following template:
<div class="comments">
<div id="comments-template">
- <div class="comment">
- <div class="_ top">
- <a class="_" href="{website}">{name}</a> said
- <a class="_" title="{time}"></a>:
+ <div contect="comment" class="comment">
+ <div class="top">
+ {website.length > 0 ? linkTo(name, website) : name} said
+ <a title="{time}"></a>:
</div>
- <div class="text"></div>
+ <div class="text">
+ {text}
+ </div>
</div>
</div>
</div>
-The javascript to actually execute this template looks like this:
-
- // The comments template will be removed from the DOM!
- var template = new Template('comments-template');
-
- // template will result in a new DOM node
- var result = template.expand(data);
-
- // insert the resulting node into the comments container
- var container = document.getElementsByClassName('comments')[0];
- container.appendChild(result);
+### Usage
-Using jQuery the code gets a bit cleaner:
+The javascript to actually execute this template looks like this:
// The comments template will be removed from the DOM!
var template = new Template('comments-template');
// Expand the template into the comments section
$('.comments').expand(template, data);
-
-
-
-### Basic Rules
-There are 5 basic rules:
-* Strings and Numbers are inserted by innerHTML to the current node.
+If you don't want to use jQuery, please look at the end of this article.
-* Arrays repeat the current node and process its elements recursively in same scope.
-* Objects trigger a class name lookup by property name. The value of each property is expanded recursively in new scope.
+### Output
-* Code will be evaluated for text surounded with braces (Works also for attributes).
+The given example renders following output:
-* Processing child nodes will be triggered for nodes with a class attribute starting with `_`.
-
-I admit the last point is a bit quirky, but processing all child nodes per default is too expensive and too unpredictable. Maybe I will find a better way, but I don’t mind inserting these extra `_` class names.
+ <div class="comments">
+ <div id="comments-template">
+ <div class="comment">
+ <div class="top">
+ <a href="http://backham.com">David Beckham</a> said
+ <a title="2008-09-07 12:28:33">2 hours ago</a>
+ </div>
+ <div class="text">
+ I watched the euro finals on tv...
+ </div>
+ </div>
+ <div class="comment">
+ <div class="top">
+ Tuncay said
+ <a title="2008-09-07 14:28:33">1 minute ago</a>
+ </div>
+ <div class="text">
+ Me too
+ </div>
+ </div>
+ </div>
+ </div>
+
+
-### Evaluation
+### Basic Rules
-So speaking of the example data, this would mean following algorithm:
+There are 3 basic rules regarding the evaluation:
-* Find the first node with a class name of comment.
+* The special node attribute `context` declares a scope, which will be
+ looked up in the current data object.
-* Repeat this node two times and recursively process the first and second comment.
+* Arrays repeat the current node and process its elements recursively.
-* Descend into the node with class `top`.
+* Code will be evaluated for text surounded with braces (works also
+ for attributes).
-* Descend into the first link node.
-* Evaluate the code found in the *href* attribute and in the text.
+### Example Evaluation
-* Descend into the second link node.
+So speaking of the example data, this would mean following algorithm:
-* Evaluate the code found in the *title* attribute.
+* Find the node with `comment` context.
-* Find the first node with the class `text`.
+* Repeat this node two times and process the first and second comment.
-* Insert the the text of the comment into the found node.
+* Evaluate the code found in text nodes and attributes within the
+ scope of each comment.
-Note that we are dealing with two scopes here: the global scope and the comment scope. The global scope just contains a name *comment* and the comment scope contains the names `date`, `name`, `website` and `text`.
+Note that we are dealing with two scopes here: the global scope and
+the comment scope. The global scope just contains a name *comment* and
+the comment scope contains the names `date`, `name`, `website` and
+`text`.
### Download
Download the script at my [github repository][2].
[1]: commenting-system-with-lightweight-json-store.html
[2]: http://github.com/georgi/patroon/tree/master
+
+
+### Without jQuery
+
+Without jQuery template expansion is a bit verbose:
+
+ // The comments template will be removed from the DOM!
+ var template = new Template('comments-template');
+
+ // template will result in a new DOM node
+ var result = template.expand(data);
+
+ // insert the resulting node into the comments container
+ var container = document.getElementsByClassName('comments')[0];
+ container.appendChild(result);
+

0 comments on commit 45a02e7

Please sign in to comment.