decent_exposure 2.3.3 → 3.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e9fff0c90cb010d9b35e02bc714102c23bd75bbe
-  data.tar.gz: 94da8ffea402d21cd7cfc9b5f34e1e4a9412c25e
+  metadata.gz: 2ec6d62cc52928970902ade2a9998e8f58758f7c
+  data.tar.gz: 0a3aff2440f88ed56a20197d270402c826c6b5e3
 SHA512:
-  metadata.gz: 3dcca3f45da8a0af81eca8aadefc5c399c4e8f7cbddc20522c3b1902849a06a19f4a50e89f013f96d2934d57cf846e9f6fafd6b51e65c36907a0a76963fdd613
-  data.tar.gz: 0748f7dac7ac669e937719541b189f8c2337aada64a69124f784edfd3a387c6f11cbe11bf7fe23713c912a5e84dcfcc51f8c5fbb1f3f6fa63c9b983a0dc42354
+  metadata.gz: c085171f6369dda3d9ae3f459aed654dcdc5a0934f28b61b605ffa1cbff9951cc5b44b214179d3969764064c748c7cddac8dc58655c7972f09dcaa6c5bec0bff
+  data.tar.gz: 692f0b40e7d1435ebaec5ac4d96422b8cb69592afcb3b5010c597f71f65f7c3f88588ee26dffd17ae38cd83ad269f5fa1581030bbf132ea3c4a63a8b38d1bf81

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 2.2.2
+  - 2.3.0

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Hashrocket
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,501 +1,338 @@
-[![Gem Version](https://badge.fury.io/rb/decent_exposure.svg)](https://badge.fury.io/rb/decent_exposure)
-[![Build Status](https://api.travis-ci.org/hashrocket/decent_exposure.svg?branch=master)](https://travis-ci.org/hashrocket/decent_exposure) 
-[![Code Climate](https://codeclimate.com/github/hashrocket/decent_exposure/badges/gpa.svg)](https://codeclimate.com/github/hashrocket/decent_exposure)
+![Decent Exposure](decent_exposure.png)
 
-**Note**: Version 2.3.x will be the last series of releases that support
-Rails 3.x and Ruby 1.8/1.9. Starting with version 3.0, Decent Exposure
-will only support Rails 4.0 and above, and Ruby 2.0 and above.
+[![Gem Version](https://img.shields.io/gem/v/decent_exposure.svg)](https://rubygems.org/gems/decent_exposure)
+[![Build Status](https://img.shields.io/travis/hashrocket/decent_exposure.svg)](http://travis-ci.org/hashrocket/decent_exposure)
+[![Code Climate](https://img.shields.io/codeclimate/github/hashrocket/decent_exposure.svg)](https://codeclimate.com/github/hashrocket/decent_exposure)
+[![Inline docs](http://inch-ci.org/github/hashrocket/decent_exposure.svg?branch=master&style=shields)](http://inch-ci.org/github/hashrocket/decent_exposure)
 
-## Mad Decent
+### Notice
 
-Rails controllers are the sweaty armpit of every rails app. This is due, in
-large part, to the fact that they expose their instance variables directly to
-their views. This means that your instance variables are your interface... and
-that you've broken encapsulation. Instance variables are meant to be private,
-for Science's sake!
+DecentExposure `3.0` is a major change from `< 3.0`. If you are using `rails <= 4.2.x` please look at `decent_exposure < 3.0`.
 
-What `decent_exposure` proposes is that you go from this:
+**Be aware... mild API changes ahead.**
+
+### Installation
+
+Add this line to your application's Gemfile:
 
 ```ruby
-class Controller
-  def new
-    @person = Person.new(params[:person])
-  end
+gem 'decent_exposure'
+```
 
-  def create
-    @person = Person.new(params[:person])
-    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(params[:person])
-      redirect_to(@person)
-    else
-      render :edit
-    end
-  end
+Or install it yourself as:
+
+    $ gem install decent_exposure
+
+### API
+
+The whole API consists of three methods so far: `expose`, `expose!`, and
+`exposure_config`.
+
+In the simplest scenario you'll just use it to expose a model in the
+controller:
+
+```ruby
+class ThingsController < ApplicationController
+  expose :thing
 end
 ```
 
-To something like this:
+Now every time you call `thing` in your controller or view, it will look for an
+ID and try to perform `Thing.find(id)`. If the ID isn't found, it will call
+`Thing.new(things_params)`. The result will be memoized in an `@exposed_thing`
+instance variable.
+
+#### Example Controller
+
+Here's what a standard Rails 4 CRUD controller using Decent Exposure might look like:
 
 ```ruby
-class Controller
-  expose(:person)
+class ThingsController < ApplicationController
+  expose :things, ->{ Thing.all }
+  expose :thing
 
   def create
-    if person.save
-      redirect_to(person)
+    if thing.save
+      redirect_to thing_path(thing)
     else
       render :new
     end
   end
 
   def update
-    if person.save
-      redirect_to(person)
+    if thing.update(thing_params)
+      redirect_to thing_path(thing)
     else
       render :edit
     end
   end
-end
-```
-
-And your views from this:
 
-```ruby
-@person.email
-```
+  def destroy
+    thing.destroy
+    redirect_to things_path
+  end
 
-To simply this:
+  private
 
-```ruby
-person.email
+  def thing_params
+    params.require(:thing).permit(:foo, :bar)
+  end
+end
 ```
 
-In your forms, instead of this:
+### Under the Hood
 
-```ruby
-= form_for @person do |f|
-  ...
-```
-
-To this:
+The default resolving workflow is pretty powerful and customizable. It could be
+expressed with the following pseudocode:
 
 ```ruby
-= form_for person do |f|
-  ...
-```
-
-`decent_exposure` makes it easy to define named methods that are made available
-to your views and which memoize the resultant values. It also tucks away the
-details of the common fetching, initializing and updating of resources and
-their parameters.
-
-That's neat and all, but the real advantage comes when it's time to refactor
-(because you've encapsulated now). What happens when you need to scope your
-`Person` resource from a `Company`? Which implementation isolates those changes
-better? In that particular example, `decent_exposure` goes one step farther and
-will handle the scoping for you (with a smidge of configuration) while still
-handling all that repetitive initialization, as we'll see next.
-
-Even if you decide not to use `decent_exposure`, do yourself a favor and stop
-using instance variables in your views. Your code will be cleaner and easier to
-refactor as a result. If you want to learn more about this approach, I've
-expanded on my thoughts in the article [A Diatribe on Maintaining State][1].
+def fetch(scope, id)
+  instance = id ? find(id, scope) : build(build_params, scope)
+  decorate(instance)
+end
 
-## Environmental Awareness
+def id
+  params[:thing_id] || params[:id]
+end
 
-Well, no it won't lessen your carbon footprint, but it does take a lot of
-cues from what's going on around it...
+def find(id, scope)
+  scope.find(id)
+end
 
-`decent_exposure` will build the requested object in one of a couple of ways
-depending on what the `params` make available to it. At its simplest, when an
-`id` is present in the `params` hash, `decent_exposure` will attempt to find a
-record. In absence of `params[:id]` `decent_exposure` will try to build a new
-record.
+def build(params, scope)
+  scope.new(params) # Thing.new(params)
+end
 
-Once the object has been obtained, it attempts to set the attributes of the
-resulting object. Thus, a newly minted `person` instance will get any
-attributes set that've been passed along in `params[:person]`.  When you
-interact with `person` in your create action, just call save on it and handle
-the valid/invalid branch. Let's revisit our previous example:
+def scope
+  model # Thing
+end
 
-```ruby
-class Controller
-  expose(:person)
+def model
+  exposure_name.classify.constantize # :thing -> Thing
+end
 
-  def create
-    if person.save
-      redirect_to(person)
-    else
-      render :new
-    end
+def build_params
+  if respond_to?(:thing_params, true) && !request.get?
+    thing_params
+  else
+    {}
   end
 end
-```
 
-Behind the scenes, `decent_exposure` has essentially done this:
-
-```ruby
-person.attributes = params[:person]
+def decorate(thing)
+  thing
+end
 ```
 
-In Rails, this assignment is actually a merge with the current attributes and
-it marks attributes as dirty as you would expect. This is why you're simply
-able to call `save` on the `person` instance in the create action, rather than
-the typical `update_attributes(params[:person])`.
-
-**An Aside**
+The exposure is also lazy, which means that it won't do anything until you call
+the method. To eliminate this laziness you can use the `expose!` macro instead,
+which will try to resolve the exposure in a before filter.
 
-Did you notice there's no `new` action? Yeah, that's because we don't need it.
-More often than not actions that respond to `GET` requests are just setting up
-state. Since we've declared an interface to our state and made it available to
-the view (a.k.a. the place where we actually want to access it), we just let
-Rails do it's magic and render the `new` view, lazily evaluating `person` when
-we actually need it.
+It is possible to override each step with options. The acceptable options to the
+`expose` macro are:
 
-**A Caveat**
+### `fetch`
 
-Rails conveniently responds with a 404 if you get a record not found in the
-controller. Since we don't find the object until we're in the view in this
-paradigm, we get an ugly `ActionView::TemplateError` instead. If this is
-problematic for you, consider using the `expose!` method to circumvent lazy
-evaluation and eagerly evaluate whilst still in the controller.
+This is the entry point. The `fetch` proc defines how to resolve your exposure
+in the first place.
 
-## Usage
+```ruby
+expose :thing, fetch: ->{ get_thing_some_way_or_another }
+```
 
-In an effort to make the examples below a bit less magical, we'll offer a
-simplified explanation for how the exposed resource would be queried for
-(assuming you are using `ActiveRecord`).
+Because the above behavior overrides the normal workflow, all other options
+would be ignored. However, Decent Exposure is decent enough to actually blow
+up with an error so you don't accidentally do this.
 
-### Obtaining an instance of an object:
+There are other less verbose ways to pass the `fetch` block, since you'll
+probably be using it often:
 
 ```ruby
-expose(:person)
+expose(:thing){ get_thing_some_way_or_another }
 ```
 
-**Query Explanation**
-
-<table>
-  <tr>
-    <td><code>id</code> present?</td>
-    <td>Query</td>
-  </tr>
-  <tr>
-    <td><code>true</code></td>
-    <td><code>Person.find(params[:id])</code></td>
-  </tr>
-  <tr>
-    <td><code>false</code></td>
-    <td><code>Person.new(params[:person])</code></td>
-  </tr>
-</table>
-
-### Obtaining a collection of objects
+Or
 
 ```ruby
-expose(:people)
+expose :thing, ->{ get_thing_some_way_or_another }
 ```
 
-**Query Explanation**
-
-<table>
-  <tr>
-    <td>Query</td>
-  </tr>
-  <tr>
-    <td><code>Person.scoped</code></td>
-  </tr>
-</table>
-
-### Scoping your object queries
-
-Want to scope your queries to ensure object hierarchy? `decent_exposure`
-automatically scopes singular forms of a resource from a plural form where
-they're defined:
+Or even shorter
 
 ```ruby
-expose(:people)
-expose(:person)
+expose :thing, :get_thing_some_way_or_another
 ```
 
-**Query Explanation**
-
-<table>
-  <tr>
-    <td><code>id</code> present?</td>
-    <td>Query</td>
-  </tr>
-  <tr>
-    <td><code>true</code></td>
-    <td><code>Person.scoped.find(params[:id])</code></td>
-  </tr>
-  <tr>
-    <td><code>false</code></td>
-    <td><code>Person.scoped.new(params[:person])</code></td>
-  </tr>
-</table>
-
-How about a more realistic scenario where the object hierarchy specifies
-something useful, like only finding people in a given company:
+There is another shortcut that allows you to redefine the entire fetch block
+with less code:
 
 ```ruby
-expose(:company)
-expose(:people, ancestor: :company)
-expose(:person)
+expose :comments, from: :post
+# equivalent to 
+expose :comments, ->{ post.comments }
 ```
 
-**Query Explanation**
-
-<table>
-  <tr>
-    <td>person <code>id</code> present?</td>
-    <td>Query</td>
-  </tr>
-  <tr>
-    <td><code>true</code></td>
-    <td><code>Company.find(params[:company_id]).people.find(params[:id])</code></td>
-  </tr>
-  <tr>
-    <td><code>false</code></td>
-    <td><code>Company.find(params[:company_id]).people.new(params[:person])</code></td>
-  </tr>
-</table>
+### `id`
 
-### Further configuration
+The default fetch logic relies on the presence of an ID. And of course Decent
+Exposure allows you to specify how exactly you want the ID to be extracted.
 
-`decent_exposure` is a configurable beast. Let's take a look at some of the
-things you can do:
-
-**Specify the model name:**
+Default behavior could be expressed using following code:
 
 ```ruby
-expose(:company, model: :enterprisey_company)
+expose :thing, id: ->{ params[:thing_id] || params[:id] }
 ```
 
-**Specify the parameter accessor method:**
+But nothing is stopping you from throwing in any arbitrary code:
 
 ```ruby
-expose(:company, params: :company_params)
+expose :thing, id: ->{ 42 }
 ```
 
-**Specify the finder method:**
+Passing lambdas might not always be fun, so here are a couple of shortcuts that
+could help make life easier.
 
 ```ruby
-expose(:article, finder: :find_by_slug)
+expose :thing, id: :custom_thing_id
+# equivalent to
+expose :thing, id: ->{ params[:custom_thing_id] }
+
+expose :thing, id: [:try_this_id, :or_maybe_that_id]
+# equivalent to
+expose :thing, id: ->{ params[:try_this_id] || params[:or_maybe_that_id] }
 ```
 
-**Specify the parameter key to use to fetch the object:**
+### `find`
+
+If an ID was provided, Decent Exposure will try to find the model using it.
+Default behavior could be expressed with this configuration: 
 
 ```ruby
-expose(:article, finder_parameter: :slug)
+expose :thing, find: ->(id, scope){ scope.find(id) }
 ```
 
-### Setting a distinct object for a single action
+Where `scope` is a model scope, like `Thing` or `User.active` or
+`Post.published`.
 
-There are times when one action in a controller is different from the
-rest of the actions. Rather than putting conditional logic in your
-exposure block, a better approach is the use the controller's setter
-methods:
+Now, if you're using FriendlyId or Stringex or something similar, you'd have to
+customize your finding logic. Your code might look somewhat like this:
 
 ```ruby
-expose(:articles) { current_user.articles }
-expose(:article)
-
-def index
-  self.articles = Article.all
-end
+expose :thing, find: ->(id, scope){ scope.find_by!(slug: id) }
 ```
 
-### Getting your hands dirty
-
-While we try to make things as easy for you as possible, sometimes you just
-need to go off the beaten path. For those times, `expose` takes a block which
-it lazily evaluates and returns the result of when called. So for instance:
+Again, because this is likely to happen a lot, Decent Exposure gives you a
+decent shortcut so you can get more done by typing less.
 
 ```ruby
-expose(:environment) { Rails.env }
+expose :thing, find_by: :slug
 ```
 
-This block is evaluated and the memoized result is returned whenever you call
-`environment`.
-
-#### Using the Default decent_exposure Goodness
+### `build`
 
-If you don't want to go too far off the beaten path, the value of the default
-exposure can be easily obtained inside of your custom block. The block will
-receive a proxy object that you can use to lazily evaluate
-the default decent_exposure logic. For example:
+When an ID is not present, Decent Exposure tries to build an object for you.
+By default, it behaves like this:
 
 ```ruby
-expose(:articles) {|default| default.limit(10) }
+expose :thing, build: ->(thing_params, scope){ scope.new(thing_params) }
 ```
 
-This allows you to customize your exposures, without having to redo all of
-the built-in logic decent_exposure gives you out of the box.
+### `build_params`
 
-### Custom strategies
+These options are 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 `thing_params` controller method if it's
+available and the request method is not `GET`. In all other cases it produces
+an empty hash.
 
-For the times when custom behavior is needed for resource finding,
-`decent_exposure` provides a base class for extending. For example, if
-scoping a resource from `current_user` is not an option, but you'd like
-to verify a resource's relationship to the `current_user`, you can use a
-custom strategy like the following:
+You can easily specify which controller method you want it to call instead of
+`thing_params`, or just provide your own logic:
 
 ```ruby
-class VerifiableStrategy < DecentExposure::Strategy
-  delegate :current_user, :to => :controller
+expose :thing, build_params: :custom_thing_params
+expose :other_thing, build_params: ->{ { foo: "bar" } }
 
-  def resource
-    instance = model.find(params[:id])
-    if current_user != instance.user
-      raise ActiveRecord::RecordNotFound
-    end
-    instance
-  end
-end
-```
-
-You would then use your custom strategy in your controller:
+private
 
-```ruby
-expose(:post, strategy: VerifiableStrategy)
+def custom_thing_params
+  # strong parameters stuff goes here
+end
 ```
 
-The API only necessitates you to define `resource`, but provides some
-common helpers to access common things, such as the `params` hash. For
-everything else, you can delegate to `controller`, which is the same as
-`self` in the context of a normal controller action.
-
-### Customizing your exposures
+### `scope`
 
-For most things, you'll be able to pass a few configuration options and get
-the desired behavior. For changes you want to affect every call to `expose` in
-a controller or controllers inheriting from it (e.g. `ApplicationController`,
-if you need to change the behavior for all your controllers), you can define
-an `decent_configuration` block:
+Defines the scope that's used in `find` and `build` steps.
 
 ```ruby
-class ApplicationController < ActionController::Base
-  decent_configuration do
-    strategy MongoidStrategy
-  end
-end
+expose :thing, scope: ->{ current_user.things }
+expose :user, scope: ->{ User.active }
+expose :post, scope: ->{ Post.published }
 ```
 
-A `decent_configuration` block without a `:name` argument is considered the
-"default" configuration for that controller (and it's ancestors).  All things
-considered, you probably only want to change the strategy in a default.
-Nonetheless, you can pass any configuration option you can to an individual
-exposure to the `decent_configuration` block.
-
-If you don't want a specific configuration to affect every exposure in the
-given controller, you can give it a name like so:
+Like before, shortcuts are there to make you happier:
 
 ```ruby
-class ArticleController < ApplicationController
-  decent_configuration(:sluggable) do
-    finder :find_by_slug
-    finder_parameter :slug
-  end
-end
+expose :post, scope: :published
+# equivalent to
+expose :post, scope: ->{ Post.published }
 ```
 
-And opt into it like so:
+and
 
 ```ruby
-expose(:article, config: :sluggable)
+expose :thing, parent: :current_user
+# equivalent to:
+expose :thing, scope: ->{ current_user.things }
 ```
 
-## Usage with Rails 4 (or strong\_parameters plugin)
+### `model`
 
-If you're using Rails 4 or
-[strong\_parameters](https://github.com/rails/strong_parameters), add the
-following to your ApplicationController:
+Allows you to specify the model class to use. Pretty straightforward.
 
-
-``` ruby
-class ApplicationController < ActionController::Base
-  decent_configuration do
-    strategy DecentExposure::StrongParametersStrategy
-  end
-end
+```ruby
+expose :thing, model: ->{ AnotherThing }
+expose :thing, model: AnotherThing
+expose :thing, model: "AnotherThing"
+expose :thing, model: :another_thing
 ```
 
-Then, when you'd like parameters to be assigned to a model, add the
-`attributes` option to your exposure:
+### `decorate`
 
-```ruby
-class FooController < ApplicationController
-  expose(:foo, attributes: :foo_params)
+Before returning the thing, Decent Exposure will run it through the
+decoration process. Initially, this does nothing, but you can obviously change
+that:
 
-  private
-  def foo_params
-    params.require(:foo).permit(:bar, :baz)
-  end
-end
+```ruby
+expose :thing, decorate: ->(thing){ ThingDecorator.new(thing) }
 ```
 
-In the example above, `foo_params` will only be called on a PUT, POST or
-PATCH request.
+## `exposure_config`
 
-
-## Testing
-
-Controller testing remains trivially easy. The shift is that you now set expectations on methods rather than instance variables. With RSpec, this mostly means avoiding `assign` and `assigns`.
+You can pre-save some configuration with `exposure_config` method to reuse it
+later.
 
 ```ruby
-describe CompaniesController do
-  describe "GET index" do
-
-    # this...
-    it "assigns @companies" do
-      company = Company.create
-      get :index
-      assigns(:companies).should eq([company])
-    end
+exposure_config :cool_find, find: ->{ very_cool_find_code }
+exposure_config :cool_build, build: ->{ very_cool_build_code }
 
-    # becomes this
-    it "exposes companies" do
-      company = Company.create
-      get :index
-      controller.companies.should eq([company])
-    end
-  end
-end
+expose :thing, with: [:cool_find, :cool_build]
+expose :another_thing, with: :cool_build
 ```
 
-View specs follow a similar pattern:
+## Contributing
 
-```ruby
-describe "people/index.html.erb" do
+1. Fork it (https://github.com/hashrocket/decent_exposure/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
 
-  # this...
-  it "lists people" do
-    assign(:people, [ mock_model(Person, name: 'John Doe') ])
-    render
-    rendered.should have_content('John Doe')
-  end
-
-  # becomes this
-  it "lists people" do
-    view.stub(people: [ mock_model(Person, name: 'John Doe') ])
-    render
-    rendered.should have_content('John Doe')
-  end
-
-end
-```
+## About
 
+[![Hashrocket logo](hashrocket_logo.png)](https://hashrocket.com)
 
-[1]: http://stephencaudill.com/blog/2010/a-diatribe-on-maintaining-state.html
+Decent Exposure is supported by the team at [Hashrocket](https://hashrocket.com), a multidisciplinary design & development consultancy. If you'd like to [work with us](https://hashrocket.com/contact-us/hire-us) or [join our team](https://hashrocket.com/contact-us/jobs), don't hesitate to get in touch.