Skip to content

HTTPS clone URL

Subversion checkout URL

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