Skip to content

HTTPS clone URL

Subversion checkout URL

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