1 | # coffeecup 0.3.1 Reference
|
2 |
|
3 | ## The coffeecup object
|
4 |
|
5 | Both the returned value from `require 'coffeecup'` and the global `coffeecup` created by `<script src="coffeecup.js">` will have the following attributes:
|
6 |
|
7 | ### compile
|
8 |
|
9 | `coffeecup.compile(template, options)`
|
10 |
|
11 | Compiles the template to a standalone function and returns it.
|
12 |
|
13 | The input template can be provided as either a function or a string. In the latter case, the CoffeeScript compiler must be available.
|
14 |
|
15 | Options:
|
16 |
|
17 | - `locals`: if set to any "truthy" value, will compile the template with the main statements wrapped around a `with` block. The template will then support the `locals` option (see below). This is the "runtime" method of putting external variables in the local scope of the template.
|
18 |
|
19 | - `hardcode`: an object containing values to be added to the template's local scope at "compile time". For each attribute in this object a `var [name] = [stringified value]` will be added to the template body.
|
20 |
|
21 | #### Compiled template
|
22 |
|
23 | The compiled template returned will be a function accepting a single object parameter:
|
24 |
|
25 | `template(data)`
|
26 |
|
27 | All attributes in `data` will be available to the template at `@` (`this`). Some attribute names are special and will trigger additional features:
|
28 |
|
29 | - `locals`: if the template was compiled with the `locals` option, it will pass this variable to the `with` statement, putting all its attributes to the local scope.
|
30 |
|
31 | - `format`: `false` by default. Whether to generate formatted HTML with indentation and line breaks, or just the natural "faux-minified" output.
|
32 |
|
33 | - `autoescape`: `false` by default. Whether to autoescape all content or let you handle it on a case by case basis with the `h` function.
|
34 |
|
35 | ### render
|
36 |
|
37 | `coffeecup.render(template, data, options)`
|
38 |
|
39 | Compiles the template provided, runs it, and returns the resulting HTML string.
|
40 |
|
41 | Options:
|
42 |
|
43 | - `cache`: `false` by default. Whether to reuse compiled templates, or re-compile them every time.
|
44 |
|
45 | ### version
|
46 |
|
47 | Version of coffeecup running.
|
48 |
|
49 | ### doctypes
|
50 |
|
51 | List of doctypes available to the `doctype` function in templates. Object with doctype names as keys and their string contents as values. Can be customized at will.
|
52 |
|
53 | The doctype named "default" will be used when none is specified (`doctype()`).
|
54 |
|
55 | ### tags
|
56 |
|
57 | List of HTML elements available as functions. Array of strings, can be customized.
|
58 |
|
59 | ### self_closing
|
60 |
|
61 | List of self-closing tags. Array of strings, can be customized.
|
62 |
|
63 | ## The template scope
|
64 |
|
65 | coffeecup templates are CoffeeScript/JavaScript functions with certain special variables put in their local scope. These are usually functions, which will write their equivalent HTML to a buffer. The contents of this buffer will be the final return value of the template.
|
66 |
|
67 | ### Tag functions
|
68 |
|
69 | By far the most important of these functions are those equivalent to each HTML element. They'll write the tags and attributes necessary to render the element.
|
70 |
|
71 | They're designed to look very similar to their HTML output when written in CoffeeScript.
|
72 |
|
73 | Empty tags:
|
74 |
|
75 | div()
|
76 | <div></div>
|
77 |
|
78 | img()
|
79 | <img />
|
80 |
|
81 | Attributes:
|
82 |
|
83 | div str: 'str', num: 42, bool: yes, arr: [1, 2, 3], obj: {foo: 'bar', ping: 'pong'}
|
84 | <div str="str" num="42" bool="bool" arr="1,2,3" obj-foo="bar" obj-ping="pong"><div>
|
85 |
|
86 | div onclick: -> alert 'hi'
|
87 | <div onclick="(function(){return alert('hi');}).call(this);"></div>
|
88 |
|
89 | Contents (string):
|
90 |
|
91 | h1 'foo'
|
92 | <h1>Foo</h1>
|
93 |
|
94 | h1 attr: 'value', 'foo'
|
95 | <h1 attr="value">Foo</h1>
|
96 |
|
97 | script '''
|
98 | alert('foo');
|
99 | console.log('bar');
|
100 | '''
|
101 | <script>alert('foo');
|
102 | console.log('bar');</script>
|
103 |
|
104 | Contents (function):
|
105 |
|
106 | div -> 'Foo'
|
107 | <div>Foo</div>
|
108 |
|
109 | # equivalent to js: div(function(){'Foo'; return 'Bar';});
|
110 | div ->
|
111 | 'Foo'
|
112 | 'Bar'
|
113 | <div>
|
114 | Bar
|
115 | </div>
|
116 |
|
117 | # equivalent to js: div(function(){'Foo'; div('Ping'); return 'Bar';});
|
118 | div ->
|
119 | 'Foo'
|
120 | div 'Ping'
|
121 | 'Bar'
|
122 | <div>
|
123 | <div>Ping</div>
|
124 | Bar
|
125 | </div>
|
126 |
|
127 | # equivalent to js: div(function(){text('Foo'); div('Ping'); return 'Bar';});
|
128 | div ->
|
129 | text 'Foo'
|
130 | div 'Ping'
|
131 | 'Bar'
|
132 | <div>
|
133 | Foo
|
134 | <div>Ping</div>
|
135 | Bar
|
136 | </div>
|
137 |
|
138 | ID/class shortcut
|
139 |
|
140 | div '#id.class.anotherclass', 'string contents'
|
141 | <div id="id" class="class anotherclass">string contents</div>
|
142 |
|
143 | div '#id.class.anotherclass', -> h1 'Hullo'
|
144 | <div id="id" class="class anotherclass"><h1>Hullo</h1></div>
|
145 |
|
146 | div '#id.class.anotherclass', style: 'position: fixed', 'string contents'
|
147 | <div id="id" class="class anotherclass" style="position: fixed">string contents</div>
|
148 |
|
149 | ### Other locals
|
150 |
|
151 | #### doctype
|
152 |
|
153 | Writes the doctype. Usage: `doctype()` (picks the default), `doctype 'xml'` (specifying). You can see and modify the list of doctypes at `coffeecup.doctypes`.
|
154 |
|
155 | #### comment
|
156 |
|
157 | Writes an HTML comment.
|
158 |
|
159 | #### ie
|
160 |
|
161 | Writes an IE conditional comment. Ex.:
|
162 |
|
163 | ie 'gte IE8', ->
|
164 | link href: 'ie.css', rel: 'stylesheet'
|
165 |
|
166 | <!--[if gte IE8]>
|
167 | <link href="ie.css" rel="stylesheet" />
|
168 | <![endif]-->
|
169 |
|
170 | #### text
|
171 |
|
172 | Writes arbitrary text to the buffer.
|
173 |
|
174 | #### tag
|
175 |
|
176 | Used for arbitrary tags. Works like the builtin tags, but the first string parameter is the name of the tag.
|
177 |
|
178 | #### coffeescript
|
179 |
|
180 | CoffeeScript-friendly shortcut to `script`:
|
181 |
|
182 | coffeescript -> alert 'hi'
|
183 | <script>
|
184 | [COFFEESCRIPT_HELPERS]
|
185 | (function(){return alert('hi');}).call(this);
|
186 | </script>
|
187 |
|
188 | coffeescript "alert 'hi'"
|
189 | <script type="text/coffeescript">alert 'hi'</script>
|
190 |
|
191 | coffeescript src: 'script.coffee'
|
192 | <script type="text/coffeescript" src="script.coffee"></script>
|
193 |
|
194 | #### yield
|
195 |
|
196 | Returns the output of a template chunk as a string instead of writing it to the buffer. Useful for string interpolations. Ex.:
|
197 |
|
198 | p "This text could use #{yield -> a href: '/', 'a link'}."
|
199 | <p>This text could use <a href="/">a link</a>.</p>
|
200 |
|
201 | Without it, the `a` function runs first, writes to the buffer and returns `null`, resulting in a useless output:
|
202 |
|
203 | p "This text could use #{a href: '/', 'a link'}."
|
204 | <a href="/">a link</a><p>This text could use null.</p>
|
205 |
|
206 | #### @
|
207 |
|
208 | CoffeeScript shortcut to `this`. This is where all the input data can be accessed.
|
209 |
|
210 | ## Extending coffeecup
|
211 |
|
212 | template = ->
|
213 | h1 @title
|
214 | form method: 'post', action: 'login', ->
|
215 | textbox id: 'username'
|
216 | textbox id: 'password'
|
217 | button @title
|
218 |
|
219 | helpers =
|
220 | textbox: (attrs) ->
|
221 | attrs.type = 'text'
|
222 | attrs.name = attrs.id
|
223 | input attrs
|
224 |
|
225 | console.log coffeecup.render template, title: 'Log In', hardcode: helpers
|
226 |
|
227 | ## The coffeecup command
|
228 |
|
229 | When installing coffeecup with `npm install coffeecup -g`, you get a `coffeecup` command that allows you to generate HTML from coffeecup templates:
|
230 |
|
231 | $ coffeecup -h
|
232 |
|
233 | Usage:
|
234 | coffeecup [options] path/to/template.coffee
|
235 |
|
236 | --js compile template to js function
|
237 | -n, --namespace global object holding the templates (default: "templates")
|
238 | -w, --watch watch templates for changes, and recompile
|
239 | -o, --output set the directory for compiled html
|
240 | -p, --print print the compiled html to stdout
|
241 | -f, --format apply line breaks and indentation to html output
|
242 | -u, --utils add helper locals (currently only "render")
|
243 | -v, --version display coffeecup version
|
244 | -h, --help display this help message
|