Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Enhances Rails with default REST functionality.

branch: master
README.md

Overview

Gem Version Code Climate GPA Gemnasium Status Travis CI Status Coverage Status

Enables default REST functionality, more than what you get with Rails out-of-the-box, which keeps your code DRY. This means you can write code like this:

class Posts < ApplicationController
  is_resourceful
end

Which would automatically add the following REST actions to your controller:

  • index
  • show
  • new
  • edit
  • create
  • update
  • destroy

Features

Supports the following gems (if detected):

Supports the following JavaScript libraries:

Requirements

  1. Any of the following Ruby VMs:
  2. Ruby on Rails 4.x.x.
  3. Knowledge of Representational State Transfer (REST).

Setup

For a secure install, type the following from the command line (recommended):

gem cert --add <(curl -Ls http://www.redalchemist.com/gem-public.pem)
gem install resourcer --trust-policy MediumSecurity

NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while allowing the installation of unsigned dependencies since they are beyond the scope of this gem.

For an insecure install, type the following (not recommended):

gem install resourcer

Add the following to your Gemfile file:

gem "resourcer"

Add the following to your application.js file:

//= require jquery.rest

For first time installers, run the install generator:

rails generate resourcer:install

For upgrades to previous releases, run the upgrade generator:

rails generate resourcer:upgrade

Usage

Add the is_resourceful macro to your controllers to make them RESTful. For example:

class Posts < ApplicationController
  is_resourceful
end

This will automatically add the seven REST actions (index, show, new, create, edit, update, and destroy) to your controller. The model class and instance names are automatically determined from the controller name. To further customize the behavior of the is_resourceful macro, the following options are available:

  • label - Optional. The resource label. Defaults to the controller name with capitalization. Example: posts => Posts.
  • belongs_to - Optional. The parent symbol (including namespaces delimited by underscores). Example: Public::PostsController, Result: :public_posts. Defaults to nil.
  • parent_key - Optional. The ID key of the parent resource (for nested resources only). Defaults to _id
  • parent_value - Optional. The ID value of the parent resource (for nested resources only). Defaults to the record id.
  • parent_resource_method - Optional. The instance method to call for acquiring child resource(s) of the parent (for nested resources only). Example: A post with many comments would be post.comments. Defaults to child resource name.
  • controller_class - Optional. The controller class (for nested resources only). Defaults to the current class. You should never need to use this.
  • controller_name - Optional. The controller name. Defaults to the controller class name minus the "Controller" suffix (same behavior as used in routing). Example: PostsController => posts
  • model_class - Optional. The model class. Defaults to the same name as the controller (minus namespace, suffix, and pluralization of course). Example: PostsController => Post
  • model_name - Optional. The model name. Defaults to the singularized version of the :controller_name. Example: posts (controller_name) => post (model_name).
  • model_object - Optional. The model object. The name defaults to the model_name. Example: post (model_name) => @post (model object). You should never need to use this but, hey, better safe than sorry.
  • model_find_method - Optional. The method used to find a model object. Defaults to :find.
  • namespaces - Optional. The namespaces (if any) for routing. Defaults to the controller namespace.
  • index_template - Optional. The index template. Defaults to "///index".
  • show_template - Optional. The show template. Defaults to "///show".
  • new_or_edit_template - Optional. The new or edit template. Defaults to "///new_or_edit".
  • authorize - Optional. Boolean. Authorizes the resource via the CanCan gem. Defaults to true.
  • disabled_actions - Optional. An array of REST actions to disable. Defaults to [].

Your view templates can be written as follows (Note: the new and edit actions share the same view):

index.html.erb

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

show.html.erb

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

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

new_or_edit.html.erb

<% form_for @post do |form| %>
  <%= render "shared/error_messages", target: @post %>

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

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

  <div><%= submit_tag "Save", class: "form-button" %></div>
<% end %>

Finally, don't forget to update your routes when making your controllers resourceful. When using the example above, the following would be added to your routes file:

map.resources :posts

Resources

To learn more about REST in Rails, check out the following:

  • RESTful Rails - A PDF work downloading and reading that inspired me to write this gem.
  • Rails Routing - The definitive guide to RESTful routing in Rails.
  • Taking Things Too Far - A good read on knowing when you have gone too far with the REST API.

Testing

To test, do the following:

  1. cd to the gem root.
  2. bundle install
  3. bundle exec rspec spec

Versioning

Read Semantic Versioning for details. Briefly, it means:

  • Patch (x.y.Z) - Incremented for small, backwards compatible bug fixes.
  • Minor (x.Y.z) - Incremented for new, backwards compatible public API enhancements and/or bug fixes.
  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.

Contributions

Read CONTRIBUTING for details.

Credits

Developed by Brooke Kuhlmann at Red Alchemist

License

Copyright (c) 2010 Red Alchemist. Read the LICENSE for details.

History

Read the CHANGELOG for details. Built with Gemsmith.

Something went wrong with that request. Please try again.