Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 321 lines (235 sloc) 8.165 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
17 * App and resource generators
18 * Content-negotiation
da8a19d @mde Update README.md
mde authored
19 * Session support (in-memory, cookie)
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
20 * Templating (EJS), partials support
21 * Fully non-blocking
22
23 ### License
24
25 Apache License, Version 2
26
e0dc47a @mde Updated README with 0.2 changes.
mde authored
27 ### Prerequisites
3b12a23 @mde Added mailing list info.
mde authored
28
1af68a6 @mde Update README.md
mde authored
29 Geddy requires version 0.4.x of Node.js or higher, and the
e0dc47a @mde Updated README with 0.2 changes.
mde authored
30 [Jake](https://github.com/mde/jake) JavaScript build-tool.
3b2b7c6 @mde Added mailing list and IRC info.
mde authored
31
e0dc47a @mde Updated README with 0.2 changes.
mde authored
32 ### Installing
fa6a6ec Added note about prereqs and building.
mde authored
33
34 To get Geddy from GitHub and install it:
35
36 git clone git://github.com/mde/geddy.git
37 cd geddy
38 make && sudo make install
39
ae163f3 @mde Updated README with custom-install-location info.
mde authored
40 By default Geddy is installed in "/usr/local." To install it into a
41 different directory (e.g., one that doesn't require super-user
42 privilege), pass the PREFIX variable to the `make install` command.
43 For example, to install it into a "geddy" directory in your home
44 directory, you could use this:
45
46 make && make install PREFIX=~/geddy
47
48 If you do install Geddy somewhere special, you'll need to add the
49 "bin" directory in the install target to your PATH to get access
50 to the `geddy` executable.
51
4b71fb1 @mde Added NPM install instructions.
mde authored
52 ### Installing with [NPM](http://npmjs.org/)
53
54 npm install -g geddy
55
56 Note that Geddy (specifically, the generators) is a system-level
57 tool, and wants to be installed globally.
58
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
59 ### Routes
60
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
61 Routes are similar to Merb or Rails routes.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
62
63 **Basic routes**
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
64
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
65 ```javascript
66 router.match('/moving/pictures/:id').to(
67 {controller: 'Moving', action: 'pictures'});
f00e1d5 Proofreading.
mde authored
68
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
69 router.match('/farewells/:farewelltype/kings/:kingid').to(
70 {controller: 'Farewells', action: 'kings'});
f00e1d5 Proofreading.
mde authored
71
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
72 //Can also match specific HTTP methods only
73 router.match('/xandadu', 'get').to(
74 {controller: 'Xandadu', action: 'specialHandler'});
75 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
76
77 **Resource-based routes**
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
78
79 router.resource('hemispheres');
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
80
81 ### Creating a Geddy app
82
e0dc47a @mde Updated README with 0.2 changes.
mde authored
83 You can use Geddy to create an app. Run `geddy app [app-name]` to
84 create an app. Then Run `geddy` inside the app-directory to start
85 the server.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
86
e0dc47a @mde Updated README with 0.2 changes.
mde authored
87 mde@localhost:~/work$ geddy app bytor
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
88 Created app bytor.
89 mde@localhost:~/work$ cd bytor
90 mde@localhost:~/work/bytor$ geddy
3b5e098 @mde Changed default port to 4000.
mde authored
91 Server running at http://127.0.0.1:4000/
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
92
3b5e098 @mde Changed default port to 4000.
mde authored
93 Go to http://localhost:4000/, and you should see:
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
94
531d4d4 Hacking in basic cookie and session support.
mde authored
95 Attention all planets of the Solar Federation
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
96
97 ### Adding resources
98
e0dc47a @mde Updated README with 0.2 changes.
mde authored
99 Use `geddy resource` in your app directory to add a
f00e1d5 Proofreading.
mde authored
100 resource. The route will be set up automatically for you.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
101
9e87037 @mde Updated docs to remove reference to old geddy-gen utility.
mde authored
102 mde@localhost:~/work/bytor$ geddy resource snow_dog
28fb1d9 Updated Readme.md
pjeweb authored
103 [ADDED] app/models/snow_dog.js
104 [ADDED] app/controllers/snow_dogs.js
105 Resource snow_dogs route added to config/router.js
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
106 Created view templates.
107
108 Restart Geddy, and you'll see the new route working. Hit your
3b5e098 @mde Changed default port to 4000.
mde authored
109 new route -- for example, http://localhost:4000/snow_dogs.json,
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
110 and you should see something like this:
111
7f414ae @larzconwell Added new Jade example
larzconwell authored
112 {"method":"index","params":{"extension":"json"}}
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
113
e0dc47a @mde Updated README with 0.2 changes.
mde authored
114 The geddy generator utility also handles fancy pluralization
115 between model and controller. Specify your resource-name as a
116 singular naun, and the generator will do the right thing --
117 changing 'person' to 'people,' etc.
487669e @mde Updated README to describe model stubs and pluralization with geddy-gen ...
mde authored
118
4e85834 More info about resource routes, content-negotiation.
mde authored
119 ### App layout
120
121 After adding a resource, a Geddy app is laid out like this:
122
123 mde@localhost:~/work/bytor$ find .
124 .
125 ./config
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
126 ./config/config.js
127 ./config/router.js
4e85834 More info about resource routes, content-negotiation.
mde authored
128 ./app
28fb1d9 Updated Readme.md
pjeweb authored
129 ./app/models
130 ./app/models/snow_dog.js
4e85834 More info about resource routes, content-negotiation.
mde authored
131 ./app/controllers
132 ./app/controllers/snow_dogs.js
133 ./app/controllers/main.js
134 ./app/controllers/application.js
135 ./app/views
136 ./app/views/snow_dogs
28fb1d9 Updated Readme.md
pjeweb authored
137 ./app/views/snow_dogs/edit.html.ejs
4e85834 More info about resource routes, content-negotiation.
mde authored
138 ./app/views/snow_dogs/show.html.ejs
139 ./app/views/snow_dogs/index.html.ejs
28fb1d9 Updated Readme.md
pjeweb authored
140 ./app/views/snow_dogs/add.html.ejs
4e85834 More info about resource routes, content-negotiation.
mde authored
141 ./public
142
143 ### Resources and controllers
144
145 Geddy's resource-based routes create url/request-method mappings
146 for easy CRUD operations like this:
147
f918541 @mde No really, update the README with the extension stuff.
mde authored
148 GET */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
149 (SnowDogs controller, index action)
150
f918541 @mde No really, update the README with the extension stuff.
mde authored
151 GET */snow_dogs/add[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
152 (SnowDogs controller, add action, for any new-resource template
153 -- "new" is not usable as a JavaScript action name)
154
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
155 POST */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
156 (SnowDogs controller, create action)
157
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
158 GET */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
159 (SnowDogs controller, show action)
160
b5d810c @mde Bumped Node version number, removed semicolon hack for edit path in rout...
mde authored
161 GET */snow_dogs/:id/edit[.extension]<br/>
2b96485 @mde Added support for create/update routing, for _method param override.
mde authored
162 (SnowDogs controller, edit action)
163
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
164 PUT */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
165 (SnowDogs controller, update action)
166
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
167 DELETE */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
168 (SnowDogs controller, remove action)
169
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
170 A simple controller that just responds with any
171 form-post/query-string params looks like this:
172
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
173 ```javascript
174 var SnowDogs = function () {
175 this.respondsWith = ['text', 'json', 'html'];
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
176
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
177 this.index = function (params) {
178 this.respond({params: params});
179 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
180
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
181 this.add = function (params) {
182 this.respond({params: params});
183 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
184
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
185 this.create = function (params) {
186 this.respond({params: params});
187 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
188
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
189 this.show = function (params) {
190 this.respond({params: params});
191 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
192
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
193 this.update = function (params) {
194 this.respond({params: params});
195 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
196
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
197 this.remove = function (params) {
198 this.respond({params: params});
199 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
200
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
201 };
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
202
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
203 exports.SnowDogs = SnowDogs;
204 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
205
4e85834 More info about resource routes, content-negotiation.
mde authored
206 ## Content-negotiation
207
a0f33a2 @mde README updates.
mde authored
208 Geddy can perform content-negotiation, and respond with with the
209 correct format based on the requested filename-extension.
4e85834 More info about resource routes, content-negotiation.
mde authored
210
a0f33a2 @mde README updates.
mde authored
211 If you have a JSON-serializable JavaScript object you want to
212 return in JSON format, pass your JavaScript object to the
4e85834 More info about resource routes, content-negotiation.
mde authored
213 `respond` method in the action on that controller.
214
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
215 ```javascript
216 this.respondsWith = ['text', 'json'];
4e85834 More info about resource routes, content-negotiation.
mde authored
217
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
218 this.show = function (params) {
219 // (Fetch some item by params.id)
220 item = {foo: 'FOO', bar: 1, baz: false};
221 this.respond(item);
222 };
223 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
224
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
225 ## Models and validations
226
a0f33a2 @mde README updates.
mde authored
227 Geddy has a simple way of defining models, with a full-featured
228 set of data validations. The syntax is very similar to models in
229 Ruby's ActiveRecord or DataMapper.
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
230
231 Here is an example of a model with some validations:
232
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
233 ```javascript
234 var User = function () {
235 this.property('login', 'string', {required: true});
236 this.property('password', 'string', {required: true});
237 this.property('lastName', 'string');
238 this.property('firstName', 'string');
239
240 this.validatesPresent('login');
241 this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
242 this.validatesLength('login', {min: 3});
243 this.validatesConfirmed('password', 'confirmPassword');
244 this.validatesWithFunction('password', function (s) {
245 // Something that returns true or false
246 return s.length > 0;
247 });
248
249 // Can define methods for instances like this
250 this.someMethod = function () {
251 // Do some stuff
252 };
253 };
254
255 // Can also define them on the prototype
256 User.prototype.someOtherMethod = function () {
257 // Do some other stuff
258 };
259
260 User = geddy.model.registerModel('User', User);
261 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
262
bec0a56 @Techwraith added docs for the new defineProperties method on models
Techwraith authored
263 Alternatively, you can use the `defineProperties` method to lay out your model:
264
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
265 ```javascript
266 var User = function () {
267 this.defineProperties({
268 login: {type: 'string', required: true}
269 , password: {type: 'string', required: true}
270 , lastName: {type: 'string'}
271 , firstName: {type: 'string'}
272 });
273 }
274 ```
bec0a56 @Techwraith added docs for the new defineProperties method on models
Techwraith authored
275
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
276 Creating an instance of one of these models is easy:
277
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
278 ```javascript
279 var params = {
280 login: 'alex'
281 , password: 'lerxst'
282 , lastName: 'Lifeson'
283 , firstName: 'Alex'
284 };
285 var user = User.create(params);
286 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
287
288 Data-validation happens on the call to `create`, and any
289 validation errors show up inside an `errors` property on
290 the instance, keyed by field name. Instances have a `valid`
291 method that returns a Boolean indicating whether the instance
292 is valid.
293
b6173ba @OscarGodson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
294 ```javascript
295 // Leaving out the required password field
296 var params = {
297 login: 'alex'
298 };
299 var user = User.create(params);
300
301 // Prints 'false'
302 sys.puts(user.valid());
303 // Prints 'Field "password" is required'
304 sys.puts(user.errors.password);
305 ```
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
306
3fd1410 @mde Update README with info on running tests.
mde authored
307 ## Running the tests
308
309 In the geddy project directory, run `jake test`. The tests simply
1c07cec @mde Restored model-tests.
mde authored
310 use NodeJS's `assert` library, which throws an error on failure.
3fd1410 @mde Update README with info on running tests.
mde authored
311 If there are no errors, the tests all ran successfully.
312
5e5438c @mde Added API docs link to README.
mde authored
313 ## API Docs
314
315 API docs [can be found here](http://mde.github.com/geddy/doc/).
316
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
317 - - -
318 Geddy Web-app development framework copyright 2112
319 mde@fleegix.org.
320
Something went wrong with that request. Please try again.