Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 261 lines (167 sloc) 10.226 kb
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
1 # CoffeeKup <☕/>
4ffd222 Maurice Machado Updated readme.
authored
2 ## Markup as CoffeeScript
75ee63a Maurice Machado Initial import.
authored
3
4ffd222 Maurice Machado Updated readme.
authored
4 CoffeeKup is a templating engine for [node.js](http://nodejs.org) and browsers that lets you to write your HTML templates in 100% pure [CoffeeScript](http://coffeescript.org).
5
6 It was created in celebration of [whyday](http://whyday.org/), as an application of the concept used in [Markaby](https://github.com/markaby/markaby) ("Markup as Ruby", by Tim Fletcher and why the lucky stiff) to CoffeeScript.
7
8 Here's what a template written for CoffeeKup looks like:
75ee63a Maurice Machado Initial import.
authored
9
10 doctype 5
11 html ->
12 head ->
13 meta charset: 'utf-8'
4ffd222 Maurice Machado Updated readme.
authored
14 title "#{@title or 'Untitled'} | A completely plausible website"
75ee63a Maurice Machado Initial import.
authored
15 meta(name: 'description', content: @description) if @description?
4ffd222 Maurice Machado Updated readme.
authored
16
17 link rel: 'stylesheet', href: '/css/app.css'
18
75ee63a Maurice Machado Initial import.
authored
19 style '''
20 body {font-family: sans-serif}
21 header, nav, section, footer {display: block}
22 '''
4ffd222 Maurice Machado Updated readme.
authored
23
24 script src: '/js/jquery.js'
25
75ee63a Maurice Machado Initial import.
authored
26 coffeescript ->
4ffd222 Maurice Machado Updated readme.
authored
27 $(document).ready ->
28 alert 'Alerts suck!'
75ee63a Maurice Machado Initial import.
authored
29 body ->
30 header ->
51f1768 Maurice Machado Updated README.
authored
31 h1 @title or 'Untitled'
4ffd222 Maurice Machado Updated readme.
authored
32
75ee63a Maurice Machado Initial import.
authored
33 nav ->
34 ul ->
35 (li -> a href: '/', -> 'Home') unless @path is '/'
51f1768 Maurice Machado Updated README.
authored
36 li -> a href: '/chunky', -> 'Bacon!'
37 switch @user.role
38 when 'owner', 'admin'
39 li -> a href: '/admin', -> 'Secret Stuff'
40 when 'vip'
41 li -> a href: '/vip', -> 'Exclusive Stuff'
42 else
43 li -> a href: '/commoners', -> 'Just Stuff'
4ffd222 Maurice Machado Updated readme.
authored
44
1769256 Maurice Machado Added divitis example with new id/class shortcut.
authored
45 div '#myid.myclass.anotherclass', style: 'position: fixed', ->
4ffd222 Maurice Machado Updated readme.
authored
46 p 'Divitis kills! Inline styling too.'
47
75ee63a Maurice Machado Initial import.
authored
48 section ->
4ffd222 Maurice Machado Updated readme.
authored
49 # A helper function you built and included.
50 breadcrumb separator: '>', clickable: yes
51
75ee63a Maurice Machado Initial import.
authored
52 h2 "Let's count to 10:"
53 p i for i in [1..10]
4ffd222 Maurice Machado Updated readme.
authored
54
55 # Another hypothetical helper.
56 form_to @post, ->
57 textbox '#title', label: 'Title:'
58 textbox '#author', label: 'Author:'
59 submit 'Save'
60
75ee63a Maurice Machado Initial import.
authored
61 footer ->
4ffd222 Maurice Machado Updated readme.
authored
62 # CoffeeScript comments. Not visible in the output document.
63 comment 'HTML comments.'
75ee63a Maurice Machado Initial import.
authored
64 p 'Bye!'
65
4ffd222 Maurice Machado Updated readme.
authored
66 Interactive demo at [coffeekup.org](http://coffeekup.org).
67
68 ## _why?
7422874 Maurice Machado Added link to live demo on README.
authored
69
4ffd222 Maurice Machado Updated readme.
authored
70 - **One language to rule them all**. JavaScript is everywhere, thus so is CoffeeScript. Servers, browsers, even databases. If extending this to rendering logic and UI structure (server and client side) is desirable to you, CoffeeKup is your friend.
75ee63a Maurice Machado Initial import.
authored
71
4ffd222 Maurice Machado Updated readme.
authored
72 - **More specifically, one _outstanding_ language**. CoffeeScript is one hell of a clean, expressive, flexible and powerful language. It's hard to find such combination, especially if you need it to run in the browser too.
d5e9bd4 Maurice Machado Updated README.
authored
73
4ffd222 Maurice Machado Updated readme.
authored
74 - **Not yet another specialized language to learn**. Transferable knowledge FTW.
d5e9bd4 Maurice Machado Updated README.
authored
75
4ffd222 Maurice Machado Updated readme.
authored
76 - **Embed your templates in CoffeeScript nicely**. Templates are just functions, so they don't lose syntax highlighting and syntax checking when embedded in CoffeeScript apps.
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
77
4ffd222 Maurice Machado Updated readme.
authored
78 - **Embed CoffeeScript in your templates nicely**. In the same manner, you can write the contents of `<script>` blocks in CoffeeScript, and keep the highlighting. Perhaps more significantly, the CoffeeScript compiler doesn't have to be called just to convert these blocks to JS, as in other templating engines.
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
79
4ffd222 Maurice Machado Updated readme.
authored
80 - **Extensive editor support**. You benefit from the already existing list of excellent CoffeeScript [text editor plugins](https://github.com/jashkenas/coffee-script/wiki/Text-editor-plugins).
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
81
4ffd222 Maurice Machado Updated readme.
authored
82 - **Client-server consistency**. The same template language _and_ implementation in node.js or the browser.
51f1768 Maurice Machado Updated README.
authored
83
4ffd222 Maurice Machado Updated readme.
authored
84 - **Easily extendable into a higher level "DSL"**. Since all elements are just functions, it's very easy to define your own custom "tags", which will work and look the same as "native" ones.
51f1768 Maurice Machado Updated README.
authored
85
4ffd222 Maurice Machado Updated readme.
authored
86 - **HTML 5 ready**. Boring legacy doctypes and elements also available.
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
87
4ffd222 Maurice Machado Updated readme.
authored
88 - **Optional auto-escaping**. You can also use the `h` helper on a case-by-case basis.
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
89
4ffd222 Maurice Machado Updated readme.
authored
90 - **Optional formatting**, with line breaks and indentation.
b4f4330 Maurice Machado README tweaked.
authored
91
4ffd222 Maurice Machado Updated readme.
authored
92 - **Pick your poison**. Works with both CoffeeScript and JavaScript apps.
b4f4330 Maurice Machado README tweaked.
authored
93
4ffd222 Maurice Machado Updated readme.
authored
94 ## Why not?
95
96 CoffeeKup may not be your best choice in those cases:
97
98 - You're after the cleanest syntax possible, above all. In this regard a specialized language such as [Jade](http://jade-lang.com) just can't be beaten.
99
100 - You use divs and/or classes for everything. While in CoffeeKup you can do `div '#id.class.class'`, specialized languages often have an even shorter syntax for that.
101
102 - You want CoffeeScript for rendering logic, but you'd rather stick with HTML for markup. Then you're looking for [Eco](http://github.com/sstephenson/eco).
103
104 - For your specific project/team/preferences, you think a limited and/or separate language for templating is actually beneficial.
75ee63a Maurice Machado Initial import.
authored
105
106 ## Installing
107
108 Just grab [node.js](http://nodejs.org/#download) and [npm](http://github.com/isaacs/npm) and you're set:
109
66f6f49 Maurice Machado Removed [sudo] from readme.
authored
110 npm install coffeekup
75ee63a Maurice Machado Initial import.
authored
111
243c54b Maurice Machado First go at updating the readme / added annotated source through docco.
authored
112 To get the `coffeekup` command, install it globally:
113
114 npm install coffeekup -g
c342d0d Maurice Machado Added instructions to install edge and mentioned 'reference.md'.
authored
115
116 Or to use the latest version:
117
118 git clone git@github.com:mauricemach/coffeekup.git && cd coffeekup
119 cake build
120 npm link
121 cd ~/myproject
122 npm link coffeekup
243c54b Maurice Machado First go at updating the readme / added annotated source through docco.
authored
123
75ee63a Maurice Machado Initial import.
authored
124 ## Using
125
4ffd222 Maurice Machado Updated readme.
authored
126 ck = require 'coffeekup'
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
127
4ffd222 Maurice Machado Updated readme.
authored
128 ck.render -> h1 "You can feed me templates as functions."
129 ck.render "h1 'Or strings. I am not too picky.'"
51f1768 Maurice Machado Updated README.
authored
130
4ffd222 Maurice Machado Updated readme.
authored
131 Defining variables:
d5e9bd4 Maurice Machado Updated README.
authored
132
133 template = ->
134 h1 @title
135 form method: 'post', action: 'login', ->
136 textbox id: 'username'
137 textbox id: 'password'
138 button @title
139
140 helpers =
141 textbox: (attrs) ->
142 attrs.type = 'text'
143 attrs.name = attrs.id
243c54b Maurice Machado First go at updating the readme / added annotated source through docco.
authored
144 input attrs
d5e9bd4 Maurice Machado Updated README.
authored
145
4ffd222 Maurice Machado Updated readme.
authored
146 ck.render(template, title: 'Log In', hardcode: helpers)
75ee63a Maurice Machado Initial import.
authored
147
51f1768 Maurice Machado Updated README.
authored
148 Precompiling to functions:
149
4ffd222 Maurice Machado Updated readme.
authored
150 template = ck.compile(template, locals: yes, hardcode: {zig: 'zag'})
151
152 template(foo: 'bar', locals: {ping: 'pong'})
6cacf2d Maurice Machado Added a zappa example.
authored
153
75ee63a Maurice Machado Initial import.
authored
154 With [express](http://expressjs.com):
155
156 app.set 'view engine', 'coffee'
98e8211 Maurice Machado Added the express adapter to readme.
authored
157 app.register '.coffee', require('coffeekup').adapters.express
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
158
75ee63a Maurice Machado Initial import.
authored
159 app.get '/', (req, res) ->
160 # Will render views/index.coffee:
243c54b Maurice Machado First go at updating the readme / added annotated source through docco.
authored
161 res.render 'index', foo: 'bar'
75ee63a Maurice Machado Initial import.
authored
162
4ffd222 Maurice Machado Updated readme.
authored
163 With [zappa](http://github.com/mauricemach/zappa):
3965393 Maurice Machado Added Meryl example, updated README.
authored
164
4ffd222 Maurice Machado Updated readme.
authored
165 get '/': ->
166 @franks = ['miller', 'oz', 'sinatra', 'zappa']
167 render 'index'
168
169 view index: ->
170 for name in @franks
171 a href: "http://en.wikipedia.org/wiki/Frank_#{name}", -> name
172
173 With [meryl](https://github.com/kadirpekel/meryl/tree/master/examples/coffeekup-template):
174
175 coffeekup = require 'coffeekup'
176
177 meryl.get '/', (req, resp) ->
fe1357d Maurice Machado Added framework adapters to ease integration.
authored
178 people = ['bob', 'alice', 'meryl']
179 resp.render 'layout', content: 'index', context: {people: people}
3965393 Maurice Machado Added Meryl example, updated README.
authored
180
181 meryl.run
182 templateExt: '.coffee'
fe1357d Maurice Machado Added framework adapters to ease integration.
authored
183 templateFunc: coffeekup.adapters.meryl
3965393 Maurice Machado Added Meryl example, updated README.
authored
184
d5e9bd4 Maurice Machado Updated README.
authored
185 On the browser:
75ee63a Maurice Machado Initial import.
authored
186
51f1768 Maurice Machado Updated README.
authored
187 <script src="template.js"></script>
188 <script>
b409d7d Rachel Carvalho Added compile to js option to CLI. Closes #58.
rachel-carvalho authored
189 $('body').append(templates.template({foo: 'bar'}));
51f1768 Maurice Machado Updated README.
authored
190 </script>
e8c2612 Maurice Machado Fixed context vars at the root and issue with the coffeescript "filter".
authored
191
51f1768 Maurice Machado Updated README.
authored
192 This is one of many browser deployment possibilities, pre-compiling your template on the server to a standalone function. To see all serving suggestions, check out [regular](http://github.com/mauricemach/coffeekup/blob/master/examples/browser/regular/index.html), [decaf](http://github.com/mauricemach/coffeekup/blob/master/examples/browser/decaf/index.html) and [crème](http://github.com/mauricemach/coffeekup/blob/master/examples/browser/creme/index.html).
75ee63a Maurice Machado Initial import.
authored
193
194 Command-line:
195
e6b3b49 Maurice Machado Added -u/--utils to command, updated README.
authored
196 $ coffeekup -h
197
198 Usage:
8482d3c Maurice Machado Updated changelog.
authored
199 coffeekup [options] path/to/template.coffee
e6b3b49 Maurice Machado Added -u/--utils to command, updated README.
authored
200
b409d7d Rachel Carvalho Added compile to js option to CLI. Closes #58.
rachel-carvalho authored
201 --js compile template to js function
202 -n, --namespace global object holding the templates (default: "templates")
8482d3c Maurice Machado Updated changelog.
authored
203 -w, --watch watch templates for changes, and recompile
204 -o, --output set the directory for compiled html
205 -p, --print print the compiled html to stdout
206 -f, --format apply line breaks and indentation to html output
207 -u, --utils add helper locals (currently only "render")
208 -v, --version display CoffeeKup version
209 -h, --help display this help message
75ee63a Maurice Machado Initial import.
authored
210
74b3cf1 Maurice Machado Added note to run `cake build` before trying examples (prompted by #63).
authored
211 See [/examples](http://github.com/mauricemach/coffeekup/tree/master/examples) for complete versions (you have to run `cake build` first).
212
213 Please note that even though all examples are given in CoffeeScript, you can also use their plain JavaScript counterparts just fine.
75ee63a Maurice Machado Initial import.
authored
214
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
215 ## Resources
d3091b4 Maurice Machado Added link to Mark Hahn's intro to CoffeeKup.
authored
216
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
217 - [API reference](https://github.com/mauricemach/coffeekup/blob/master/docs/reference.md)
c342d0d Maurice Machado Added instructions to install edge and mentioned 'reference.md'.
authored
218
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
219 - [Mailing list](https://groups.google.com/group/coffeekup)
d3091b4 Maurice Machado Added link to Mark Hahn's intro to CoffeeKup.
authored
220
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
221 - [Issues](https://github.com/mauricemach/coffeekup/issues)
c06affd Maurice Machado README tweaks.
authored
222
0240993 Maurice Machado Added freenode channel.
authored
223 - **IRC**: #coffeekup on irc.freenode.net
224
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
225 - [A Beginners's Introduction to CoffeeKup](https://github.com/mark-hahn/coffeekup-intro)
a4459cc Maurice Machado Added related projects and thanks sections to readme.
authored
226
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
227 ## Tools
2084382 Maurice Machado Split up resources and related projects.
authored
228
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
229 - [html2coffeekup](https://github.com/brandonbloom/html2coffeekup) - Converts HTML to CoffeeKup templates.
a4459cc Maurice Machado Added related projects and thanks sections to readme.
authored
230
30ac37f Maurice Machado Added htmlkup.
authored
231 - [htmlkup](https://github.com/colinta/htmlkup) - Another HTML converter, stdin/stdout based.
232
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
233 - [ice](https://github.com/ludicast/ice) - CoffeeKup and Eco in Rails ([screencast](http://vimeo.com/25907220)).
bfa834b Maurice Machado Added ice (CoffeeKup and Eco for Rails) to related projects.
authored
234
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
235 - [coffee-world](https://github.com/khoomeister/coffee-world) - Tool to watch and compile HTML with CoffeeKup, CSS with coffee-css and JS with CoffeeScript.
bb00191 Maurice Machado Added more resources and related projects.
authored
236
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
237 - [cupcake](https://github.com/twilson63/cupcake) - Express app generator with CoffeeKup support.
867c8f4 Maurice Machado Bumped master version to 0.3.0beta2.
authored
238
2084382 Maurice Machado Split up resources and related projects.
authored
239 ## Related projects
240
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
241 - [ck](https://github.com/aeosynth/ck) - "a smaller, faster coffeekup": Alternative, barebones implementation.
e1ee49d Maurice Machado Fixed readme.
authored
242
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
243 - [ckup](https://github.com/satyr/ckup) - "Markup as Coco": Similar engine but for [Coco](https://github.com/satyr/coco) ("Unfancy CoffeeScript").
e1ee49d Maurice Machado Fixed readme.
authored
244
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
245 - [Eco](https://github.com/sstephenson/eco) - "Embedded CoffeeScript templates": "EJS/ERB" for CoffeeScript.
a4459cc Maurice Machado Added related projects and thanks sections to readme.
authored
246
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
247 - [timbits](https://github.com/Postmedia/timbits) - "Widget framework based on Express and CoffeeScript".
bb00191 Maurice Machado Added more resources and related projects.
authored
248
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
249 - [coffee-css](https://github.com/khoomeister/coffee-css) - "More CSS for CoffeeScript".
bb00191 Maurice Machado Added more resources and related projects.
authored
250
e505e78 Maurice Machado Added mailing list, other tweaks.
authored
251 - [ccss](https://github.com/aeosynth/ccss) - "CoffeeScript CSS".
252
253 ## Compatibility
254
255 Latest version tested with node 0.4.9 and CoffeeScript 1.1.1.
bb00191 Maurice Machado Added more resources and related projects.
authored
256
a4459cc Maurice Machado Added related projects and thanks sections to readme.
authored
257 ## Special thanks
258
259 - [Jeremy Ashkenas](https://github.com/jashkenas), for the amazing CoffeeScript language.
b409d7d Rachel Carvalho Added compile to js option to CLI. Closes #58.
rachel-carvalho authored
260 - [why the lucky stiff](Why_the_lucky_stiff), for the inspiration.
Something went wrong with that request. Please try again.