Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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