= 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:

  class Posts < ApplicationController
    include BTech::Rest 
  end

Which would automatically yield the following REST actions:

* index
* show
* new
* edit
* create
* update
* destroy

How is that for being {DRY}[http://en.wikipedia.org/wiki/DRY]? Read on to learn more.

= License

Copyright (c) 2008-2009 Brooke Kuhlmann of {Berserk Technologies}[http://www.berserktech.com].
See the included LICENSE for more info.

= History

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.

= Installation

Type the following from the command line to install:

* *UNIX*: sudo gem install aeonscope-btech_rest
* *Windows*: gem install aeonscope-btech_rest

Update your environment.rb file to include the new gem:

* config.gem "btech_rest"

To apply unobtrusive jQuery support, run the following generator (TIP: suffix the command line with -h option for usage):

* script/generate ujs_setup

= Usage

As mentioned in the overview, simply add the following line of code to your controller(s) to make them RESTful:

  include BTech::Rest
	
Example:

  class Posts < ApplicationController
    include BTech::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:

<b>index.html.erb</b>

  <h2>Posts</h2>
  <div>
    <table>
	  <thead>
		  <tr>
		    <th>Label</th>
		    <th>Created At</th>
		    <th>Updated At</th>
		    <th>Actions</th>
		  </tr>
	  </thead>
	  <tbody>
		  <%= render @posts %>
	  </tbody>
    </table>
  </div>

<b>show.html.erb</b>

  <h2>Label</h2>
  <p><%= @post.label %></p>

  <h2>Content</h2>
  <p><%= @post.content %></p>

  <p><%= link_to "Back", :back %></p>

<b>new.html.erb</b>

  <% form_for @post do |form| %>
    <%= form.error_messages :header_data => :strong, :header_message => "Error" %>

    <div>
      <%= form.label :label %><br/>
      <%= form.text_field :label %>
    </div>

    <div>
      <%= form.label :content %><br/>
      <%= form.text_area :content %>
    </div>

    <div><%= show_submit_and_cancel :cancel_options => posts_path %></div>
 <% end %>

<b>edit.html.erb</b>

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.

Example:

  class Comments < ApplicationController
    include BTech::Rest
    belongs_to :posts
    resource_options :label => "My Wicked Comments"
    disabled_actions :show, :destroy
  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.
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"
* *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">
* *namespaces* = []
* *show_partial* = "/posts/show"
* *new_or_edit_partial* = "/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"
* *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">
* *namespaces* = []
* *show_partial* = "/comments/show"
* *new_or_edit_partial* = "/comments/new_or_edit"
		
= Contact/Feedback/Issues

* {Berserk Technologies}[http://www.berserktech.com] - Company web site.
* Aeonscope[http://www.aeonscope.net] - Personal web site.
* Twitter[http://www.twitter.com/Aeonscope] - Short bursts of insight and/or noise.