= Overview

Easily adhere to DRY principals and add default REST functionality to your controllers.  This means you can write code
like this:

	class Posts < ApplicationController
		include BTech::Rest 
	end

...and you will automatically have 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 {Berserk Technologies}[http://www.berserktech.com].
See the included LICENSE[link:files/LICENSE_rdoc.html] file for more info.

= History

See the CHANGELOG[link:files/CHANGELOG_rdoc.html] file for more info.

= Requirements

1. 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.
2. mislav-will_paginate[http://github.com/mislav/will_paginate/tree/master] gem. This is automatically installed/updated for you unless the correct version is detected.

= Installation

Type the following from the command line to install:

* <b>MacOS/Linux</b>: sudo gem install btech_rest
* *Windows*: gem install btech_rest

Type the following from the command line to 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:

	include BTech::Rest
	
Example:

	class Posts < ApplicationController
		include BTech::Rest 
	end

To customize the RESTful behavior of your controller, use any combination of these three macros:

* belongs_to[link:classes/BTech/Rest/ClassMethods.html] - Enables resource nesting where a controller can belong to a parent controller (i.e. http://www.example.com/posts/1/comments/2). This behavior is similar to the ActiveRecord belongs_to[http://apidock.com/rails/ActiveRecord/Associations/ClassMethods/belongs_to/] macro.
* resource_options[link:classes/BTech/Rest/ClassMethods.html] - Allows you to customize the default behavior of your controller(s). There is a lot you can do with this, so follow the link and read the method comments to learn more.
* disabled_actions[link:classes/BTech/Rest/ClassMethods.html] - 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.