Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 280 lines (199 sloc) 7.403 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
e0dc47a @mde Updated README with 0.2 changes.
mde authored
40 ### Installing with [NPM](http://npmjs.org/)
41
42 npm install -g geddy
43
44 Geddy includes app- and resource-generation scripts that are
45 easiest to use in a global install.
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
190 Geddy has built-in ability to perform content-negotiation
191 based on the requested filename-extension.
192
193 If you have a JSON-serializable JavaScript object you want
194 to return in JSON format, pass your JavaScript object to the
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
207 Geddy has an easy, intuitive way of defining models, with
208 a full-featured set of data validations. The syntax is very
209 similar to models in Ruby's ActiveRecord or DataMapper.
210
211 The model module is coded with browser-based use in mind,
212 so it's very easy to share model and input validation code in
213 your app between client and server.
214
215 Here is an example of a model with some validations:
216
217 var User = function () {
7f15377 @mde Updated docs, tests, template to use new lowercase names for datatypes.
mde authored
218 this.property('login', 'string', {required: true});
219 this.property('password', 'string', {required: true});
220 this.property('lastName', 'string');
221 this.property('firstName', 'string');
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
222
223 this.validatesPresent('login');
224 this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
225 this.validatesLength('login', {min: 3});
226 this.validatesConfirmed('password', 'confirmPassword');
4df79a5 @mde Fixed overzealous search-and-replace.
mde authored
227 this.validatesWithFunction('password', function (s) {
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
228 // Something that returns true or false
229 return s.length > 0;
230 });
231
232 // Can define methods for instances like this
233 this.someMethod = function () {
234 // Do some stuff
235 };
236 };
237
238 // Can also define them on the prototype
239 User.prototype.someOtherMethod = function () {
240 // Do some other stuff
241 };
242
e0dc47a @mde Updated README with 0.2 changes.
mde authored
243 geddy.model.registerModel('User', User);
2c7a18d @mde Updated with info about controllers and models/validations.
mde authored
244
245 Creating an instance of one of these models is easy:
246
247 var params = {
248 login: 'alex',
249 password: 'lerxst',
250 lastName: 'Lifeson',
251 firstName: 'Alex'
252 };
253 var user = User.create(params);
254
255 Data-validation happens on the call to `create`, and any
256 validation errors show up inside an `errors` property on
257 the instance, keyed by field name. Instances have a `valid`
258 method that returns a Boolean indicating whether the instance
259 is valid.
260
261 // Leaving out the required password field
262 var params = {
263 login: 'alex',
264 };
265 var user = User.create(params);
266
267 // Prints 'false'
268 sys.puts(user.valid());
269 // Prints 'Field "password" is required'
270 sys.puts(user.errors.password);
271
5e5438c @mde Added API docs link to README.
mde authored
272 ## API Docs
273
274 API docs [can be found here](http://mde.github.com/geddy/doc/).
275
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
276 - - -
277 Geddy Web-app development framework copyright 2112
278 mde@fleegix.org.
279
Something went wrong with that request. Please try again.