From 987140e446822c98ace8df8a72d05af39d9d5529 Mon Sep 17 00:00:00 2001 From: Miguel Madero Date: Mon, 1 Oct 2012 19:26:18 -0300 Subject: [PATCH] Did another pass and fixed some typos --- site/tutorial.html | 187 +++++++++++++++++++++++---------------------- 1 file changed, 94 insertions(+), 93 deletions(-) diff --git a/site/tutorial.html b/site/tutorial.html index acb8e9c0..c04c4270 100644 --- a/site/tutorial.html +++ b/site/tutorial.html @@ -151,13 +151,13 @@
App tutorials

Welcome to the Geddy Tutorial

-

In this tutorial we'll learn how to use Geddy by creating a simple todo manager applciation. There will be two created applications one created from scaffolding and one created from using resources. See the finished version.

+ +

In this tutorial we'll learn how to use Geddy by creating a simple todo manager applciation. We will create two applications one using scaffolding and one using resources. See the finished version.

In this tutorial we'll cover:

How to use Geddy commands

-

Each of Geddy's commands(app, resource, controller, etc.) take a command or set of commands(excluding secret). Here we'll learn how to use those commands.

+

Each of Geddy's commands(app, resource, controller, etc.) take a command or set of commands(excluding secret and console). Here we'll learn how to use those commands.

Model properties

-

There are a three commands(resource, model and scaffold) that also include model property arguments. This is a list seperated by spaces that include the property, it's type and an optional default setting. Below are some examples of how they are used in the commands.

+

There are a three commands(resource, model and scaffold) that also include model property arguments. This is a list seperated by spaces that include the property, its type and an optional default setting. Below are some examples of how they are used in the commands.

$ geddy scaffold user name:string
-

The example above example will create our normal scaffolding and include a name property of type string. If no type is given it will default to string.

+

The example above will create our normal scaffolding and include a name property of type string. If no type is given it will default to string.

$ geddy scaffold user name:default
-

This example creates scaffolding but includes name as the default property that will be used when displaying the content in the views. In this example the property name is given the type string because no type was given, you could of also writte name:string:default, or you could've used a different type of course. the default setting also includes an alias called def. If no default property is given Geddy will use id as the display property. +

This example creates scaffolding but includes name as the default property that will be used when displaying the content in the views. In this example the property name is given the type string because no type was given, you could of also writte name:string:default, or you could've used a different type of course. The default setting also includes an alias called def. If no default property is given Geddy will use id as the display property. - 

$ geddy scaffold user name:default id:number
-

As the above examples this creates are scaffold, and this time we use name type string as the default property we also overwrite the included id property. If no id property is given Geddy will use include id type int

+ 
$ geddy scaffold user name:default id:int
+

This time we used name type string as the default property. We also overwrote the included id property with a different type (by default it's a string).

Note: an ID property will always be created.

Scaffolding application tutorial

-

This will be a short tutorial as scaffolding will do almost everything for us, I won't go into detail on what it does as it will be covered in exstensive detail in the resources tutorial. The source for this tutorial will be here

+

This will be a short tutorial as scaffolding will do almost everything for us, I won't go into detail on what it does as it will be covered in exstensive detail in the resources tutorial. The source for this tutorial will be here.

First we'll create our application, this will create a base so we can start on.

$ geddy app todo_app
-

Lets spend some time reviewing what geddy did. The previous command created a lot. During the tutorial we will edit and review some of this files, but we'll briefly explain what they are now so you get familiar with the base application.

+

Let's spend some time reviewing what geddy did. The previous command created a lot. During the tutorial we will edit and review some of this files, but we'll briefly explain what they are now so you get familiar with the base application.

-

Now you can start the application up by simply doing $ cd todo_app && geddy, Then open your browser to localhost:4000, and you'll find the hello world page.

+

Now from your app's root simply start geddy

-

So now we want to create a scaffold that will be used to create our todo items. We will create a title and status property so that we have some attributes to use.

+ 
+$ cd todo_app 
+$ geddy
+ +

Then open your browser to localhost:4000, and you'll find the hello world page.

+ +

So now we want to create a scaffold to manage our todo items. We will create a title and status property so that we have some attributes to use.

$ geddy scaffold todo title:default status
-

We are almost done. Now you have to start the geddy

+

We are almost done. Now you have to restart geddy

$ geddy

Open your browser to localhost:4000/todos and you'll get a list of the todos which should be empty. Go ahead and look around, you can create show edit and delete todo items. We're going to make a few changes though.

@@ -278,46 +285,40 @@

Scaffolding application tutorial

... }; Todo = geddy.model.register('Todo', Todo); -

Here we are making it so the title property is required and have a minumum of 5 characters. We also made it so the status acts like a boolean attribute but uses custom names instead of true/false. Now we'll need to edit the 'edit' and 'add' views to reflect the status changes.

- - 
-...
-<div class="control-group">
-  <label for="status" class="control-label">status</label>
-  <div class="controls">
-    <select name="status" class="span6">
-      <option>open</option>
-      <option>done</option>
-    </select>
-  </div>
-</div>
-...
-

Now that we've made the needed changes, restart Geddy to update our model changes, now we've got a good todo application running and didn't really have to do anything. Scaffolding is very good when you don't need to do much. To learn more about models and applications keep reading and follow the resource application tutorial to get a better understanding of views and controller which we didn't really cover in the Scaffold Tutorial.

+

Here we are making it so the title property is required and have a minumum of 5 characters. We also made it so the status acts like a boolean attribute but uses custom names instead of true/false. We should also change our edit and add views to limit the options, but we will do it as part of the resources tutorial, for now we will leave the views the way they are.

+ +

Now that we've made the needed changes, restart Geddy to update our model changes. Go and play with the app again, create a todo item, try to edit and test the validation rules. We've got a good todo application running and didn't really have to do much. Scaffolding is very good when you need something simple to get you started. To learn more about controllers and views keep reading and follow the resources tutorial.

Resource application tutorial

Let's start by using the geddy executable to generate a basic app-structure.

$ geddy app todo_app
-

Now let's try out our new application by doing $ cd todo_app && geddy command, your app should be running on port 4000. Visit http://localhost:4000 in your browser to see your app.

+

Now let's try out our new application by running geddy from your application's root

+ + 
+$ cd todo_app 
+$ geddy
+ +

Your app should be running on port 4000. Visit http://localhost:4000 in your browser to see your app.

Optional: check out your app on a mobile phone

Generate a resource

-

Now, lets actually get started building our To Do list manager. First, we'll need to generate the todo resource. We do this using the geddy executable as well:

+

Now, let's get started building our To Do list manager. First, we'll need to generate the todo resource. We do this using the geddy executable as well:

$ geddy resource todo title:string status

What did that do?

These tools should look somewhat familiar to anyone who's used an ORM-system like Ruby's ActiveRecord, or DataMapper.

-

Go ahead and open up app/models/todo.js. Read through the commented out code there for some ideas on what you can do with models. We'll be writing our model from scratch for this tutorial, so lets leave that commented out. (It's been deleted in the example app.)

+

Go ahead and open up app/models/todo.js. Read through the commented out code there for some ideas on what you can do with models. We'll be writing our model from scratch for this tutorial, so let's leave that commented out.

So, minus the commented out code, you should have a file that looks like this:

@@ -466,43 +466,51 @@ 
The Todo model

 
 Todo = geddy.model.register('Todo', Todo);
-

The `defineProperties` method takes any number of properties to be added to the model. The keys in the object will be added as properties on the model. The values are just objects that describe the properties. When we ran the scaffold command it created these for us. But we want to change it so they are all `required` so set `title` and `status` to match `id` now.

+

The defineProperties method takes any number of properties to be added to the model. The keys in the object will be added as properties on the model. The values are just objects that describe the properties. When we ran the scaffold command it created these for us. But we want to change it so they are all `required`. To learn more, check out the readme.

-

To learn more, check out the readme.

- -

There's also more detailed validation API. While we're here, lets use that API to set up some more validations:

+

There's also a more detailed validation API. While we're here, let's add some validation as well. The final code should look like this:

-this.validatesPresent('title');
-this.validatesLength('title', {min: 5});
+var Todo = function () {
 
-this.validatesWithFunction('status', function (status) {
-  return status == 'open' || status == 'done';
-});
+ this.defineProperties({ + title: {type: 'string'} + , status: {type: 'string'} + }); + + this.validatesPresent('title'); + this.validatesLength('title', {min: 5}); + + this.validatesWithFunction('status', function (status) { + return status == 'open' || status == 'done'; + }); +}; + +Todo = geddy.model.register('Todo', Todo);

For the title property, we made sure that the property is always present and we made sure that the title property is a minimum of 5 characters long.

-

For the 'status' property, we used a function to validate that the property is always set to either open or done.

+

For the status property, we used a function to validate that the property is always set to either open or done.

For more information about Geddy's Models, you can check out the Model wiki page.

The Todo model-adapter

-

Now that we've set up our todo model, we need to define a way to store it. To keep our models persistance agnostic, Geddy uses model-adapters. By default it will use mongo. For the purpose of this tutorial we will change the defaultAdapter to memory editing config/development.js. +

Now that we've set up our todo model, we need to define a way to store it. To keep our models persistance agnostic, Geddy uses model-adapters. By default it will store objects in memory using the memory model adapter. You can change the default memoryAdapter in config/development.js. 

defaultAdapter = 'memory'
-

There, now we've got a place to store our todo's. This is in your application-memory, so it will disappear when you restart the server.

+

Now we've got a place to store our todo's. This is in your application's memory, so it will disappear when you restart the server.

Optional: use mongo for persistence

-

Install a mongodb server if you haven't already and $ [sudo] npm install -g mongodb-wrapper to install the required mongodb-wrapper and leave the defaultAdapter = 'mongo' in config/development.js to use mongo instead of the memory adapter.

+

Install a mongodb server if you haven't already and $ [sudo] npm install -g mongodb-wrapper to install the required mongodb-wrapper and set defaultAdapter = 'mongo' in config/development.js instead of the memory adapter. You will also have to specify the db configuration db: { mongo: { dbname: 'model_test' }. For more information see the Model Adapter Wiki Page

The Todo Controller

-

TODO: add some intro about controllers. Explain what Geddy adds by default and what we're about to change

+

Controllers sit between the views and models. They are also the entry point of our code. When a user gets a page a function in a controller, also called a controller acton, will get invoked. The controller will usually interact with the model and pass it to the view. The pattern isn't as black and white, but for the purpose of the tutorial, let's move on to actually write some controller actions.

Saving todos

-

To save a todo we need edit the create action in app/controllers/todos.js. It's not doing much at the momment so lets modify it a little bit.

+

To save a todo we need to edit the create action in app/controllers/todos.js. It's not doing much at the momment so lets modify it a little bit.

 this.create = function (req, resp, params) {
@@ -521,14 +529,12 @@ 
Saving todos

 
             
First, we create a new instance of the Todo model with geddy.model.Todo.create, passing in the title that our form will post up to us, and setting up the default status.

 
-            
Then we call we call the save method and redirect the user back to the /todos route. Internally, save does two things. It validates the model based on the rules we defined earlier. This is similar to calling todo.isValid(). If the model was valid, it will delegate to the model adapter configured previously to actually persist the model. If either step fails, you will get an error collection as the first parameter of the function and we we redirect the user back to the /todos/add route. Otherwise we redirect to the controller default action self.redirect({controller: self.name});.

+            
Then we call we call the save method. Internally, save does two things. It validates the model based on the rules we defined earlier. This is similar to calling todo.isValid(). If the model was valid, it will delegate to the model adapter configured previously to actually persist the model. If either step fails, you will get an error collection as the first parameter of the function and we redirect the user back to the /todos/add route. Otherwise we redirect to the controller's default action self.redirect({controller: self.name});.

 
-            
Listing all todos

+            
Listing all todos

 
             
Now that we we can create To Do items, we should probably list them somewhere. Lets change the index action in the todos controller.

 
-            
Edit the index action to show all todos

-
             
Open up /app/controllers/todos.js again and replace the current implementaton with the following code.

 
             
@@ -542,31 +548,25 @@ 
Edit the index action to show all todos

 
             
This part is a bit simpler and it follows a similar pattern. Instead of calling create in geddy.model.Todo this time we simply call all and we pass the data back to the view for rendering

 
-            
Now that we can can load todo items you can test it by starting up Geddy and go to http://localhost:4000/todos and you can view the list of items.

+            
Now that we can can load todo items you can test it by starting up Geddy and going to localhost:4000/todos and you can view the list of items.

 
-            
Showing a todo

+            
Showing a todo

 
-            
Now that we have our index action working as expected, we should probably work on the show controller action to display todo details.

-
-            
Edit the show action to find a todo

-
-            
Open up your todos controller again. This time we need to edit the show action to make it look like the following code.

+            
Now that we have our index action working as expected, we should work on the show controller action to display todo details.

 
             
 this.show = function (req, resp, params) {
   var self = this;
 
   geddy.model.Todo.load(params.id, function(err, todo) {
-    self.respond({params: params, todo: todo.toObj()});
+    self.respond({params: params, todo: todo});
   });
 };

             
Now we have a working show action in the controller to load items.

 
-            
Updating a todo

-
-            
Edit the update action to find a todo, change the status, and save it

+            
Updating a todo

 
-            
Alright, now that we can view our todos lets edit the update action in the todos controller. It should look something like this.

+            
Alright, now that we can view our todos let's edit the update and edit actions in the todos controller. They should look something like this:

 
             
 this.edit = function (req, resp, params) {
@@ -614,10 +614,11 @@ 
Oh, did we mention that you have a JSON and JSONP api now too?

             
If you want to explore a little more, here are some other things you could do:

 
             
    
-            
  • Change the Main#index route to point to the Todos#index action (hint, check out config/router.js)
    • 
-            
  • Add some logging with geddy.log
    • 
-            
  • Set up metrics by running npm install metrics, and uncomment the metrics entry (metrics: { port: 4001 }) in your config/environment.js file
    • 
-            
  • Configure mongo, riak or postgress and use it instead of the memory modelAdapter. See how easy it's to switch
    • 
+              
  • Change the Main#index route to point to the Todos#index action (hint, check out config/router.js)
    • 
+              
  • Add some logging with geddy.log
    • 
+              
+              
+              
  • Configure mongo, riak or postgress and use it instead of the memory modelAdapter. See how easy it's to switch
    •