Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Updated documentation

  • Loading branch information...
commit 93a018a700dd72eb24b9ef2a46437e838e4149a2 1 parent 82e0705
Cameron Bytheway camshaft authored

Showing 3 changed files with 246 additions and 45 deletions. Show diff stats Hide diff stats

  1. +8 0 LICENSE
  2. +237 44 README.md
  3. +1 1  package.json
8 LICENSE
... ... @@ -0,0 +1,8 @@
  1 +The MIT License (MIT)
  2 +Copyright (c) 2012 Cameron Bytheway <cameron@nujii.com>
  3 +
  4 +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
  5 +
  6 +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  7 +
  8 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
281 README.md
Source Rendered
... ... @@ -1,7 +1,234 @@
1 1 CoffeeScript meets Collection+JSON (cscj) [![Build Status](https://secure.travis-ci.org/CamShaft/cscj.png)](http://travis-ci.org/CamShaft/cscj)
2 2 =========================================
3 3
4   -cscj is a little templating library that makes writing the Collection+JSON media type painless:
  4 +cscj is a little templating library that makes writing the Collection+JSON media type painless.
  5 +
  6 +Public API
  7 +----------
  8 +
  9 +```coffee
  10 +cscj = require "cscj"
  11 +
  12 +view = """
  13 +@collection ->
  14 + @href "http://example.com"
  15 +"""
  16 +
  17 +fn = cscj.compile view, options
  18 +fn(locals)
  19 +```
  20 +
  21 +### Options
  22 +
  23 +* `locals` Local variable object
  24 +* `filename` Used in exceptions
  25 +* `debug` Outputs tokens and function body generated
  26 +
  27 +Syntax
  28 +------
  29 +
  30 +A collection is started by defining the root:
  31 +
  32 +```coffee
  33 +@collection ->
  34 +
  35 + # Collection parts go here
  36 +
  37 +```
  38 +
  39 +### Collection
  40 +
  41 +```coffee
  42 +@collection ->
  43 +
  44 + # Let's set our `href`
  45 + @href "http://example.com"
  46 +
  47 + # Oops there was an error!
  48 + @error title: "Not Found!", code: "404", message: "This is not the collection your are looking for"
  49 +
  50 + # We can also specify the error type
  51 + @error "password", title: "Invalid password": code: "400", message: "Too short"
  52 +
  53 + # We can add some links
  54 + @link href: "http://example.com", rel: "index"
  55 + @link href: "http://example.com/users", rel: "users"
  56 + @link href: "http://example.com/posts", rel: "posts"
  57 +
  58 + # Add an item
  59 + @item ->
  60 +
  61 + # Item parts go here
  62 +
  63 + # Add a query
  64 + @query ->
  65 +
  66 + # Query parts go here
  67 +
  68 + # Add a template
  69 + @template ->
  70 +
  71 + # Template parts go here
  72 +
  73 +```
  74 +
  75 +### Item
  76 +
  77 +```coffee
  78 +@item ->
  79 +
  80 + # Href
  81 + @href "http://example.com/users/1"
  82 +
  83 + # Links
  84 + @link href: "http://example.com/users/1/photos", rel: "photos"
  85 + @link href: "http://example.com/users/1/friends", rel: "friends"
  86 +
  87 + # Data
  88 + @datum name: "firstName", value: "Cameron", prompt: "First Name"
  89 + @datum name: "lastName", value: "Bytheway", prompt: "Last Name"
  90 +```
  91 +
  92 +### Query
  93 +
  94 +```coffee
  95 +@query ->
  96 +
  97 + # Href
  98 + @href "http://example.com/users"
  99 +
  100 + # Rel
  101 + @rel "users"
  102 +
  103 + # Data
  104 + @datum name: "firstName", prompt: "First Name"
  105 + @datum name: "lastName", prompt: "Last Name"
  106 +
  107 + # Optional
  108 +
  109 + # Encoding is defined by the extension for URI Templates
  110 + # https://github.com/mamund/collection-json/blob/master/extensions/uri-templates.md
  111 + @encoding "uri-template"
  112 +```
  113 +
  114 +### Template
  115 +
  116 +```coffee
  117 +@template ->
  118 +
  119 + # Data
  120 + @datum name: "firstName", prompt: "First Name"
  121 + @datum name: "lastName", prompt: "Last Name"
  122 +
  123 + # Optional
  124 +
  125 + # The following are defined by the extension for multiple templates
  126 + # https://github.com/mamund/collection-json/blob/master/extensions/templates.md
  127 +
  128 + @href "http://example.com/users/avatar"
  129 +
  130 + @rel "avatar"
  131 +
  132 + @type "application/x-www-form-urlencoded"
  133 +
  134 + @name "avatar"
  135 +```
  136 +
  137 +Referencing Local Variables
  138 +---------------------------
  139 +
  140 +When we pass in locals, they are referenced as normal variables:
  141 +
  142 +```coffee
  143 +# example.coffee
  144 +cscj = require "cscj"
  145 +
  146 +cscj.renderFile "./view.coffee", {root: "http://example.com"}, (error, collection)->
  147 + console.log collection
  148 +```
  149 +
  150 +```coffee
  151 +# view.coffee
  152 +@collection ->
  153 +
  154 + @href root
  155 +```
  156 +
  157 +Running this code will output:
  158 +
  159 +```json
  160 +{
  161 + "collection":{
  162 + "href":"http://example.com",
  163 + "version":"1.0"
  164 + }
  165 +}
  166 +```
  167 +
  168 +You can also define helpers:
  169 +
  170 +```coffee
  171 +# example2.coffee
  172 +cscj = require "cscj"
  173 +
  174 +locals =
  175 + links: (collection)->
  176 + collection.link rel: "index", href: "http://example.com"
  177 + collection.link rel: "users", href: "http://example.com/users"
  178 + root: "http://example.com"
  179 +
  180 +cscj.renderFile "./view.coffee", locals, (error, collection)->
  181 + console.log collection
  182 +```
  183 +
  184 +```coffee
  185 +# view.coffee
  186 +@collection ->
  187 +
  188 + @href root
  189 + links @
  190 +```
  191 +
  192 +Running this code will output:
  193 +
  194 +```json
  195 +{
  196 + "collection":{
  197 + "href":"http://example.com",
  198 + "version":"1.0",
  199 + "links": [
  200 + { "href": "http://example.com", "rel": "index" },
  201 + { "href": "http://example.com/users", "rel": "users" }
  202 + ]
  203 + }
  204 +}
  205 +```
  206 +
  207 +Using CoffeeScript
  208 +------------------
  209 +
  210 +Since the template is just CoffeeScript you can do some powerful stuff:
  211 +
  212 +```coffee
  213 +@collection ->
  214 + ...
  215 + for item in items
  216 + @item ->
  217 +
  218 + @href item.href
  219 +
  220 + # Iterate the links in the item
  221 + for link in item.links
  222 + @link rel: link.rel, href: link.href
  223 +
  224 + # Iterate the keys in the item and add them to the `data` array
  225 + for key, value in item
  226 + @datum name: key, value: value if not (key in ["href", "links"])
  227 + ...
  228 +```
  229 +
  230 +Example
  231 +-------
5 232
6 233 ```coffee
7 234 # views/index.coffee
@@ -39,36 +266,19 @@ which would render
39 266 "collection":{
40 267 "href":"http://localhost:5000",
41 268 "version":"1.0",
42   - "error":{
43   - "code":"404",
44   - "message":"This is a test"
45   - },
  269 + "error":{ "code":"404", "message":"This is a test" },
46 270 "links":[
47   - {
48   - "href":"http://localhost:5000",
49   - "rel":"index"
50   - }
  271 + { "href":"http://localhost:5000", "rel":"index" }
51 272 ],
52 273 "items":[
53 274 {
54 275 "href":"http://localhost:5000/people/1",
55 276 "links":[
56   - {
57   - "href":"http://localhost:5000/1/photos",
58   - "rel":"photos"
59   - }
  277 + { "href":"http://localhost:5000/1/photos", "rel":"photos" }
60 278 ],
61 279 "data":[
62   - {
63   - "name":"firstName",
64   - "value":"Cameron",
65   - "prompt":"First Name"
66   - },
67   - {
68   - "name":"lastName",
69   - "value":"Bytheway",
70   - "prompt":"Last Name"
71   - }
  280 + { "name":"firstName", "value":"Cameron", "prompt":"First Name" },
  281 + { "name":"lastName", "value":"Bytheway", "prompt":"Last Name" }
72 282 ]
73 283 }
74 284 ],
@@ -77,38 +287,21 @@ which would render
77 287 "href":"http://localhost:5000/people",
78 288 "rel":"people",
79 289 "data":[
80   - {
81   - "name":"firstName",
82   - "prompt":"First Name"
83   - },
84   - {
85   - "name":"lastName",
86   - "prompt":"Last Name"
87   - }
  290 + { "name":"firstName", "prompt":"First Name" },
  291 + { "name":"lastName", "prompt":"Last Name" }
88 292 ]
89 293 }
90 294 ],
91 295 "template":{
92 296 "data":[
93   - {
94   - "name":"firstName",
95   - "prompt":"First Name"
96   - },
97   - {
98   - "name":"lastName",
99   - "prompt":"Last Name"
100   - }
  297 + { "name":"firstName", "prompt":"First Name" },
  298 + { "name":"lastName", "prompt":"Last Name" }
101 299 ]
102 300 }
103 301 }
104 302 }
105 303 ```
106 304
107   -Usage
108   ------
109   -
110   -Just add it to your dependencies in `package.json` and you're ready to go!
111   -
112 305 Tests
113 306 -----
114 307 ```bash
2  package.json
@@ -11,7 +11,7 @@
11 11 },
12 12 "repository": "",
13 13 "author": "Cameron Bytheway",
14   - "license": "BSD",
  14 + "license": "MIT",
15 15 "dependencies": {
16 16 "coffee-dsl": "~0.0.0",
17 17 "coffee-script": "~1.3.3"

0 comments on commit 93a018a

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