Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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