Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 358 lines (266 sloc) 9.788 kb
310fcb9 @mde Updated README, simplified title.
mde authored
1 ## Geddy web framework for Node.js
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
2 - - -
3
4 ### Goals
5
1fc7dbf @mde Simplfied goals in README.
mde authored
6 * Easy to use
7 * Modular
8 * Fast
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
9
10 Geddy should make things easy for the most basic applications,
11 but still let you get under the hood and tinker if you want.
12
13 ### Features
14
15 * Powerful, flexible router
16 * Easy resource-based routing
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
17 * App, resource and scaffold generators
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
18 * Content-negotiation
da8a19d @mde Update README.md
mde authored
19 * Session support (in-memory, cookie)
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
20 * Multiple template engine support(EJS, Jade, Mustache, Handlebars)
21 * View helpers([Docs](https://github.com/mde/geddy/wiki/View-Helpers))
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
22 * Fully non-blocking
23
24 ### License
25
26 Apache License, Version 2
27
e0dc47a @mde Updated README with 0.2 changes.
mde authored
28 ### Prerequisites
3b12a23 @mde Added mailing list info.
mde authored
29
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
30 Geddy requires version 0.6.x of Node.js or higher, and the
e0dc47a @mde Updated README with 0.2 changes.
mde authored
31 [Jake](https://github.com/mde/jake) JavaScript build-tool.
3b2b7c6 @mde Added mailing list and IRC info.
mde authored
32
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
33 ### Installing from Github
fa6a6ec Added note about prereqs and building.
mde authored
34
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
35 To get Geddy from Github and install it do:
fa6a6ec Added note about prereqs and building.
mde authored
36
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
37 ```
38 git clone git@github.com:mde/geddy.git
39 cd geddy
40 make && sudo make install
41 ```
fa6a6ec Added note about prereqs and building.
mde authored
42
ae163f3 @mde Updated README with custom-install-location info.
mde authored
43 By default Geddy is installed in "/usr/local." To install it into a
44 different directory (e.g., one that doesn't require super-user
45 privilege), pass the PREFIX variable to the `make install` command.
46 For example, to install it into a "geddy" directory in your home
47 directory, you could use this:
48
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
49 ```
50 make && make install PREFIX=~/geddy
51 ```
ae163f3 @mde Updated README with custom-install-location info.
mde authored
52
53 If you do install Geddy somewhere special, you'll need to add the
54 "bin" directory in the install target to your PATH to get access
55 to the `geddy` executable.
56
4b71fb1 @mde Added NPM install instructions.
mde authored
57 ### Installing with [NPM](http://npmjs.org/)
58
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
59 ```
60 [sudo] npm -g install geddy
61 ```
4b71fb1 @mde Added NPM install instructions.
mde authored
62
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
63 Note: Geddy (specifically, the generators) is a system-level
4b71fb1 @mde Added NPM install instructions.
mde authored
64 tool, and wants to be installed globally.
65
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
66 ### Creating a Geddy application
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
67
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
68 To create Geddy applications simply run `geddy app <name>`.
69 Then you can run `geddy` inside the application to start the server.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
70
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
71 ```
72 mde@localhost:~/work$ geddy app bytor
73 Created app bytor.
74 mde@localhost:~/work$ cd bytor
75 mde@localhost:~/work/bytor$ geddy
76 Server running at http://127.0.0.1:4000/
77 ```
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
78
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
79 Go to http://localhost:4000/, and you should see the introduction page.
f00e1d5 Proofreading.
mde authored
80
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
81 ### Generating resources
f00e1d5 Proofreading.
mde authored
82
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
83 Use `geddy resource <name> [model properties]` to generate a resource in your application.
84 Resources do not generate views, but creates a view directory. A resource route will be
85 created for you.
86
87 ````
88 mde@localhost:~/work$ geddy resource snow_dog breed:string name:string color:string
89 [Added] app/models/snow_dog.js
90 [Added] app/controllers/snow_dogs.js
91 [Added] Resource snow_dogs route added to config/router.js
92 [Added] snow_dogs view directory
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
93 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
94
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
95 Now start your Geddy server and your new route will work. Trying this for example
96 will return the params for the index action in JSON:
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
97
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
98 ```
99 $ curl localhost:4000/snow_dogs.json
100 {"params":{"method":"GET","controller":"SnowDogs","action":"index","format":"json"}}
101 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
102
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
103 Geddy generators handle plural inflections for model and controller names. ex: 'person' to 'people'
104 To read about the model properties argument jump to [Model properties](#model-properties)
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
105
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
106 ### Generating scaffolding
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
107
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
108 Use `geddy scaffold <name> [model properties]` to generate scaffoling in your application.
109 Scaffolding creates full CRUD actions includes views, and will default your configuration to use
110 [Mongodb](http://www.mongodb.org/) Resource routes will be created for you.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
111
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
112 ````
113 mde@localhost:~/work$ geddy resource snow_dog breed:string name:string color:string
114 [Added] app/models/snow_dog.js
115 [Added] app/controllers/snow_dogs.js
116 [Added] Resource snow_dogs route added to config/router.js
117 [Added] View templates
118 [Added] Database configuration to config/environment.js
119 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
120
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
121 Now start your Geddy server and you'll have new views created from scaffolding. Trying this for example
122 will return the content for the index action in HTML:
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
123
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
124 ```
125 $ curl localhost:4000/snow_dogs
126 <!DOCTYPE html>
127 <html lang="en">
128 <head>
129 <meta charset="utf-8">
130 <title>Geddy App | This app uses Geddy.js</title>
131 <meta name="description" content="">
132 <meta name="author" content="">
133
134 <meta name="viewport" content="width=device-width" />
135
136 <!-- The HTML5 shim, for IE6-8 support of HTML elements -->
137 <!--[if lt IE 9]>
138 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
139 <![endif]-->
140
141 .....
142 ```
143
144 Geddy generators handle plural inflections for model and controller names. ex: 'person' to 'people'
145 To read about the model properties argument jump to [Model properties](#model-properties)
146
147 ### Model properties
148
149 Some Geddy generators (resource, scaffold and model) have a argument that takes a list of model
150 properties. Here's an example of a resource with some properties:
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
151
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
152 ```
153 geddy resource user name admin:boolean lastLogin:datetime
154 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
155
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
156 Each of these items include a name and an optional type, if there's no type given it'll default
157 to string. The list of supported types are listed in the [model](https://github.com/mde/geddy/wiki/Models) documentation.
158 If no id property is given then a default id property will be created with the type of string.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
159
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
160 ### Routes
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
161
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
162 Routes are created in a similar fashion to Merb or Rails.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
163
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
164 ***Basic routes***
165 ```
166 router.match('/moving/pictures/:id').to(
167 {controller: 'Moving', action: 'pictures'});
487669e @mde Updated README to describe model stubs and pluralization with geddy-gen ...
mde authored
168
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
169 router.match('/farewells/:farewelltype/kings/:kingid').to(
170 {controller: 'Farewells', action: 'kings'});
4e85834 More info about resource routes, content-negotiation.
mde authored
171
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
172 //Can also match specific HTTP methods only
173 router.match('/xandadu', 'get').to(
174 {controller: 'Xandadu', action: 'specialHandler'});
175 ```
4e85834 More info about resource routes, content-negotiation.
mde authored
176
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
177 ***Resource routes***
178 ```
179 router.resource('hemispheres');
180 ```
4e85834 More info about resource routes, content-negotiation.
mde authored
181
182 ### Resources and controllers
183
184 Geddy's resource-based routes create url/request-method mappings
185 for easy CRUD operations like this:
186
f918541 @mde No really, update the README with the extension stuff.
mde authored
187 GET */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
188 (SnowDogs controller, index action)
189
f918541 @mde No really, update the README with the extension stuff.
mde authored
190 GET */snow_dogs/add[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
191 (SnowDogs controller, add action, for any new-resource template
192 -- "new" is not usable as a JavaScript action name)
193
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
194 POST */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
195 (SnowDogs controller, create action)
196
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
197 GET */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
198 (SnowDogs controller, show action)
199
b5d810c @mde Bumped Node version number, removed semicolon hack for edit path in rout...
mde authored
200 GET */snow_dogs/:id/edit[.extension]<br/>
2b96485 @mde Added support for create/update routing, for _method param override.
mde authored
201 (SnowDogs controller, edit action)
202
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
203 PUT */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
204 (SnowDogs controller, update action)
205
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
206 DELETE */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
207 (SnowDogs controller, remove action)
208
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
209 A simple controller that just responds with any
210 form-post/query-string params looks like this:
211
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
212 ```javascript
213 var SnowDogs = function () {
214 this.respondsWith = ['text', 'json', 'html'];
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
215
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
216 this.index = function (params) {
217 this.respond({params: params});
218 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
219
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
220 this.add = function (params) {
221 this.respond({params: params});
222 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
223
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
224 this.create = function (params) {
225 this.respond({params: params});
226 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
227
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
228 this.show = function (params) {
229 this.respond({params: params});
230 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
231
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
232 this.update = function (params) {
233 this.respond({params: params});
234 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
235
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
236 this.remove = function (params) {
237 this.respond({params: params});
238 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
239
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
240 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
241
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
242 exports.SnowDogs = SnowDogs;
243 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
244
4e85834 More info about resource routes, content-negotiation.
mde authored
245 ## Content-negotiation
246
a0f33a2 @mde README updates.
mde authored
247 Geddy can perform content-negotiation, and respond with with the
248 correct format based on the requested filename-extension.
4e85834 More info about resource routes, content-negotiation.
mde authored
249
a0f33a2 @mde README updates.
mde authored
250 If you have a JSON-serializable JavaScript object you want to
251 return in JSON format, pass your JavaScript object to the
4e85834 More info about resource routes, content-negotiation.
mde authored
252 `respond` method in the action on that controller.
253
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
254 ```javascript
255 this.respondsWith = ['text', 'json'];
4e85834 More info about resource routes, content-negotiation.
mde authored
256
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
257 this.show = function (params) {
258 item = {foo: 'FOO', bar: 1, baz: false};
259 this.respond(item);
260 };
261 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
262 ## Models and validations
263
a0f33a2 @mde README updates.
mde authored
264 Geddy has a simple way of defining models, with a full-featured
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
265 set of data validations. The syntax is similar to models in
a0f33a2 @mde README updates.
mde authored
266 Ruby's ActiveRecord or DataMapper.
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
267
268 Here is an example of a model with some validations:
269
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
270 ```javascript
271 var User = function () {
272 this.property('login', 'string', {required: true});
273 this.property('password', 'string', {required: true});
274 this.property('lastName', 'string');
275 this.property('firstName', 'string');
276
277 this.validatesPresent('login');
278 this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
279 this.validatesLength('login', {min: 3});
280 this.validatesConfirmed('password', 'confirmPassword');
281 this.validatesWithFunction('password', function (s) {
282 // Something that returns true or false
283 return s.length > 0;
284 });
285
286 // Can define methods for instances like this
287 this.someMethod = function () {
288 // Do some stuff
289 };
290 };
291
292 // Can also define them on the prototype
293 User.prototype.someOtherMethod = function () {
294 // Do some other stuff
295 };
296
297 User = geddy.model.registerModel('User', User);
298 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
299
bec0a56 @Techwraith added docs for the new defineProperties method on models
Techwraith authored
300 Alternatively, you can use the `defineProperties` method to lay out your model:
301
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
302 ```javascript
303 var User = function () {
304 this.defineProperties({
305 login: {type: 'string', required: true}
306 , password: {type: 'string', required: true}
307 , lastName: {type: 'string'}
308 , firstName: {type: 'string'}
309 });
310 }
311 ```
bec0a56 @Techwraith added docs for the new defineProperties method on models
Techwraith authored
312
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
313 Creating an instance of one of these models is easy:
314
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
315 ```javascript
316 var params = {
317 login: 'alex'
318 , password: 'lerxst'
319 , lastName: 'Lifeson'
320 , firstName: 'Alex'
321 };
322 var user = User.create(params);
323 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
324
325 Data-validation happens on the call to `create`, and any
326 validation errors show up inside an `errors` property on
327 the instance, keyed by field name. Instances have a `valid`
328 method that returns a Boolean indicating whether the instance
329 is valid.
330
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
331 ```javascript
332 // Leaving out the required password field
333 var params = {
334 login: 'alex'
335 };
336 var user = User.create(params);
337
338 // Prints 'false'
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
339 util.puts(user.valid());
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
340 // Prints 'Field "password" is required'
a082031 @larzconwell Updated readme to reflect new generators
larzconwell authored
341 util.puts(user.errors.password);
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
342 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
343
3fd1410 @mde Update README with info on running tests.
mde authored
344 ## Running the tests
345
346 In the geddy project directory, run `jake test`. The tests simply
1c07cec @mde Restored model-tests.
mde authored
347 use NodeJS's `assert` library, which throws an error on failure.
3fd1410 @mde Update README with info on running tests.
mde authored
348 If there are no errors, the tests all ran successfully.
349
5e5438c @mde Added API docs link to README.
mde authored
350 ## API Docs
351
352 API docs [can be found here](http://mde.github.com/geddy/doc/).
353
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
354 - - -
355 Geddy Web-app development framework copyright 2112
356 mde@fleegix.org.
357
Something went wrong with that request. Please try again.