Project

resources

0.0
No commit activity in last 3 years
No release in over 3 years
It's a gem that help's you to create CRUD controllers for your models in a very fast and flexible way.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 1.4.1, ~> 1.4
>= 1.4.3, ~> 1.4
>= 3.2.0, ~> 3.2

Runtime

>= 3, >= 3.2
 Project Readme

Resources

It's a gem that help's you to create CRUD controllers for your models in a very fast and flexible way.

Note: Version 1.0.0+ introduces some breaking changes, to see the list of this change please check CHANGE_LOG.md


Installation

Add this line to your application's Gemfile:

gem 'resources'

Note: if you use rails 4 you need to add gem 'responders' before resources

And then execute:

bundle install

Or install it yourself as:

$ gem install resources

Run the configuration generator, this will create the resources initializer

rails g resources:install

USAGE

Just add resource_for to your controller and give the model's name

class Admin::CountriesController < ApplicationController
  resource_for "Country"
end

or use the controller generator

rails g resource_controller admin/country

And that's it, you have to do anything else on the controller to create a CRUD maintenance for the country model.

resource_for will handle all the restful actions for you and it will give you the next's helper_methods for your convenience:

resources: this will have a collection of Country, objects so you can use on the index actions or any other collection route actions of your controller

resource: this will have a Country, object so you can use on the member route actions like new, create, edit, update, show, destroy

resources_search: this is a ransack object to you in the search_form_for helper

resource_saved?: this is a helper to user after create or update a record to know if it was saved.

OPTIONS AND FLEXIBILITY

resource_for by default expects the params key for update or create the object to be resource if you use form_for or simple_form you need to add the as: :resource option

= simple_form_for [:admin, resource], as: :resource do |f|
  = f.input :code
  = f.input :name
  = f.input :active
  = f.submit "SAVE"

FLASH - flash

This options allows you to add a flash notice after saving or destroying a record.

class Admin::CountriesController < ApplicationController
  resource_for :"Country", flash: true
end

By default expects this locale: "resources.#{controller_path}.#{action_name}".

You can also pass a lambda to define a custom flash

class Admin::CountriesController < ApplicationController
  resource_for :"Country", flash: -> (resource, params, controller) do
    if  controller.action_name == "create"
      I18n.t("flash.record_successfully_created")
    else
      I18n.t("flash.record_successfully_updated")
    end  
  end
end

RESOURCE PARAMS - params_resource

This options allows you to change the default params key used for create or update the record. So you don't have to add the as: :resource to the simple_form_for.

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    params_resource: :country
end

Note: For Rails 4 you may encounter with this error (ActiveModel::ForbiddenAttributesError) when you try to update a record due to strong_parameters protection. To avoid this just add to your model a method named permited_attributes that return an array of allowed attributes. Example

class Country < ActiveRecord::Base

  def permited_attributes
    [:name, :code, :active]
  end

end

Or you can use the lambda syntax.

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    params_resource: lambda{ |params|   params[:country] }
end

# For rails 4

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    params_resource: lambda{ |params|
      params.require(:country).permit(:name)
    }
end

RESOURCE ALIAS - resource_method_name - resources_method_name

This options allows you to alias the resource method in case you don't like the name. if you don't specify a resources_method_name it will name the alias to resource_method_name pluralized.

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    params_resource: :country,
    resource_method_name: :country
end

NOTE: making a change in resource_method_name and resources_method_name options requires a server restart.

Now in your view you can use country instead of resource

= simple_form_for [:admin, country] do |f|
  = f.input :code
  = f.input :name
  = f.input :active
  = f.submit "SAVE"

PAGINATION - pagination

This option enable pagination in case that you use any of the most popular pagination gems (kaminari or will_paginate).

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    pagination: true,
    params_resource: :country,
    resource_method_name: :country
end

Or you can use the lambda syntax.

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    pagination: lambda{ |params, controller| params[:disable_pagination].blank? },
    params_resource: :country,
    resource_method_name: :country
end

DEFAULT SCOPES - resource_scope- resources_scope

This options are to set a default scope for the resources, and resource objects.

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    resources_scope: :active,
    pagination: true,
    params_resource: :country,
    resource_method_name: :country
end

Note: this will execute the scope active and get you only the countries that are currently actives.

You can use the lambda syntax for a more complex scope.

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    resources_scope: lambda{ |scope, params, controller|
      scope.by_active_state(params[:active_state]).includes(:cities)
    },
    pagination: true,
    params_resource: :country,
    resource_method_name: :country
end

SEARCH - search- search_options

The search option enable ransack in case that you have installed it. And the search_options allows you to pass a hash of parameters to the result method of ransack like distinct: true

class Admin::CountriesController < ApplicationController
  resource_for :"Country",
    search: true,
    search_options: {distinct: true},
    resources_scope: :active,
    pagination: true,
    params_resource: :country,
    resource_method_name: :country
end

NOTE: For the use of the** search_form_for** you have the resources_search helper that is a racksack object or in this case countries_search because we used the resource alias resource_method_name

= search_form_for [:admin, countries_search] do |f|
  = f.label :name_cont
  = f.search_field :name_cont
  = f.submit

**Overriding methods **

**Redirects **

By default, after any of the REST actions that modify the record (create, update, destroy) it redirects to the index action of that controller, but if you define method after_#{action_name}_path_for that returns a path it will execute this method and redirect to that particular path.

Example

  def after_create_path_for
    root_url
  end

NOTE: After creating the record it will redirect to the root_url

default REST actions

If you want to override any of the REST actions, to add any extra logic that you may need, you can just pass a block to the save_resource or destroy_resource inside the actions and add your custom logic there.

Example

  def create
    save_resource do
      # Add you complex logic here
      if resource_saved?
        flash[:notice] = I18n.t("app.record_successfully_created")
        redirect_to root_url and return
      else
        render action: :new
      end
    end
  end

NOTE: Remember that you can make use of the resource_saved? method to know if the record has been saved

**Using it with Grape **

If you are using resources with the Grape gem fallow the next steps:

In your Gemfile add the resources after grape

gem "grape"
gem 'grape-raketasks'
gem "hashie-forbidden_attributes"
gem "resources"

Now in your api class add the helpers ::Resources::GrapeHelpers and in the execute the resource_for inside a before block.

require "resources"
require "resources/grape_helpers" # only need to add this line if you didnt do the previous step
module Twitter
  class API < Grape::API
    version 'v1', using: :header, vendor: 'twitter'
    format :json
    prefix :api

    helpers ::Resources::GrapeHelpers

    before do
      resource_for :"Country"
    end

    resource :countries do
      desc "Return a list of countries."
      get do
        resources
      end

      desc "Return a country."
      get ':id' do
        resource
      end

      desc "Update a country."
      put ':id' do
        save_resource
      end

    end

  end
end

NOTE: Currently there is a limitation, the option resource_method_name doesn't work inside grape

**GLOBAL CONFIGURATION **

You can change the default parameters of any configuration by change the options in the config/initializers/resources.rb that was generated by running rails g resources:install

Resources.config do |config|
  config.params_search = :q # ransack search parameter. Default params[:q]
  config.params_resource = :resource # resource parameter to be saved.  
end

Copyright

Copyright (c) 2015 Emilio Forrer. See LICENSE.txt for further details.