README.rdoc in aeonscope-rest-1.0.0 vs README.rdoc in aeonscope-rest-1.1.0
- old
+ new
@@ -1,14 +1,14 @@
= Overview
-Enables default REST functionality, more than what you get with Rails out-of-the-box, and keeps your code DRY. This means you can write code like this:
+Enables default REST functionality, more than what you get with Rails out-of-the-box, to keep your code DRY. This means you can write code like this:
class Posts < ApplicationController
include Rest
end
-Which would automatically yield the following REST actions:
+Which would automatically add the following REST actions to your controller:
* index
* show
* new
* edit
@@ -27,28 +27,28 @@
See the CHANGELOG file for more info.
= Requirements
-1. {Ruby on Rails}[http://rubyonrails.org] (automatically installed for you if you don't have 2.3.x or higher).
-2. mislav-will_paginate[http://github.com/mislav/will_paginate/tree/master] gem (automatically installed for you).
-3. Knowledge of the {Representational State Transfer (REST)}[http://en.wikipedia.com/wiki/REST]. Download and read {RESTful Rails}[http://www.b-simple.de/documents] if you need further info.
+1. Knowledge of {Representational State Transfer (REST)}[http://en.wikipedia.com/wiki/REST].
+2. {Ruby on Rails}[http://rubyonrails.org] (automatically installed for you if you don't have 2.3.x or higher).
+3. mislav-will_paginate[http://github.com/mislav/will_paginate/tree/master] gem (automatically installed for you).
= Installation
Type the following from the command line to install:
* *UNIX*: sudo gem install aeonscope-rest
* *Windows*: gem install aeonscope-rest
Update your environment.rb file to include the new gem:
-* config.gem "rest"
+* config.gem "aeonscope-rest", :lib => "rest", :source => "http://gems.github.com"
-To apply unobtrusive jQuery support, run the following generator (TIP: suffix the command line with -h option for usage):
+Then run the following generator to complete setup (TIP: suffix the command line with -h option for usage):
-* script/generate ujs_setup
+* script/generate rest_setup
= Usage
As mentioned in the overview, simply add the following line of code to your controller(s) to make them RESTful:
@@ -58,12 +58,16 @@
class Posts < ApplicationController
include Rest
end
-This will automatically create the seven REST actions (index, show, new, create, edit, update, and destroy) for your controller. The model (i.e. Post) and model instance (i.e. @posts or @post depending on the action) are automatically determined from the controller name and created for you as well which means you can immediately write the following code in your views:
+This will automatically create the seven REST actions (index, show, new, create, edit, update, and destroy) for your controller. The model (i.e. Post) and model instance (i.e. @posts or @post depending on the action) are automatically determined from the controller name. Just make sure your routes are updated to reflect the new resource. For example:
+ map.resources :posts
+
+This means you can immediately write the following code in your views:
+
<b>index.html.erb</b>
<h2>Posts</h2>
<div>
<table>
@@ -89,11 +93,11 @@
<h2>Content</h2>
<p><%= @post.content %></p>
<p><%= link_to "Back", :back %></p>
-<b>new.html.erb</b>
+<b>new_or_edit.html.erb</b>
<% form_for @post do |form| %>
<%= form.error_messages :header_data => :strong, :header_message => "Error" %>
<div>
@@ -104,19 +108,15 @@
<div>
<%= form.label :content %><br/>
<%= form.text_area :content %>
</div>
- <div><%= show_submit_and_cancel :cancel_options => posts_path %></div>
+ <div><%= submit_tag "Save", :class => "form-button" %> or <%= link_to "Cancel", posts_path %></div>
<% end %>
-<b>edit.html.erb</b>
+Notice how the form_for[http://apidock.com/rails/ActionView/Helpers/FormHelper/form_for] helper method automatically determines what controller action to use based off the model object (i.e. @post). This allows you to use the same form for new and edit actions by creating one template called: new_or_edit.html.erb. Nice, eh?
-Use the same code as shown in the new.html.erb view above. ;-) The Rails form_for helper will automatically determine what action to take as shown in the following code:
-
- <% form_for @post do |form| %>
-
To customize the RESTful behavior of your controller, use any combination of these three macros:
* *belongs_to* - Enables resource nesting where a controller can belong to a parent controller. This behavior is similar to the ActiveRecord {belongs_to}[http://apidock.com/rails/ActiveRecord/Associations/ClassMethods/belongs_to] macro.
* *resource_options* - Allows you to customize the default behavior of your controller(s). There is a lot you can do with this, read the code documentation for more info.
* *disabled_actions* - Allows you to disable any of the default REST actions. Follow the link to learn more.
@@ -131,40 +131,52 @@
end
Here is the breakdown, line-by-line, of the example shown above:
1. Enables restful behavior.
-2. Identifies the controller as a nested resource of posts.
+2. Identifies the comments controller as a child of the posts controller (i.e. nested resource).
3. Instead of using the default label "Comments", a customized label of "My Wicked Comments" is used instead.
4. The "show" and "destroy" actions are disabled which means only the following actions will work: index, new, edit, create, and update.
Using the post and comment controller relationship as defined above, we can break this relationship down even further. The post (parent) resource would have the following values (in this case, all default values):
* *parent_key* = N/A
* *parent_value* = N/A
* *parent_resource_method* = N/A
-* *name* = "posts"
+* *controller_class* = PostsController
+* *controller_name* = "posts"
* *label* = "Posts"
-* *controller* = PostsController
-* *model* = Post
-* *record* = #<Post id: 1, label: "Test", content: "Test", created_at: "2008-10-31 23:59:28", updated_at: "2008-10-31 23:59:28">
+* *model_class* = Post
+* *model_name* = post
+* *model_object* = @post #<Post id: 1, label: "Test", content: "Test", created_at: "2008-10-31 23:59:28", updated_at: "2008-10-31 23:59:28">
* *namespaces* = []
-* *show_partial* = "/posts/show"
-* *new_or_edit_partial* = "/posts/new_or_edit"
+* *index_template* = "/posts/index"
+* *show_template* = "/posts/show"
+* *new_or_edit_template* = "/posts/new_or_edit"
The comment (child) resource would have the following values:
-
+
* *parent_key* = post_id
* *parent_value* = 1
* *parent_resource_method* = N/A
-* *name* = "comments"
+* *controller_class* = CommentsController
+* *controller_name* = "comments"
* *label* = "My Wicked Comments"
-* *controller* = CommentsController
-* *model* = Comment
-* *record* = #<Post id: 1, post_id: nil, label: "Test", content: "Test", created_at: "2008-10-31 23:59:28", updated_at: "2008-10-31 23:59:28">
+* *model_class* = Comment
+* *model_name* = comment
+* *model_object* = @comment #<Comment id: 1, post_id: 1, label: "Test", content: "Test", created_at: "2008-10-31 23:59:28", updated_at: "2008-10-31 23:59:28">
* *namespaces* = []
-* *show_partial* = "/comments/show"
-* *new_or_edit_partial* = "/comments/new_or_edit"
+* *index_template* = "/comments/index"
+* *show_template* = "/comments/show"
+* *new_or_edit_template* = "/comments/new_or_edit"
+
+Resources
+
+To learn more about REST in Rails, check out the following:
+
+* {RESTful Rails}[http://www.b-simple.de/documents] - A PDF work downloading and reading that inspired me to write this gem.
+* {Rails Routing}[http://guides.rails.info/routing.html] - The definitive guide to RESTful routing in Rails.
+* {Taking Things Too Far}[http://www.therailsway.com/2009/6/22/taking-things-too-far-rest] - A good read on knowing when you have gone too far with REST API.
= Contact/Feedback/Issues
* {Berserk Technologies}[http://www.berserktech.com] - Company web site.
* Aeonscope[http://www.aeonscope.net] - Personal web site.