Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 364 lines (271 sloc) 10.085 kb
310fcb9 Matthew Eernisse 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 Matthew Eernisse 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
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
17 * App, resource and scaffold generators
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
18 * Content-negotiation
da8a19d Matthew Eernisse Update README.md
mde authored
19 * Session support (in-memory, cookie)
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
20 * Multiple template engine support(EJS, Jade, Mustache, Handlebars)
21 * View helpers([Docs](https://github.com/mde/geddy/wiki/View-Helpers))
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
22 * Fully non-blocking
23
24 ### License
25
26 Apache License, Version 2
27
e0dc47a Matthew Eernisse Updated README with 0.2 changes.
mde authored
28 ### Prerequisites
3b12a23 Matthew Eernisse Added mailing list info.
mde authored
29
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
30 Geddy requires version 0.6.x of Node.js or higher, and the
e0dc47a Matthew Eernisse Updated README with 0.2 changes.
mde authored
31 [Jake](https://github.com/mde/jake) JavaScript build-tool.
3b2b7c6 Matthew Eernisse Added mailing list and IRC info.
mde authored
32
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
33 ### Installing from Github
fa6a6ec Added note about prereqs and building.
mde authored
34
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
35 To get Geddy from Github and install it do:
fa6a6ec Added note about prereqs and building.
mde authored
36
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
37 ```
38 git clone git@github.com:mde/geddy.git
39 cd geddy
40 make && sudo make install
41 ```
fa6a6ec Added note about prereqs and building.
mde authored
42
ae163f3 Matthew Eernisse Updated README with custom-install-location info.
mde authored
43 By default Geddy is installed in "/usr/local." To install it into a
44 different directory (e.g., one that doesn't require super-user
45 privilege), pass the PREFIX variable to the `make install` command.
46 For example, to install it into a "geddy" directory in your home
47 directory, you could use this:
48
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
49 ```
50 make && make install PREFIX=~/geddy
51 ```
ae163f3 Matthew Eernisse Updated README with custom-install-location info.
mde authored
52
53 If you do install Geddy somewhere special, you'll need to add the
54 "bin" directory in the install target to your PATH to get access
55 to the `geddy` executable.
56
4b71fb1 Matthew Eernisse Added NPM install instructions.
mde authored
57 ### Installing with [NPM](http://npmjs.org/)
58
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
59 ```
60 [sudo] npm -g install geddy
61 ```
4b71fb1 Matthew Eernisse Added NPM install instructions.
mde authored
62
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
63 Note: Geddy (specifically, the generators) is a system-level
4b71fb1 Matthew Eernisse Added NPM install instructions.
mde authored
64 tool, and wants to be installed globally.
65
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
66 ### Creating a Geddy application
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
67
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
68 To create Geddy applications simply run `geddy app <name>`.
69 Then you can run `geddy` inside the application to start the server.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
70
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
71 ```
72 mde@localhost:~/work$ geddy app bytor
73 Created app bytor.
74 mde@localhost:~/work$ cd bytor
75 mde@localhost:~/work/bytor$ geddy
76 Server running at http://127.0.0.1:4000/
77 ```
4df79a5 Matthew Eernisse Fixed overzealous search-and-replace.
mde authored
78
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
79 Go to http://localhost:4000/, and you should see the introduction page.
f00e1d5 Proofreading.
mde authored
80
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
81 ### Generating resources
f00e1d5 Proofreading.
mde authored
82
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
83 Use `geddy resource <name> [model properties]` to generate a resource in your application.
84 Resources do not generate views, but creates a view directory. A resource route will be
85 created for you.
86
87 ````
88 mde@localhost:~/work$ geddy resource snow_dog breed:string name:string color:string
89 [Added] app/models/snow_dog.js
90 [Added] app/controllers/snow_dogs.js
91 [Added] Resource snow_dogs route added to config/router.js
92 [Added] snow_dogs view directory
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
93 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
94
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
95 Now start your Geddy server and your new route will work. Trying this for example
96 will return the params for the index action in JSON:
4df79a5 Matthew Eernisse Fixed overzealous search-and-replace.
mde authored
97
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
98 ```
99 $ curl localhost:4000/snow_dogs.json
100 {"params":{"method":"GET","controller":"SnowDogs","action":"index","format":"json"}}
101 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
102
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
103 Geddy generators handle plural inflections for model and controller names. ex: 'person' to 'people'
104 To read about the model properties argument jump to [Model properties](#model-properties)
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
105
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
106 ### Generating scaffolding
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
107
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
108 Use `geddy scaffold <name> [model properties]` to generate scaffoling in your application.
109 Scaffolding creates full CRUD actions includes views, and will default your configuration to use
110 [Mongodb](http://www.mongodb.org/) Resource routes will be created for you.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
111
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
112 ````
113 mde@localhost:~/work$ geddy resource snow_dog breed:string name:string color:string
114 [Added] app/models/snow_dog.js
115 [Added] app/controllers/snow_dogs.js
116 [Added] Resource snow_dogs route added to config/router.js
117 [Added] View templates
118 [Added] Database configuration to config/environment.js
119 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
120
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
121 Now start your Geddy server and you'll have new views created from scaffolding. Trying this for example
122 will return the content for the index action in HTML:
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
123
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
124 ```
125 $ curl localhost:4000/snow_dogs
126 <!DOCTYPE html>
127 <html lang="en">
128 <head>
129 <meta charset="utf-8">
130 <title>Geddy App | This app uses Geddy.js</title>
131 <meta name="description" content="">
132 <meta name="author" content="">
133
134 <meta name="viewport" content="width=device-width" />
135
136 <!-- The HTML5 shim, for IE6-8 support of HTML elements -->
137 <!--[if lt IE 9]>
138 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
139 <![endif]-->
140
141 .....
142 ```
143
144 Geddy generators handle plural inflections for model and controller names. ex: 'person' to 'people'
145 To read about the model properties argument jump to [Model properties](#model-properties)
146
147 ### Model properties
148
149 Some Geddy generators (resource, scaffold and model) have a argument that takes a list of model
150 properties. Here's an example of a resource with some properties:
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
151
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
152 ```
153 geddy resource user name admin:boolean lastLogin:datetime
154 ```
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
155
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
156 Each of these items include a name and an optional type, if there's no type given it'll default
157 to string. The list of supported types are listed in the [model](https://github.com/mde/geddy/wiki/Models) documentation.
158 If no id property is given then a default id property will be created with the type of string.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
159
ea91d7d Larz Conwell Added new default argument to model property section
larzconwell authored
160 You can also use custom default properties:
161 ```
162 geddy resource user name:default admin:boolean
163 ```
164 The above example will use the property `name`(string) to display the items in the views instead of the default ID property, this way when generating scaffolds, it will look better out of the box.
165
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
166 ### Routes
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
167
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
168 Routes are created in a similar fashion to Merb or Rails.
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
169
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
170 ***Basic routes***
171 ```
172 router.match('/moving/pictures/:id').to(
173 {controller: 'Moving', action: 'pictures'});
487669e Matthew Eernisse Updated README to describe model stubs and pluralization with geddy-gen ...
mde authored
174
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
175 router.match('/farewells/:farewelltype/kings/:kingid').to(
176 {controller: 'Farewells', action: 'kings'});
4e85834 More info about resource routes, content-negotiation.
mde authored
177
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
178 //Can also match specific HTTP methods only
179 router.match('/xandadu', 'get').to(
180 {controller: 'Xandadu', action: 'specialHandler'});
181 ```
4e85834 More info about resource routes, content-negotiation.
mde authored
182
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
183 ***Resource routes***
184 ```
185 router.resource('hemispheres');
186 ```
4e85834 More info about resource routes, content-negotiation.
mde authored
187
188 ### Resources and controllers
189
190 Geddy's resource-based routes create url/request-method mappings
191 for easy CRUD operations like this:
192
f918541 Matthew Eernisse No really, update the README with the extension stuff.
mde authored
193 GET */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
194 (SnowDogs controller, index action)
195
f918541 Matthew Eernisse No really, update the README with the extension stuff.
mde authored
196 GET */snow_dogs/add[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
197 (SnowDogs controller, add action, for any new-resource template
198 -- "new" is not usable as a JavaScript action name)
199
b563a1c Matthew Eernisse Make the doc regarding RESTful routes clearly include the file extension...
mde authored
200 POST */snow_dogs[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
201 (SnowDogs controller, create action)
202
b563a1c Matthew Eernisse Make the doc regarding RESTful routes clearly include the file extension...
mde authored
203 GET */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
204 (SnowDogs controller, show action)
205
b5d810c Matthew Eernisse Bumped Node version number, removed semicolon hack for edit path in rout...
mde authored
206 GET */snow_dogs/:id/edit[.extension]<br/>
2b96485 Matthew Eernisse Added support for create/update routing, for _method param override.
mde authored
207 (SnowDogs controller, edit action)
208
b563a1c Matthew Eernisse Make the doc regarding RESTful routes clearly include the file extension...
mde authored
209 PUT */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
210 (SnowDogs controller, update action)
211
b563a1c Matthew Eernisse Make the doc regarding RESTful routes clearly include the file extension...
mde authored
212 DELETE */snow_dogs/:id[.extension]<br/>
4e85834 More info about resource routes, content-negotiation.
mde authored
213 (SnowDogs controller, remove action)
214
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
215 A simple controller that just responds with any
216 form-post/query-string params looks like this:
217
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
218 ```javascript
219 var SnowDogs = function () {
220 this.respondsWith = ['text', 'json', 'html'];
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
221
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
222 this.index = function (params) {
223 this.respond({params: params});
224 };
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
225
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
226 this.add = function (params) {
227 this.respond({params: params});
228 };
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
229
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
230 this.create = function (params) {
231 this.respond({params: params});
232 };
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
233
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
234 this.show = function (params) {
235 this.respond({params: params});
236 };
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
237
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
238 this.update = function (params) {
239 this.respond({params: params});
240 };
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
241
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
242 this.remove = function (params) {
243 this.respond({params: params});
244 };
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
245
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
246 };
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
247
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
248 exports.SnowDogs = SnowDogs;
249 ```
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
250
4e85834 More info about resource routes, content-negotiation.
mde authored
251 ## Content-negotiation
252
a0f33a2 Matthew Eernisse README updates.
mde authored
253 Geddy can perform content-negotiation, and respond with with the
254 correct format based on the requested filename-extension.
4e85834 More info about resource routes, content-negotiation.
mde authored
255
a0f33a2 Matthew Eernisse README updates.
mde authored
256 If you have a JSON-serializable JavaScript object you want to
257 return in JSON format, pass your JavaScript object to the
4e85834 More info about resource routes, content-negotiation.
mde authored
258 `respond` method in the action on that controller.
259
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
260 ```javascript
261 this.respondsWith = ['text', 'json'];
4e85834 More info about resource routes, content-negotiation.
mde authored
262
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
263 this.show = function (params) {
264 item = {foo: 'FOO', bar: 1, baz: false};
265 this.respond(item);
266 };
267 ```
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
268 ## Models and validations
269
a0f33a2 Matthew Eernisse README updates.
mde authored
270 Geddy has a simple way of defining models, with a full-featured
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
271 set of data validations. The syntax is similar to models in
a0f33a2 Matthew Eernisse README updates.
mde authored
272 Ruby's ActiveRecord or DataMapper.
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
273
274 Here is an example of a model with some validations:
275
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
276 ```javascript
277 var User = function () {
278 this.property('login', 'string', {required: true});
279 this.property('password', 'string', {required: true});
280 this.property('lastName', 'string');
281 this.property('firstName', 'string');
282
283 this.validatesPresent('login');
284 this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
285 this.validatesLength('login', {min: 3});
286 this.validatesConfirmed('password', 'confirmPassword');
287 this.validatesWithFunction('password', function (s) {
288 // Something that returns true or false
289 return s.length > 0;
290 });
291
292 // Can define methods for instances like this
293 this.someMethod = function () {
294 // Do some stuff
295 };
296 };
297
298 // Can also define them on the prototype
299 User.prototype.someOtherMethod = function () {
300 // Do some other stuff
301 };
302
303 User = geddy.model.registerModel('User', User);
304 ```
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
305
bec0a56 Daniel Erickson added docs for the new defineProperties method on models
Techwraith authored
306 Alternatively, you can use the `defineProperties` method to lay out your model:
307
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
308 ```javascript
309 var User = function () {
310 this.defineProperties({
311 login: {type: 'string', required: true}
312 , password: {type: 'string', required: true}
313 , lastName: {type: 'string'}
314 , firstName: {type: 'string'}
315 });
316 }
317 ```
bec0a56 Daniel Erickson added docs for the new defineProperties method on models
Techwraith authored
318
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
319 Creating an instance of one of these models is easy:
320
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
321 ```javascript
322 var params = {
323 login: 'alex'
324 , password: 'lerxst'
325 , lastName: 'Lifeson'
326 , firstName: 'Alex'
327 };
328 var user = User.create(params);
329 ```
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
330
331 Data-validation happens on the call to `create`, and any
332 validation errors show up inside an `errors` property on
333 the instance, keyed by field name. Instances have a `valid`
334 method that returns a Boolean indicating whether the instance
335 is valid.
336
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
337 ```javascript
338 // Leaving out the required password field
339 var params = {
340 login: 'alex'
341 };
342 var user = User.create(params);
343
344 // Prints 'false'
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
345 util.puts(user.valid());
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
346 // Prints 'Field "password" is required'
a082031 Larz Conwell Updated readme to reflect new generators
larzconwell authored
347 util.puts(user.errors.password);
b6173ba Oscar Godson Updated README.md with fenced code samples for easier reading of code
OscarGodson authored
348 ```
2c7a18d Matthew Eernisse Updated with info about controllers and models/validations.
mde authored
349
3fd1410 Matthew Eernisse Update README with info on running tests.
mde authored
350 ## Running the tests
351
352 In the geddy project directory, run `jake test`. The tests simply
1c07cec Matthew Eernisse Restored model-tests.
mde authored
353 use NodeJS's `assert` library, which throws an error on failure.
3fd1410 Matthew Eernisse Update README with info on running tests.
mde authored
354 If there are no errors, the tests all ran successfully.
355
5e5438c Matthew Eernisse Added API docs link to README.
mde authored
356 ## API Docs
357
358 API docs [can be found here](http://mde.github.com/geddy/doc/).
359
88b6bb0 Updated README with overview info and markdown formatting.
mde authored
360 - - -
361 Geddy Web-app development framework copyright 2112
362 mde@fleegix.org.
363
Something went wrong with that request. Please try again.