Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 294 lines (209 sloc) 7.971 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
e0dc47a @mde Updated README with 0.2 changes.
mde authored
19 * Session support (in-memory, cookie, CouchDB)
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
3767939 @mde Limiting to Node 0.4.x.
mde authored
29 Geddy requires version 0.4.x of Node.js, 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
65 router.match('/moving/pictures/:id').to(
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
66 {controller: 'Moving', action: 'pictures'});
f00e1d5 Proofreading.
mde authored
67
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
68 router.match('/farewells/:farewelltype/kings/:kingid').to(
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
69 {controller: 'Farewells', action: 'kings'});
f00e1d5 Proofreading.
mde authored
70
71 //Can also match specific HTTP methods only
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
72 router.match('/xandadu', 'get').to(
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
73 {controller: 'Xandadu', action: 'specialHandler'});
74
75 **Resource-based routes**
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
76
77 router.resource('hemispheres');
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
78
79 ### Creating a Geddy app
80
e0dc47a @mde Updated README with 0.2 changes.
mde authored
81 You can use Geddy to create an app. Run `geddy app [app-name]` to
82 create an app. Then Run `geddy` inside the app-directory to start
83 the server.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
84
e0dc47a @mde Updated README with 0.2 changes.
mde authored
85 mde@localhost:~/work$ geddy app bytor
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
86 Created app bytor.
87 mde@localhost:~/work$ cd bytor
88 mde@localhost:~/work/bytor$ geddy
3b5e098 @mde Changed default port to 4000.
mde authored
89 Server running at http://127.0.0.1:4000/
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
90
3b5e098 @mde Changed default port to 4000.
mde authored
91 Go to http://localhost:4000/, and you should see:
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
92
531d4d4 Hacking in basic cookie and session support.
mde authored
93 Attention all planets of the Solar Federation
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
94
95 ### Adding resources
96
e0dc47a @mde Updated README with 0.2 changes.
mde authored
97 Use `geddy resource` in your app directory to add a
f00e1d5 Proofreading.
mde authored
98 resource. The route will be set up automatically for you.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
99
487669e @mde Updated README to describe model stubs and pluralization with geddy-gen ...
mde authored
100 mde@localhost:~/work/bytor$ geddy-gen resource snow_dog
101 [ADDED] ./app/models/snow_dog.js
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
102 [ADDED] ./app/controllers/snow_dogs.js
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
103 resources snow_dogs route added to ./config/router.js
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
104 Created view templates.
105
106 Restart Geddy, and you'll see the new route working. Hit your
3b5e098 @mde Changed default port to 4000.
mde authored
107 new route -- for example, http://localhost:4000/snow_dogs.json,
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
108 and you should see something like this:
109
110 {"method":"index","params":{"extension":"json"}}
111
e0dc47a @mde Updated README with 0.2 changes.
mde authored
112 The geddy generator utility also handles fancy pluralization
113 between model and controller. Specify your resource-name as a
114 singular naun, and the generator will do the right thing --
115 changing 'person' to 'people,' etc.
487669e @mde Updated README to describe model stubs and pluralization with geddy-gen ...
mde authored
116
4e85834 More info about resource routes, content-negotiation.
mde authored
117 ### App layout
118
119 After adding a resource, a Geddy app is laid out like this:
120
121 mde@localhost:~/work/bytor$ find .
122 .
123 ./config
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
124 ./config/config.js
125 ./config/router.js
4e85834 More info about resource routes, content-negotiation.
mde authored
126 ./app
127 ./app/controllers
128 ./app/controllers/snow_dogs.js
129 ./app/controllers/main.js
130 ./app/controllers/application.js
131 ./app/views
132 ./app/views/snow_dogs
133 ./app/views/snow_dogs/show.html.ejs
134 ./app/views/snow_dogs/add.html.ejs
135 ./app/views/snow_dogs/index.html.ejs
136 ./public
137
138 ### Resources and controllers
139
140 Geddy's resource-based routes create url/request-method mappings
141 for easy CRUD operations like this:
142
f918541 @mde No really, update the README with the extension stuff.
mde authored
143 GET */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
144 (SnowDogs controller, index action)
145
f918541 @mde No really, update the README with the extension stuff.
mde authored
146 GET */snow_dogs/add[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
147 (SnowDogs controller, add action, for any new-resource template
148 -- "new" is not usable as a JavaScript action name)
149
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
150 POST */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
151 (SnowDogs controller, create action)
152
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
153 GET */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
154 (SnowDogs controller, show action)
155
b5d810c @mde Bumped Node version number, removed semicolon hack for edit path in rout...
mde authored
156 GET */snow_dogs/:id/edit[.extension]<br/>
2b96485 @mde Added support for create/update routing, for _method param override.
mde authored
157 (SnowDogs controller, edit action)
158
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
159 PUT */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
160 (SnowDogs controller, update action)
161
b563a1c @mde Make the doc regarding RESTful routes clearly include the file extension...
mde authored
162 DELETE */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
163 (SnowDogs controller, remove action)
164
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
165 A simple controller that just responds with any
166 form-post/query-string params looks like this:
167
168 var SnowDogs = function () {
169 this.respondsWith = ['text', 'json', 'html'];
170
171 this.index = function (params) {
172 this.respond({params: params});
173 };
174
175 this.add = function (params) {
176 this.respond({params: params});
177 };
178
179 this.create = function (params) {
180 this.respond({params: params});
181 };
182
183 this.show = function (params) {
184 this.respond({params: params});
185 };
186
187 this.update = function (params) {
188 this.respond({params: params});
189 };
190
191 this.remove = function (params) {
192 this.respond({params: params});
193 };
194
195 };
196
197 exports.SnowDogs = SnowDogs;
198
199
4e85834 More info about resource routes, content-negotiation.
mde authored
200 ## Content-negotiation
201
a0f33a2 @mde README updates.
mde authored
202 Geddy can perform content-negotiation, and respond with with the
203 correct format based on the requested filename-extension.
4e85834 More info about resource routes, content-negotiation.
mde authored
204
a0f33a2 @mde README updates.
mde authored
205 If you have a JSON-serializable JavaScript object you want to
206 return in JSON format, pass your JavaScript object to the
4e85834 More info about resource routes, content-negotiation.
mde authored
207 `respond` method in the action on that controller.
208
209 this.respondsWith = ['text', 'json'];
210
211 this.show = function (params) {
212 // (Fetch some item by params.id)
213 item = {foo: 'FOO', bar: 1, baz: false};
214 this.respond(item);
215 };
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
216
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
217 ## Models and validations
218
a0f33a2 @mde README updates.
mde authored
219 Geddy has a simple way of defining models, with a full-featured
220 set of data validations. The syntax is very similar to models in
221 Ruby's ActiveRecord or DataMapper.
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
222
223 Here is an example of a model with some validations:
224
225 var User = function () {
7f15377 @mde Updated docs, tests, template to use new lowercase names for datatypes.
mde authored
226 this.property('login', 'string', {required: true});
227 this.property('password', 'string', {required: true});
228 this.property('lastName', 'string');
229 this.property('firstName', 'string');
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
230
231 this.validatesPresent('login');
232 this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
233 this.validatesLength('login', {min: 3});
234 this.validatesConfirmed('password', 'confirmPassword');
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
235 this.validatesWithFunction('password', function (s) {
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
236 // Something that returns true or false
237 return s.length > 0;
238 });
239
240 // Can define methods for instances like this
241 this.someMethod = function () {
242 // Do some stuff
243 };
244 };
245
246 // Can also define them on the prototype
247 User.prototype.someOtherMethod = function () {
248 // Do some other stuff
249 };
250
4aefaa9 @mde Load up models on app-startup.
mde authored
251 User = geddy.model.registerModel('User', User);
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
252
253 Creating an instance of one of these models is easy:
254
255 var params = {
256 login: 'alex',
257 password: 'lerxst',
258 lastName: 'Lifeson',
259 firstName: 'Alex'
260 };
261 var user = User.create(params);
262
263 Data-validation happens on the call to `create`, and any
264 validation errors show up inside an `errors` property on
265 the instance, keyed by field name. Instances have a `valid`
266 method that returns a Boolean indicating whether the instance
267 is valid.
268
269 // Leaving out the required password field
270 var params = {
271 login: 'alex',
272 };
273 var user = User.create(params);
274
275 // Prints 'false'
276 sys.puts(user.valid());
277 // Prints 'Field "password" is required'
278 sys.puts(user.errors.password);
279
3fd1410 @mde Update README with info on running tests.
mde authored
280 ## Running the tests
281
282 In the geddy project directory, run `jake test`. The tests simply
1c07cec @mde Restored model-tests.
mde authored
283 use NodeJS's `assert` library, which throws an error on failure.
3fd1410 @mde Update README with info on running tests.
mde authored
284 If there are no errors, the tests all ran successfully.
285
5e5438c @mde Added API docs link to README.
mde authored
286 ## API Docs
287
288 API docs [can be found here](http://mde.github.com/geddy/doc/).
289
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
290 - - -
291 Geddy Web-app development framework copyright 2112
292 mde@fleegix.org.
293
Something went wrong with that request. Please try again.