Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 285 lines (180 sloc) 11.082 kB
9f3930c @gradus updating readme
authored
1 # CoffeeCup <☕/>
4ffd222 @mauricemach Updated readme.
mauricemach authored
2 ## Markup as CoffeeScript
75ee63a @mauricemach Initial import.
mauricemach authored
3
128e5e3 @gradus add .travis.yml
authored
4 [![Build Status](https://secure.travis-ci.org/gradus/coffeecup.png?branch=master)](http://travis-ci.org/gradus/coffeecup)
5
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
6 This is a clone of @mauricemach [CoffeeCup](https://github.com/mauricemach/coffeekup).
9f3930c @gradus updating readme
authored
7
8 I am renaming and trying to keep this project alive.
9
2cefd3d @gradus update readme
authored
10 [Fork CoffeeCup on Github](https://github.com/gradus/coffeecup).
11
9f3930c @gradus updating readme
authored
12 CoffeeCup 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).
4ffd222 @mauricemach Updated readme.
mauricemach authored
13
14 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.
15
9f3930c @gradus updating readme
authored
16 Here's what a template written for CoffeeCup looks like:
75ee63a @mauricemach Initial import.
mauricemach authored
17
18 doctype 5
19 html ->
20 head ->
21 meta charset: 'utf-8'
4ffd222 @mauricemach Updated readme.
mauricemach authored
22 title "#{@title or 'Untitled'} | A completely plausible website"
75ee63a @mauricemach Initial import.
mauricemach authored
23 meta(name: 'description', content: @description) if @description?
4ffd222 @mauricemach Updated readme.
mauricemach authored
24
25 link rel: 'stylesheet', href: '/css/app.css'
26
75ee63a @mauricemach Initial import.
mauricemach authored
27 style '''
28 body {font-family: sans-serif}
29 header, nav, section, footer {display: block}
30 '''
7c4b164 @gradus update readme with Stylus support comment in template
authored
31
32 comment 'Stylus is supported as well'
33
04586e4 @gradus add stylus example in readme
authored
34 stylus '''
35 body
36 margin: 0
37 '''
38
4ffd222 @mauricemach Updated readme.
mauricemach authored
39 script src: '/js/jquery.js'
40
75ee63a @mauricemach Initial import.
mauricemach authored
41 coffeescript ->
4ffd222 @mauricemach Updated readme.
mauricemach authored
42 $(document).ready ->
43 alert 'Alerts suck!'
75ee63a @mauricemach Initial import.
mauricemach authored
44 body ->
45 header ->
51f1768 @mauricemach Updated README.
mauricemach authored
46 h1 @title or 'Untitled'
4ffd222 @mauricemach Updated readme.
mauricemach authored
47
75ee63a @mauricemach Initial import.
mauricemach authored
48 nav ->
49 ul ->
50 (li -> a href: '/', -> 'Home') unless @path is '/'
51f1768 @mauricemach Updated README.
mauricemach authored
51 li -> a href: '/chunky', -> 'Bacon!'
52 switch @user.role
53 when 'owner', 'admin'
54 li -> a href: '/admin', -> 'Secret Stuff'
55 when 'vip'
56 li -> a href: '/vip', -> 'Exclusive Stuff'
57 else
58 li -> a href: '/commoners', -> 'Just Stuff'
4ffd222 @mauricemach Updated readme.
mauricemach authored
59
1769256 @mauricemach Added divitis example with new id/class shortcut.
mauricemach authored
60 div '#myid.myclass.anotherclass', style: 'position: fixed', ->
4ffd222 @mauricemach Updated readme.
mauricemach authored
61 p 'Divitis kills! Inline styling too.'
62
75ee63a @mauricemach Initial import.
mauricemach authored
63 section ->
4ffd222 @mauricemach Updated readme.
mauricemach authored
64 # A helper function you built and included.
65 breadcrumb separator: '>', clickable: yes
66
75ee63a @mauricemach Initial import.
mauricemach authored
67 h2 "Let's count to 10:"
68 p i for i in [1..10]
4ffd222 @mauricemach Updated readme.
mauricemach authored
69
70 # Another hypothetical helper.
71 form_to @post, ->
72 textbox '#title', label: 'Title:'
73 textbox '#author', label: 'Author:'
74 submit 'Save'
75
75ee63a @mauricemach Initial import.
mauricemach authored
76 footer ->
4ffd222 @mauricemach Updated readme.
mauricemach authored
77 # CoffeeScript comments. Not visible in the output document.
78 comment 'HTML comments.'
75ee63a @mauricemach Initial import.
mauricemach authored
79 p 'Bye!'
80
4ffd222 @mauricemach Updated readme.
mauricemach authored
81 Interactive demo at [coffeekup.org](http://coffeekup.org).
82
83 ## _why?
7422874 @mauricemach Added link to live demo on README.
mauricemach authored
84
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
85 - **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, CoffeeCup is your friend.
75ee63a @mauricemach Initial import.
mauricemach authored
86
4ffd222 @mauricemach Updated readme.
mauricemach authored
87 - **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 @mauricemach Updated README.
mauricemach authored
88
4ffd222 @mauricemach Updated readme.
mauricemach authored
89 - **Not yet another specialized language to learn**. Transferable knowledge FTW.
d5e9bd4 @mauricemach Updated README.
mauricemach authored
90
4ffd222 @mauricemach Updated readme.
mauricemach authored
91 - **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 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
92
4ffd222 @mauricemach Updated readme.
mauricemach authored
93 - **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 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
94
4ffd222 @mauricemach Updated readme.
mauricemach authored
95 - **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 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
96
4ffd222 @mauricemach Updated readme.
mauricemach authored
97 - **Client-server consistency**. The same template language _and_ implementation in node.js or the browser.
51f1768 @mauricemach Updated README.
mauricemach authored
98
4ffd222 @mauricemach Updated readme.
mauricemach authored
99 - **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 @mauricemach Updated README.
mauricemach authored
100
4ffd222 @mauricemach Updated readme.
mauricemach authored
101 - **HTML 5 ready**. Boring legacy doctypes and elements also available.
e8c2612 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
102
4ffd222 @mauricemach Updated readme.
mauricemach authored
103 - **Optional auto-escaping**. You can also use the `h` helper on a case-by-case basis.
e8c2612 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
104
4ffd222 @mauricemach Updated readme.
mauricemach authored
105 - **Optional formatting**, with line breaks and indentation.
b4f4330 @mauricemach README tweaked.
mauricemach authored
106
4ffd222 @mauricemach Updated readme.
mauricemach authored
107 - **Pick your poison**. Works with both CoffeeScript and JavaScript apps.
b4f4330 @mauricemach README tweaked.
mauricemach authored
108
4ffd222 @mauricemach Updated readme.
mauricemach authored
109 ## Why not?
110
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
111 CoffeeCup may not be your best choice in those cases:
4ffd222 @mauricemach Updated readme.
mauricemach authored
112
113 - 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.
114
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
115 - You use divs and/or classes for everything. While in CoffeeCup you can do `div '#id.class.class'`, specialized languages often have an even shorter syntax for that.
4ffd222 @mauricemach Updated readme.
mauricemach authored
116
117 - 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).
118
119 - For your specific project/team/preferences, you think a limited and/or separate language for templating is actually beneficial.
75ee63a @mauricemach Initial import.
mauricemach authored
120
121 ## Installing
122
123 Just grab [node.js](http://nodejs.org/#download) and [npm](http://github.com/isaacs/npm) and you're set:
124
b8af523 @gradus updating readme
authored
125 npm install coffeecup
75ee63a @mauricemach Initial import.
mauricemach authored
126
b8af523 @gradus updating readme
authored
127 To get the `coffeecup` command, install it globally:
243c54b @mauricemach First go at updating the readme / added annotated source through docco.
mauricemach authored
128
b8af523 @gradus updating readme
authored
129 npm install coffeecup -g
c342d0d @mauricemach Added instructions to install edge and mentioned 'reference.md'.
mauricemach authored
130
131 Or to use the latest version:
132
b8af523 @gradus updating readme
authored
133 git clone git@github.com:gradus/coffeecup.git && cd coffeecup
c342d0d @mauricemach Added instructions to install edge and mentioned 'reference.md'.
mauricemach authored
134 cake build
135 npm link
136 cd ~/myproject
b8af523 @gradus updating readme
authored
137 npm link coffeecup
243c54b @mauricemach First go at updating the readme / added annotated source through docco.
mauricemach authored
138
75ee63a @mauricemach Initial import.
mauricemach authored
139 ## Using
140
b8af523 @gradus updating readme
authored
141 cc = require 'coffeecup'
e8c2612 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
142
b8af523 @gradus updating readme
authored
143 cc.render -> h1 "You can feed me templates as functions."
144 cc.render "h1 'Or strings. I am not too picky.'"
51f1768 @mauricemach Updated README.
mauricemach authored
145
4ffd222 @mauricemach Updated readme.
mauricemach authored
146 Defining variables:
d5e9bd4 @mauricemach Updated README.
mauricemach authored
147
148 template = ->
149 h1 @title
150 form method: 'post', action: 'login', ->
151 textbox id: 'username'
152 textbox id: 'password'
153 button @title
154
155 helpers =
156 textbox: (attrs) ->
157 attrs.type = 'text'
158 attrs.name = attrs.id
243c54b @mauricemach First go at updating the readme / added annotated source through docco.
mauricemach authored
159 input attrs
d5e9bd4 @mauricemach Updated README.
mauricemach authored
160
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
161 cc.render(template, title: 'Log In', hardcode: helpers)
75ee63a @mauricemach Initial import.
mauricemach authored
162
51f1768 @mauricemach Updated README.
mauricemach authored
163 Precompiling to functions:
164
a8ccdd5 @gradus update cakefile
authored
165 template = cc.compile(template, locals: yes, hardcode: {zig: 'zag'})
4ffd222 @mauricemach Updated readme.
mauricemach authored
166
167 template(foo: 'bar', locals: {ping: 'pong'})
6cacf2d @mauricemach Added a zappa example.
mauricemach authored
168
75ee63a @mauricemach Initial import.
mauricemach authored
169 With [express](http://expressjs.com):
170
171 app.set 'view engine', 'coffee'
b8af523 @gradus updating readme
authored
172 app.register '.coffee', require('coffeecup').adapters.express
e8c2612 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
173
75ee63a @mauricemach Initial import.
mauricemach authored
174 app.get '/', (req, res) ->
175 # Will render views/index.coffee:
243c54b @mauricemach First go at updating the readme / added annotated source through docco.
mauricemach authored
176 res.render 'index', foo: 'bar'
75ee63a @mauricemach Initial import.
mauricemach authored
177
4ffd222 @mauricemach Updated readme.
mauricemach authored
178 With [zappa](http://github.com/mauricemach/zappa):
3965393 @mauricemach Added Meryl example, updated README.
mauricemach authored
179
4ffd222 @mauricemach Updated readme.
mauricemach authored
180 get '/': ->
181 @franks = ['miller', 'oz', 'sinatra', 'zappa']
182 render 'index'
183
184 view index: ->
185 for name in @franks
186 a href: "http://en.wikipedia.org/wiki/Frank_#{name}", -> name
187
188 With [meryl](https://github.com/kadirpekel/meryl/tree/master/examples/coffeekup-template):
189
b8af523 @gradus updating readme
authored
190 coffeekup = require 'coffeecup'
4ffd222 @mauricemach Updated readme.
mauricemach authored
191
192 meryl.get '/', (req, resp) ->
fe1357d @mauricemach Added framework adapters to ease integration.
mauricemach authored
193 people = ['bob', 'alice', 'meryl']
194 resp.render 'layout', content: 'index', context: {people: people}
3965393 @mauricemach Added Meryl example, updated README.
mauricemach authored
195
196 meryl.run
197 templateExt: '.coffee'
b8af523 @gradus updating readme
authored
198 templateFunc: coffeecup.adapters.meryl
3965393 @mauricemach Added Meryl example, updated README.
mauricemach authored
199
d5e9bd4 @mauricemach Updated README.
mauricemach authored
200 On the browser:
75ee63a @mauricemach Initial import.
mauricemach authored
201
51f1768 @mauricemach Updated README.
mauricemach authored
202 <script src="template.js"></script>
203 <script>
b409d7d @rachel-carvalho Added compile to js option to CLI. Closes #58.
rachel-carvalho authored
204 $('body').append(templates.template({foo: 'bar'}));
51f1768 @mauricemach Updated README.
mauricemach authored
205 </script>
e8c2612 @mauricemach Fixed context vars at the root and issue with the coffeescript "filter".
mauricemach authored
206
b8af523 @gradus updating readme
authored
207 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/gradus/coffeecup/blob/master/examples/browser/regular/index.html), [decaf](http://github.com/gradus/coffeecup/blob/master/examples/browser/decaf/index.html) and [crème](http://github.com/gradus/coffeecup/blob/master/examples/browser/creme/index.html).
75ee63a @mauricemach Initial import.
mauricemach authored
208
209 Command-line:
210
b8af523 @gradus updating readme
authored
211 $ coffeecup -h
e6b3b49 @mauricemach Added -u/--utils to command, updated README.
mauricemach authored
212
213 Usage:
b8af523 @gradus updating readme
authored
214 coffeecup [options] path/to/template.coffee
e6b3b49 @mauricemach Added -u/--utils to command, updated README.
mauricemach authored
215
b409d7d @rachel-carvalho Added compile to js option to CLI. Closes #58.
rachel-carvalho authored
216 --js compile template to js function
217 -n, --namespace global object holding the templates (default: "templates")
8482d3c @mauricemach Updated changelog.
mauricemach authored
218 -w, --watch watch templates for changes, and recompile
219 -o, --output set the directory for compiled html
220 -p, --print print the compiled html to stdout
221 -f, --format apply line breaks and indentation to html output
222 -u, --utils add helper locals (currently only "render")
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
223 -v, --version display CoffeeCup version
8482d3c @mauricemach Updated changelog.
mauricemach authored
224 -h, --help display this help message
75ee63a @mauricemach Initial import.
mauricemach authored
225
b8af523 @gradus updating readme
authored
226 See [/examples](http://github.com/gradus/coffeekup/tree/master/examples) for complete versions (you have to run `cake build` first).
74b3cf1 @mauricemach Added note to run `cake build` before trying examples (prompted by #63).
mauricemach authored
227
228 Please note that even though all examples are given in CoffeeScript, you can also use their plain JavaScript counterparts just fine.
75ee63a @mauricemach Initial import.
mauricemach authored
229
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
230 ## Resources
d3091b4 @mauricemach Added link to Mark Hahn's intro to CoffeeKup.
mauricemach authored
231
67b4dda @awwx Fix link to API reference.
awwx authored
232 - [API reference](https://github.com/gradus/coffeecup/blob/master/docs/reference.md)
c342d0d @mauricemach Added instructions to install edge and mentioned 'reference.md'.
mauricemach authored
233
9f3930c @gradus updating readme
authored
234 - [Issues](https://github.com/gradus/coffeecup/issues)
c06affd @mauricemach README tweaks.
mauricemach authored
235
bc3c327 @gradus add google group to readme
authored
236 - [Google Group](https://groups.google.com/forum/#!forum/coffeecup_)
237
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
238 - [A Beginners's Introduction to CoffeeCup](https://github.com/mark-hahn/coffeekup-intro)
a4459cc @mauricemach Added related projects and thanks sections to readme.
mauricemach authored
239
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
240 ## Tools
2084382 @mauricemach Split up resources and related projects.
mauricemach authored
241
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
242 - [html2coffeekup](https://github.com/brandonbloom/html2coffeekup) - Converts HTML to CoffeeCup templates.
a4459cc @mauricemach Added related projects and thanks sections to readme.
mauricemach authored
243
30ac37f @mauricemach Added htmlkup.
mauricemach authored
244 - [htmlkup](https://github.com/colinta/htmlkup) - Another HTML converter, stdin/stdout based.
245
ca9ef69 @twilson63 uglify-js is a dependency
twilson63 authored
246 - [html2coffeecup-app](https://html2coffeecup.nodejitsu.com) - html to CoffeeCup web app.
0551087 @twilson63 added html2coffeecup web app and iron-coffee to the additional projec…
twilson63 authored
247
a8ccdd5 @gradus update cakefile
authored
248 - [creamer](https://github.com/twilson63/creamer) - A flatiron plugin for coffeecup
249
250 - [coffeecup-helpers](https://github.com/twilson63/coffeecup-helpers) - CoffeeCup Html Helpers
251
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
252 - [ice](https://github.com/ludicast/ice) - CoffeeCup and Eco in Rails ([screencast](http://vimeo.com/25907220)).
bfa834b @mauricemach Added ice (CoffeeKup and Eco for Rails) to related projects.
mauricemach authored
253
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
254 - [coffee-world](https://github.com/khoomeister/coffee-world) - Tool to watch and compile HTML with CoffeeCup, CSS with coffee-css and JS with CoffeeScript.
bb00191 @mauricemach Added more resources and related projects.
mauricemach authored
255
b427ed8 @gradus add optparse as dependencie for coffeecup bin.
authored
256 - [cupcake](https://github.com/twilson63/cupcake) - Express app generator with CoffeeCup support.
867c8f4 @mauricemach Bumped master version to 0.3.0beta2.
mauricemach authored
257
2084382 @mauricemach Split up resources and related projects.
mauricemach authored
258 ## Related projects
259
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
260 - [ck](https://github.com/aeosynth/ck) - "a smaller, faster coffeekup": Alternative, barebones implementation.
e1ee49d @mauricemach Fixed readme.
mauricemach authored
261
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
262 - [ckup](https://github.com/satyr/ckup) - "Markup as Coco": Similar engine but for [Coco](https://github.com/satyr/coco) ("Unfancy CoffeeScript").
e1ee49d @mauricemach Fixed readme.
mauricemach authored
263
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
264 - [Eco](https://github.com/sstephenson/eco) - "Embedded CoffeeScript templates": "EJS/ERB" for CoffeeScript.
a4459cc @mauricemach Added related projects and thanks sections to readme.
mauricemach authored
265
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
266 - [timbits](https://github.com/Postmedia/timbits) - "Widget framework based on Express and CoffeeScript".
bb00191 @mauricemach Added more resources and related projects.
mauricemach authored
267
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
268 - [coffee-css](https://github.com/khoomeister/coffee-css) - "More CSS for CoffeeScript".
bb00191 @mauricemach Added more resources and related projects.
mauricemach authored
269
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
270 - [ccss](https://github.com/aeosynth/ccss) - "CoffeeScript CSS".
271
a8ccdd5 @gradus update cakefile
authored
272 - [black-coffee](https://github.com/gradus/black-coffee) - Flatiron and Coffee-Script Template.
273
0551087 @twilson63 added html2coffeecup web app and iron-coffee to the additional projec…
twilson63 authored
274 - [iron-coffee](https://github.com/twilson63/iron-coffee) - Flatiron and Coffee-Script Template.
275
a8ccdd5 @gradus update cakefile
authored
276
e505e78 @mauricemach Added mailing list, other tweaks.
mauricemach authored
277 ## Compatibility
278
f0ab647 @gradus update coffee-script compatability version in readme
authored
279 Latest version tested with node 0.6.11 and CoffeeScript 1.2.0.
bb00191 @mauricemach Added more resources and related projects.
mauricemach authored
280
a4459cc @mauricemach Added related projects and thanks sections to readme.
mauricemach authored
281 ## Special thanks
282
283 - [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
284 - [why the lucky stiff](Why_the_lucky_stiff), for the inspiration.
Something went wrong with that request. Please try again.