resourcerer 0.2.2 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 55448f1a54313470f4c84d50243ad79ce0f13750
-  data.tar.gz: 30de7964ebdff67394987395145c00e156cdafe9
+SHA256:
+  metadata.gz: 1097af8bba31336db7caf41e84c05587cb1f43fb3561405c28e73f9a034d510d
+  data.tar.gz: fce0ba2273e4632d6ea879d97d3b3de6a66c9ba8398416ad488b8b81ade15bcb
 SHA512:
-  metadata.gz: 0201a4f045934bd7b2bfc9fd7ca32b324386d618c84ee9da16963d73002472d801c7487972151a29d856c3f926725748f05a08e05844819cd29fec7c736ee4d5
-  data.tar.gz: b06fb4cbbc6216be391e6bf9af24019596a4af8bd0459fd30f2e3178c6d99be48743ee17474b0497f4c5f2e773686a918fe9f504f43fb1d5fa1f1186a0b3f593
+  metadata.gz: e8cc87a1601df6643f9abb2134b236379f00bca9a39ae088f2670051651b2e422f896c1684602c215d1a98c72576a2f8c46f3310839fd4cc0d2a392990febdc8
+  data.tar.gz: 9e9d1ab0976fcdccb8987b90d2368ae46dc65f1848787a51644e31ba213e16351b77a85739f9b2ab49ab7c02a3cda1687380e3f0dfc876273038c1cc3e2499ce

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## Resourcerer 2.0.4 (2021-02-24) ##
+
+*   Update `ruby_version` requirement in gemspec to allow usage in Ruby 3.0.
+
+## Resourcerer 2.0.3 (2017-04-03) ##
+
+*   Complete rewrite, embrace functions as first-class citizens for configuration.

data/README.md

@@ -1,294 +1,315 @@
+<h1 align="center">
 Resourcerer
-=====================
-What `resourcerer` proposes is that you go from this:
+<p align="center">
+  <a href="https://github.com/ElMassimo/resourcerer/actions">
+    <img alt="Build Status" src="https://github.com/ElMassimo/resourcerer/workflows/build/badge.svg"/>
+  </a>
+  <a href="https://codeclimate.com/github/ElMassimo/vite_ruby">
+    <img alt="Maintainability" src="https://codeclimate.com/github/ElMassimo/vite_ruby/badges/gpa.svg"/>
+  </a>
+  <a href="https://codeclimate.com/github/ElMassimo/resourcerer">
+    <img alt="Test Coverage" src="https://codeclimate.com/github/ElMassimo/resourcerer/badges/coverage.svg"/>
+  </a>
+  <a href="https://rubygems.org/gems/resourcerer">
+    <img alt="Gem Version" src="https://img.shields.io/gem/v/resourcerer.svg?colorB=e9573f"/>
+  </a>
+  <a href="https://github.com/ElMassimo/resourcerer/blob/master/LICENSE.txt">
+    <img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/>
+  </a>
+</p>
+</h1>
+
+A small library to help you avoid boilerplate for standard CRUD actions, while improving your controllers' readibility.
+
+### Installation
+
+Add this line to your application's Gemfile:
 
 ```ruby
-class PersonController < ApplicationController
-  def new
-    @person = Person.new
-  end
+gem 'resourcerer'
+```
 
-  def create
-    @person = Person.new(person_params)
-    if @person.save
-      redirect_to(@person)
-    else
-      render :new
-    end
-  end
+And then execute:
 
-  def edit
-    @person = Person.find(params[:id])
-  end
+    $ bundle
 
-  def update
-    @person = Person.find(params[:id])
-    if @person.update_attributes(person_params)
-      redirect_to(@person)
-    else
-      render :edit
-    end
-  end
-  
-  private
-    def person_params
-      params.require(:person).permit(:name)
-    end
+Or install it yourself as:
+
+    $ gem install resourcerer
+
+### Usage
+
+In the simplest scenario you'll just use it to define a resource in the controller:
+
+```ruby
+class BandsController < ApplicationController
+  resource :band
 end
 ```
 
-To something like this:
+Now every time you call `band` in your controller or view, it will look for an
+ID and try to perform `Band.find(id)`. If an ID parameter isn't found, it will
+call `Band.new(band_params)`. The result will be memoized in a
+`@resourcerer_band` instance variable.
+
+#### Example
+
+Here's what a standard Rails CRUD controller using Resourcerer might look like:
 
 ```ruby
-class PersonController < ApplicationController
-  resource :person
+class BandsController < ApplicationController
+  resource :band do
+    permit [:name, :genre]
+  end
 
   def create
-    if person.save
-      redirect_to(person)
+    if band.save
+      redirect_to band_path(band)
     else
       render :new
     end
   end
 
   def update
-    if person.save
-      redirect_to(person)
+    if band.save
+      redirect_to band_path(band)
     else
       render :edit
     end
   end
-  
-  private
-    def person_params
-      params.require(:person).permit(:name)
-    end
+
+  def destroy
+    band.destroy
+    redirect_to bands_path
+  end
 end
 ```
 
-The idea is that you don't have to write boilerplate for standard CRUD actions, while at the same time improving your controllers readibility.
+That's [way less code than usual!](https://gist.github.com/ElMassimo/18fbdb7108f46f3c975712945f7a3318) :smiley:
 
-## Usage
+### Under the Hood
 
-Let's see what Resourcerer is doing behind the curtains :smiley:.
+The default resolving workflow is pretty powerful and customizable. It could be
+expressed with the following pseudocode:
 
-This examples assume that you are using Rails 4 Strong Parameters.
+```ruby
+def fetch(scope, id)
+  instance = id ? find(id, scope) : build(attrs, scope)
+  instance.tap { instance.assign_attributes(attrs) if assign? }
+end
 
-### Obtaining a resource:
+def id
+  params[:band_id] || params[:id]
+end
 
-```ruby
-resource :person
-```
+def find(id, scope)
+  scope.find(id)
+end
+
+def build(params, scope)
+  scope.new(params) # Band.new(params)
+end
+
+def scope
+  model # Band
+end
 
-**Query Explanation**
+def model
+  :band.classify.constantize # Band
+end
 
-<table>
-  <tr>
-    <td><code>id</code> present?</td>
-    <td>Query (get/delete)</td>
-    <td>Query (post/patch/put)</td>
-  </tr>
-  <tr>
-    <td><code>true</code></td>
-    <td><code>Person.find(params[:id])</code></td>
-    <td><code>Person.find(params[:id]).attributes = person_params</code></td>
-  </tr>
-  <tr>
-    <td><code>false</code></td>
-    <td><code>Person.new</code></td>
-    <td><code>Person.new(person_params)</code></td>
-  </tr>
-</table>
+def assign?
+  action_name == 'update'
+end
 
+def attrs
+  if respond_to?(:band_params, true) && !request.get?
+    band_params
+  else
+    {}
+  end
+end
+```
+The resource is lazy, so it won't do anyband until the method is called.
 
-### Configuration
+## Configuration
 
-Let's take a look at some of the things you can do:
+It is possible to override each step with options. The acceptable options to the
+`resource` macro are:
 
-**Specify the model name:**
+### `id`
+
+In order to fetch a resource Resourcerer relies on the presence of an ID:
 
 ```ruby
-resource(:company, model: :enterprise)
+# Default Behavior
+resource :band, id: ->{ params[:band_id] || params[:id] }
 ```
 
-**Specify the parameter key to use to fetch the object:**
+You can override any option's default behavior by passing in a `Proc`:
 
 ```ruby
-resource(:enterprise, finder_param: :company_id)
+resource :band, id: ->{ 42 }
 ```
 
-**Specify the model attribute to use to perform the search:**
+Passing lambdas might not always be fun, so most options provide shortcuts that
+might help make life easier:
 
 ```ruby
-resource(:enterprise, find_by: :name)
+resource :band, id: :custom_band_id
+# same as
+resource :band, id: ->{ params[:custom_band_id] }
+
+resource :band, id: [:try_this_id, :or_maybe_that_id]
+# same as
+resource :band, id: ->{ params[:try_this_id] || params[:or_maybe_that_id] }
 ```
 
-**Specify how to obtain the object attributes:**
+### `find`
+
+If an ID was provided, Resourcerer will try to find the model:
 
 ```ruby
-# Specify the strong parameters method's name when using the default `StrongParametersStrategy`
-resource(:employee, attributes_method: :person_params)
+# Default Behavior
+resource :band, find: -> (id, scope) { scope.find(id) }
+```
+
+Where `scope` is a model scope, like `Band` or `User.active` or
+`Post.published`. There's even a convenient shortcut for cases where the ID is
+actually something else:
 
-# Specify the parameter key that holds the attributes when using the `EagerAttributesStrategy`
-resource(:person, param_key: :employee)
+```ruby
+resource :band, find_by: :slug
+# same as
+resource :band, find: ->(slug, scope){ scope.find_by!(slug: slug) }
 ```
 
-### DSL
-Resourcer also features a nice DSL, which is helpful when you need more control over the resource
-lifecycle.
+### `build`
+
+When an ID is not present, Resourcerer tries to build an object for you:
 
-You can also access every configuration option available above:
 ```ruby
-resource(:employee) do
-  model :person
-  find_by :name
-  find {|name| company.find_employee(name) }
-  build { company.new_employee }
-  assign { params.require(:employee).permit(:name) }
-end
-# is the same as:
-resource(:employee, model: :person, finder_attribute: :name, finder: ->(name){ company.find_employee(name) }, builder: ->{ company.new_employee }, attributes: ->{ params.require(:employee).permit(:name) })
+# Default Behavior
+resource :band, build: ->(attrs, scope){ scope.new(band_params) }
 ```
-The DSL is more convenient when you have an object oriented design and want to allow an object to handle its collections, or as a quick way to set the StrongParameters method.
 
-Configuration options play well together, and the defaults try to make intelligent use of them. For example,
-setting the `finder_attribute` in the example abovie changes the `finder_param` to `person_name` instead of `person_id`, and the value of that parameter is provided to the finder block.
+### `attrs`
 
-### Setting a distinct object for a single action
+This option is responsible for calulating params before passing them to the
+build step. The default behavior was modeled with Strong Parameters in mind and
+is somewhat smart: it calls the `band_params` controller method if it's
+available and the request method is not `GET`. In all other cases it produces
+an empty hash.
 
-There are times when one action in a controller is different from the
-rest of the actions. A nice approach to circumvent this is to use the
-controller's setter methods. This example uses [presenter_rails](https://github.com/ElMassimo/presenter_rails).
+You can easily specify which controller method you want it to call instead of
+`band_params`, or just provide your own logic:
 
 ```ruby
-resource(:article)
+resource :band, attrs: :custom_band_params
+resource :other_band, attrs: ->{ { foo: "bar" } }
 
-def show_oldest
-  self.article = Article.find_oldest
-end
+private
 
-present :article do
-  ArticlePresenter.new(article)
+def custom_band_params
+  params.require(:band).permit(:name, :genre)
 end
 ```
 
-### Custom strategies
-
-For times when you need custom behavior for resource finding, you can
-create your own strategy by extending `Resourcerer::Strategy`:
+Using the default model name conventions? `permit` can do that for you:
 
 ```ruby
-class VerifiableStrategy < Resourcerer::Strategy
-  delegate :current_user, :to => :controller
+resource :band, permit: [:name, :genre]
+```
 
-  def resource
-    instance = model.find(params[:id])
-    if current_user != instance.user
-      raise ActiveRecord::RecordNotFound
-    end
-    instance
-  end
-end
+### `collection`
+
+Defines the scope that's used in `find` and `build` steps:
+
+```ruby
+resource :band, collection: ->{ current_user.bands }
 ```
 
-You would then use your custom strategy in your controller:
+### `model`
+
+Allows you to specify the model class to use:
 
 ```ruby
-resource(:post, strategy: VerifiableStrategy)
+resource :band, model: ->{ AnotherBand }
+resource :band, model: AnotherBand
+resource :band, model: "AnotherBand"
+resource :band, model: :another_band
 ```
 
-## Using decorators or presenters
-### With [draper](http://github.com/drapergem/draper)
+### `assign` and `assign?`
 
-If you use decorators, you can go from something like this:
+Allows you to specify whether the attributes should be assigned:
 
 ```ruby
-class PersonController < ApplicationController
-  def new
-    @person = Person.new.decorate
-  end
+resource :band, assign?: false
+resource :band, assign?: [:edit, :update]
+resource :band, assign?: ->{ current_user.admin? }
+```
 
-  def create
-    @person = Person.new(person_params)
-    if @person.save
-      redirect_to(@person)
-    else
-      @person = @person.decorate
-      render :new
-    end
-  end
+and also how to assign them:
 
-  def edit
-    @person = Person.find(params[:id]).decorate
-  end
+```ruby
+resource :band, assign: ->(band, attrs) { band.set_info(attrs) }
 
-  def update
-    @person = Person.find(params[:id])
-    if @person.update_attributes(person_params)
-      redirect_to(@person)
-    else
-      @person = @person.decorate
-      render :edit
-    end
-  end
-  
-  private
-    def person_params
-      params.require(:person).permit(:name)
-    end
-end
 ```
 
-To something like this by adding [presenter_rails](https://github.com/ElMassimo/presenter_rails) to the mix:
+
+## Advanced Configuration with `resourcerer_config`
+
+You can define configuration presets with the `resourcerer_config` method to reuse
+them later in different resource definitions.
 
 ```ruby
-class PersonController < ApplicationController
-  resource(:person)
-  
-  present :person do
-    person.decorate
-  end
+resourcerer_config :cool_find, find: ->{ very_cool_find_code }
+resourcerer_config :cool_build, build: ->{ very_cool_build_code }
+
+resource :band, using: [:cool_find, :cool_build]
+resource :another_band, using: :cool_build
+```
+
+Options that are passed to `resource` will take precedence over the presets.
+
+
+## Decorators or Presenters (like [draper](http://github.com/drapergem/draper))
+
+If you use decorators, you'll be able to avoid [even more boilerplate](https://gist.github.com/ElMassimo/6775148c0d7364be111531a254b41ba9) if you throw [presenter_rails](https://github.com/ElMassimo/presenter_rails) in the mix:
+
+```ruby
+class BandController < ApplicationController
+  resource(:band, permit: :name)
+  present(:band) { band.decorate }
 
   def create
-    if person.save
-      redirect_to(person)
+    if band.save
+      redirect_to(band)
     else
       render :new
     end
   end
 
   def update
-    if person.save
-      redirect_to(person)
+    if band.save
+      redirect_to(band)
     else
       render :edit
     end
   end
-
-  private
-    def person_params
-      params.require(:person).permit(:name)
-    end
 end
 ```
 
-### Comparison with [decent_exposure](https://github.com/voxdolo/decent_exposure).
+### Comparison with [Decent Exposure](https://github.com/hashrocket/decent_exposure).
 
-Resourcerer is heavily inspired on [decent exposure](https://github.com/voxdolo/decent_exposure), it attempts to be more predictable by focusing on finding a resource and assigning attributes, and discarding completely the view exposure part.
+Resourcerer is heavily inspired on [Decent Exposure](https://github.com/hashrocket/decent_exposure), but it attempts to be simpler and more flexible by not focusing on exposing variables to the view context.
 
 #### Similarities
-Both allow you to find or initialize a resource and assign attributes, removing the boilerplate from most CRUD actions.
+Both allow you to find or initialize a model and assign attributes, removing the boilerplate from most CRUD actions.
 
 #### Differences
-Resourcerer does not expose an object to the view in any way, scope the query to a collection method if defined, nor deal with collections.
-
-
-### Caveats
-#### When using StrongParametersStrategy
-Since attributes are assigned on every POST, PUT, and PATCH request, sometimes when using Strong Parameters it's not desirable that the attributes method is called. For that reason, the presence of `params[param_key]` is checked before assigning attributes.
-##### Troubleshooting
-- _The attributes are not being assigned_: Check that the resource name matches the param used in the attributes method, and set the `param_key` configuration if they are different.
-- _Need an error to be thrown if the params are not present_: Use the `EagerStrongParametersStrategy`, available in the sample strategies in this repository, you can set it using the `strategy` configuration option.
+Resourcerer does not expose an object to the view in any way, nor deal with decoratation. It also provides better support for strong parameters.
 
 ### Special Thanks
-Resourcerer was inspired by [decent_exposure](https://github.com/voxdolo/decent_exposure).
+Resourcerer is based on [DecentExposure](https://github.com/hashrocket/decent_exposure).