Skip to content
This repository
Browse code

breaking out the docs and cleaning up the README a bit

  • Loading branch information...
commit 2370d2b18b896d99a4237275477f2a76a47c3e6c 1 parent 217c046
Paul Armstrong authored
250  README.md
Source Rendered
... ...
@@ -1,235 +1,59 @@
1 1
 # Node-T
2 2
 
3  
-A fast django-like templating engine for node.js.
  3
+A fast, Django-like template engine for node.js.
4 4
 
5  
-Node-T is a templating engine inspired by the django syntax. It has a few extensions and the templates are compiled to native javascript functions which make them really fast. For now it's synchronous, but once a template is read and compiled, it is cached in memory.
  5
+Node-T is a template engine inspired by the Django syntax. It has a few extensions and the templates are compiled to native javascript functions which make them really fast. For now it's synchronous, but once a template is read and compiled, it is cached in memory.
6 6
 
7  
-### Example template code
  7
+## Basic Example
8 8
 
9  
-    <html>
10  
-    <body>
11  
-      <h1>Example</h1>
12  
-      {% for name in names %}
13  
-        <p>
14  
-          {{forloop.counter}}
15  
-          {# This is a comment #}
16  
-          {{name}}{% if name == "Django" %} Reinhardt{% end %}
17  
-        </p>
18  
-      {% end %}
19  
-    </body>
20  
-    </html>
  9
+### Template code
21 10
 
22  
-### Example node code
  11
+    <h1>Example</h1>
  12
+    {% for name in names %}
  13
+      <p>
  14
+        {{ forloop.counter }}
  15
+        {# This is a comment #}
  16
+        {{ name }}{% if name == "Django" %} Reinhardt{% end %}
  17
+      </p>
  18
+    {% end %}
  19
+
  20
+### node.js code
23 21
 
24 22
     var template  = require('node-t');
25 23
     var tmpl = template.fromFile("/path/to/template.html");
26 24
     console.log(tmpl.render({names: ["Duke", "Django", "Louis"]}));
27 25
 
28  
-### How it works
  26
+### Output
  27
+
  28
+    <h1>Example</h1>
  29
+      <p>
  30
+        1
  31
+        Duke
  32
+      </p>
  33
+      <p>
  34
+        2
  35
+        Django Reinhardt
  36
+      </p>
  37
+      <p>
  38
+        3
  39
+        Louis
  40
+      </p>
  41
+    {% end %}
  42
+
  43
+## How it works
29 44
 
30 45
 Node-T reads template files and translates them into javascript functions using the Function constructor. When we later render a template we call the evaled function passing a context object as an argument. This makes the rendering very fast. The template tags are defined as strings of Javascript code - which is a bit ugly, but there are helpers that will make writing tags easier for you.
31 46
 
32 47
 The slots system will allow you to define your own HTML snippets that will be rendered with a special context.
33 48
 
34  
-## The API
35  
-
36  
-You have 2 methods for creating a template object:
37  
-
38  
-    var template = require('node-slots');
39  
-    template.fromFile("path/to/template/file.html");
40  
-    template.fromString("Template string here");
41  
-
42  
-Both of them will give you a template object on which you call the render method passing it a map of context values.
43  
-
44  
-    var tmpl = template.fromFile("path/to/template/file.html");
45  
-    var renderdHtml = tmpl.render({});
46  
-
47 49
 ## Template syntax
48 50
 
49  
-You should be familiar with the [Django template syntax][1]. Here I'll just sum up the diferences:
50  
-
51  
-- There are no filters implemented yet
52  
-- Tags like {% for %} and {% if %} are closed with a simple {% end %} tag
53  
-- Not all tags are implemented
54  
-- Some extra tags are implemented
55  
-- Syntax for some tags is a bit different.
56  
-
57  
-Here's a list of currently implemented tags:
58  
-
59  
-### Variable tags
60  
-
61  
-Used to print a variable to the template. If the variable is not in the context we don't get an error, rather an empty string. You can use dot notation to access object proerties or array memebers.
62  
-
63  
-    <p>First Name: {{users.0.first_name}}</p>
64  
-
65  
-#### Variable Filters
66  
-
67  
-Used to modify variables. Filters are added directly after variable names, separated by the pipe (|) character. You can chain multiple filters together, applying one after the other in succession.
68  
-
69  
-    {{ foo|reverse|join(' ')|title }}
70  
-
71  
-##### default(default_value)
72  
-
73  
-If the variable is `undefined`, `null`, or `false`, a default return value can be specified.
74  
-
75  
-    {{ foo|default('foo is not defined') }}
76  
-
77  
-##### lower
78  
-
79  
-Return the variable in all lowercase letters.
80  
-
81  
-##### upper
82  
-
83  
-Return the variable in all uppercase letters
84  
-
85  
-##### capitalize
86  
-
87  
-Capitalize the first character in the string.
88  
-
89  
-##### title
90  
-
91  
-Change the output to title case–the first letter of every word will uppercase, while all the rest will be lowercase.
92  
-
93  
-##### join
94  
-
95  
-If the value is an Array, you can join each value with a delimiter and return it as a string.
96  
-
97  
-    {{ authors|join(', ') }}
98  
-
99  
-##### reverse
100  
-
101  
-If the value is an Array, this filter will reverse all items in the array.
102  
-
103  
-##### length
104  
-
105  
-Return the `length` property of the value.
106  
-
107  
-##### url_encode
108  
-
109  
-Encode a URI component.
110  
-
111  
-##### url_decode
112  
-
113  
-Decode a URI component.
114  
-
115  
-##### json_encode
116  
-
117  
-Return a JSON string of the variable.
118  
-
119  
-##### striptags
120  
-
121  
-Strip all HTML/XML tags.
122  
-
123  
-##### date
124  
-
125  
-Convert a valid date into a format as specified. Mostly conforms to (php.net's date formatting)[http://php.net/date].
126  
-
127  
-    {{ post.created|date('F jS, Y') }}
128  
-
129  
-### Comment tags
130  
-
131  
-Comment tags are simply ignored. Comments can't span multitple lines.
132  
-
133  
-    {# This is a comment #}
134  
-
135  
-### Logic tags
136  
-
137  
-#### extends / block
138  
-
139  
-Check django's template inheritance system for more info. Unlike django, the block tags are terminated with {% end %}, not with {% endblock %}
140  
-
141  
-#### include
142  
-
143  
-Includes a template in it's place. The template is rendered within the current context. Does not requre closing with {% end %}.
144  
-
145  
-    {% include template_path %}
146  
-    {% include "path/to/template.js" %}
147  
-
148  
-#### for
149  
-
150  
-You can iterate arrays and objects. Access the current iteration index through 'forloop.index' which is available inside the loop.
151  
-
152  
-    {% for x in y %}
153  
-      <p>{% forloop.index %}</p>
154  
-    {% end %}
155  
-
156  
-#### if
157  
-
158  
-Supports the following expressions. No else tag yet.
159  
-
160  
-    {% if x %}{% end %}
161  
-    {% if !x %}{% end %}
162  
-    {% if x operator y %}
163  
-      Operators: ==, !=, <, <=, >, >=, ===, !==, in
164  
-      The 'in' operator checks for presence in arrays too.
165  
-    {% end %}
166  
-    {% if x == 'five' %}
167  
-      The operands can be also be string or number literals
168  
-    {% end %}
169  
-
170  
-#### slot
171  
-
172  
-Use slots where you want highly customized content that depends heavily on dynamic data. They work in pair with widget functions that you can write yourself.
173  
-
174  
-Template code
175  
-
176  
-    <div>
177  
-      {% slot main %}
178  
-    </div>
179  
-    <div>
180  
-      {% slot sidebar %}
181  
-    </div>
182  
-
183  
-Node.js code
184  
-
185  
-    context.slots = {
186  
-      main: [
187  
-        "<h1>This is a paragraph as a normal string.</h1>", // String
188  
-
189  
-        { tagname: 'analytics',   // Widget object
190  
-          uaCode: 'UA-XXXXX-X' },
191  
-      ],
192  
-
193  
-      sidebar: [
194  
-        "<h3>Navigation</h3>",    // String
195  
-
196  
-        { tagname: 'navigation',  // Widget object
197  
-          links: [
198  
-            '/home',
199  
-            '/about',
200  
-            '/kittens'
201  
-          ]}
202  
-      ]
203  
-    }
204  
-
205  
-    context.widgets = {
206  
-      analytics: function (context) {
207  
-        // this inside widget functions is bound to the widget object
208  
-        return "<script>..." + this.uaCode + "...</script>";
209  
-      },
210  
-      navigation: function (context) {
211  
-        var i, html = "";
212  
-        for (i=0; i<this.links; i++)
213  
-          html += "<a href='" + links[i] + "'>" + links[i] + "</a>";
214  
-        return html;
215  
-      }
216  
-    }
217  
-
218  
-    template.render(context)
219  
-
220  
-Result
221  
-
222  
-    <div>
223  
-      <h1>This is a paragraph as a normal string.</h1>
224  
-      <script>...UA-XXXXX-X...</script>
225  
-    </div>
226  
-    <div>
227  
-      <h3>Navigation</h3>
228  
-      <a href='/home'>/home</a>
229  
-      <a href='/about'>/about</a>
230  
-      <a href='/kittens'>/kittens</a>
231  
-    </div>
  51
+While Node-T is inspired by the [Django template syntax][1], there are a few differences:
232 52
 
  53
+- Filters have a different syntaxt.
  54
+- Tags like {% for %} and {% if %} are closed with a simple {% end %} tag.
  55
+- Some tags are missing or have different syntax.
  56
+- Some extra tags are available.
233 57
 
234 58
 ## License
235 59
 
13  docs/api.md
Source Rendered
... ...
@@ -0,0 +1,13 @@
  1
+# The API
  2
+
  3
+You have 2 methods for creating a template object:
  4
+
  5
+    var template = require('node-slots');
  6
+    template.fromFile("path/to/template/file.html");
  7
+    template.fromString("Template string here");
  8
+
  9
+Both of them will give you a template object on which you call the render method passing it a map of context values.
  10
+
  11
+    var tmpl = template.fromFile("path/to/template/file.html");
  12
+    var renderdHtml = tmpl.render({});
  13
+
63  docs/filters.md
Source Rendered
... ...
@@ -0,0 +1,63 @@
  1
+# Variable Filters
  2
+
  3
+Used to modify variables. Filters are added directly after variable names, separated by the pipe (|) character. You can chain multiple filters together, applying one after the other in succession.
  4
+
  5
+    {{ foo|reverse|join(' ')|title }}
  6
+
  7
+## default(default_value)
  8
+
  9
+If the variable is `undefined`, `null`, or `false`, a default return value can be specified.
  10
+
  11
+    {{ foo|default('foo is not defined') }}
  12
+
  13
+## lower
  14
+
  15
+Return the variable in all lowercase letters.
  16
+
  17
+## upper
  18
+
  19
+Return the variable in all uppercase letters
  20
+
  21
+## capitalize
  22
+
  23
+Capitalize the first character in the string.
  24
+
  25
+## title
  26
+
  27
+Change the output to title case–the first letter of every word will uppercase, while all the rest will be lowercase.
  28
+
  29
+## join
  30
+
  31
+If the value is an Array, you can join each value with a delimiter and return it as a string.
  32
+
  33
+    {{ authors|join(', ') }}
  34
+
  35
+## reverse
  36
+
  37
+If the value is an Array, this filter will reverse all items in the array.
  38
+
  39
+## length
  40
+
  41
+Return the `length` property of the value.
  42
+
  43
+## url_encode
  44
+
  45
+Encode a URI component.
  46
+
  47
+## url_decode
  48
+
  49
+Decode a URI component.
  50
+
  51
+## json_encode
  52
+
  53
+Return a JSON string of the variable.
  54
+
  55
+## striptags
  56
+
  57
+Strip all HTML/XML tags.
  58
+
  59
+## date
  60
+
  61
+Convert a valid date into a format as specified. Mostly conforms to (php.net's date formatting)[http://php.net/date].
  62
+
  63
+    {{ post.created|date('F jS, Y') }}
110  docs/tags.md
Source Rendered
... ...
@@ -0,0 +1,110 @@
  1
+# Variable tags
  2
+
  3
+Used to print a variable to the template. If the variable is not in the context we don't get an error, rather an empty string. You can use dot notation to access object proerties or array memebers.
  4
+
  5
+    <p>First Name: {{users.0.first_name}}</p>
  6
+
  7
+# Comment tags
  8
+
  9
+Comment tags are simply ignored. Comments can't span multitple lines.
  10
+
  11
+    {# This is a comment #}
  12
+
  13
+# Logic tags
  14
+
  15
+## extends / block
  16
+
  17
+Check django's template inheritance system for more info. Unlike django, the block tags are terminated with {% end %}, not with {% endblock %}
  18
+
  19
+## include
  20
+
  21
+Includes a template in it's place. The template is rendered within the current context. Does not requre closing with {% end %}.
  22
+
  23
+    {% include template_path %}
  24
+    {% include "path/to/template.js" %}
  25
+
  26
+## for
  27
+
  28
+You can iterate arrays and objects. Access the current iteration index through 'forloop.index' which is available inside the loop.
  29
+
  30
+    {% for x in y %}
  31
+      <p>{% forloop.index %}</p>
  32
+    {% end %}
  33
+
  34
+## if
  35
+
  36
+Supports the following expressions. No else tag yet.
  37
+
  38
+    {% if x %}{% end %}
  39
+    {% if !x %}{% end %}
  40
+    {% if x operator y %}
  41
+      Operators: ==, !=, <, <=, >, >=, ===, !==, in
  42
+      The 'in' operator checks for presence in arrays too.
  43
+    {% end %}
  44
+    {% if x == 'five' %}
  45
+      The operands can be also be string or number literals
  46
+    {% end %}
  47
+
  48
+## slot
  49
+
  50
+Use slots where you want highly customized content that depends heavily on dynamic data. They work in pair with widget functions that you can write yourself.
  51
+
  52
+Template code
  53
+
  54
+    <div>
  55
+      {% slot main %}
  56
+    </div>
  57
+    <div>
  58
+      {% slot sidebar %}
  59
+    </div>
  60
+
  61
+Node.js code
  62
+
  63
+    context.slots = {
  64
+      main: [
  65
+        "<h1>This is a paragraph as a normal string.</h1>", // String
  66
+
  67
+        { tagname: 'analytics',   // Widget object
  68
+          uaCode: 'UA-XXXXX-X' },
  69
+      ],
  70
+
  71
+      sidebar: [
  72
+        "<h3>Navigation</h3>",    // String
  73
+
  74
+        { tagname: 'navigation',  // Widget object
  75
+          links: [
  76
+            '/home',
  77
+            '/about',
  78
+            '/kittens'
  79
+          ]}
  80
+      ]
  81
+    }
  82
+
  83
+    context.widgets = {
  84
+      analytics: function (context) {
  85
+        // this inside widget functions is bound to the widget object
  86
+        return "<script>..." + this.uaCode + "...</script>";
  87
+      },
  88
+      navigation: function (context) {
  89
+        var i, html = "";
  90
+        for (i=0; i<this.links; i++)
  91
+          html += "<a href='" + links[i] + "'>" + links[i] + "</a>";
  92
+        return html;
  93
+      }
  94
+    }
  95
+
  96
+    template.render(context)
  97
+
  98
+Result
  99
+
  100
+    <div>
  101
+      <h1>This is a paragraph as a normal string.</h1>
  102
+      <script>...UA-XXXXX-X...</script>
  103
+    </div>
  104
+    <div>
  105
+      <h3>Navigation</h3>
  106
+      <a href='/home'>/home</a>
  107
+      <a href='/about'>/about</a>
  108
+      <a href='/kittens'>/kittens</a>
  109
+    </div>
  110
+

0 notes on commit 2370d2b

Please sign in to comment.
Something went wrong with that request. Please try again.