skinny_controllers 0.7.4 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f9c02facf2a390b5d23ca3f70c5740bf649f3bc
-  data.tar.gz: ee725724fdf275ea1740c6641d1207b5ed9949f6
+  metadata.gz: 5387b4c2379bd53d4a19a66243c529d8e764dfab
+  data.tar.gz: 5c8df4c666ae85e6f762bb68391f06c03c5e21e6
 SHA512:
-  metadata.gz: 5011b18d544388bfb015a4223a0777a926d95540341d0f7107461d658406cbd4cceb535dabe8bb77de5e235ddd1ed28920bf8b74fcd2e252ff7448fa283ddce3
-  data.tar.gz: 9d70c6dd3cdecc598afc7dc49c5f522c09e1fcf1f801ab533488801bf49a747b79815c00af86890f009d8dc67dc50ce6959498b2679f9eaa63271c71ed5ecbd5
+  metadata.gz: d6a9c45f2ba2def7309e979a060a87f984640c03e33340778547f6fae68c56289c9d8f089e5092fd24fed89fef70ca7752095853a2ce219dd1021438cd5ddafe
+  data.tar.gz: 93434e6dd65a1c1a650810acb9b95fae6382570dbe908e538f84206c9f22790da2cfd4c4644eedc510309d9f2cf60c9b0e15700efa09f528b2c0735b0fc0f724

data/README.md

@@ -22,6 +22,20 @@ or
 
 `gem install skinny_controllers`
 
+
+## Generators
+
+```
+rails g operation event_summary
+# => create  app/operations/event_summary_operations.rb
+
+rails g policy event_summary
+# create  app/policies/event_summary_policy.rb
+
+rails g skinny_controller event_summaries
+# create  app/controllers/event_summaries_controller.rb
+```
+
 # Usage
 
 ## In a controller:
@@ -46,6 +60,8 @@ The above does a multitude of assumptions to make sure that you can type the lea
 5. If relying on the default / implicit operations for create and update, the params key for your model's changes much be formatted as `{ Model.name.underscore => { attributes }}``
 6. If using strong parameters, SkinnyControllers will look for `{action}_{model}_params` then `{model}_params` and then `params`. See the `strong_parameters_spec.rb` test to see an example.
 
+
+
 ### Your model name might be different from your resource name
 Lets say you have a JSON API resource that you'd like to render that has some additional/subset of data.
 Maybe the model is an `Event`, and the resource an `EventSummary` (which could do some aggregation of `Event` data).
@@ -244,6 +260,158 @@ end
 ```
 
 
+## More Advanced Usage
+
+These are snippets taking from other projects.
+
+### Finding a record when the id parameter isn't passed
+
+
+
+```ruby
+module HostOperations
+  class Read < SkinnyControllers::Operation::Base
+    def run
+      model # always allowed, never restricted
+    end
+
+    # Needs to be overridden, because a 'host' can be either
+    # an Event or an Organization.
+    #
+    # the params to this method should include the subdomain
+    # e.g.: { subdomain: 'swingin2015' }
+    def model_from_params
+      subdomain = params[:subdomain]
+      # first check the events, since those are more commonly used
+      host = Event.find_by_domain(subdomain)
+      # if the event doesn't exist, see if we have an organization
+      host ||= Organization.find_by_domain(subdomain)
+    end
+  end
+end
+```
+
+### The built in model-finding methods can be completely ignored
+
+The `model` method does not need to be overridden. `run` is what is called on the operation.
+
+```ruby
+module MembershipRenewalOperations
+  # MembershipRenewalsController#index
+  class ReadAll < SkinnyControllers::Operation::Base
+
+    def run
+      # default 'model' functionality is avoided
+      latest_renewals
+    end
+
+    private
+
+    def organization
+      id = params[:organization_id]
+      Organization.find(id)
+    end
+
+    def renewals
+      options = organization.membership_options.includes(renewals: [:user, :membership_option])
+      options.map(&:renewals).flatten
+    end
+
+    def latest_renewals
+      sorted_renewals = renewals.sort_by{|r| [r.user_id,r.updated_at]}.reverse
+
+      # unique picks the first option.
+      # so, because the list is sorted by user id, then updated at,
+      # for each user, the first renewal will be chosen...
+      # and because it is descending, that means the most recent renewal
+      sorted_renewals.uniq{|r| r.user_id}
+    end
+  end
+
+end
+```
+
+## Testing
+
+The whole goal of this project is to minimize the complexity or existence of controller tests, and provide
+a way to unit test business logic.
+
+In the following examples, I'll be using RSpec -- but there isn't anything that would prevent you from using a different testing framework, if you so choose.
+
+### Operations
+
+```ruby
+describe HostOperations do
+  describe HostOperations::Read do
+    context 'model_from_params' do
+      let(:subdomain){ 'subdomain' }
+      # an operation takes a user, and a list of params
+      # there are optional parameters as well, but generally may not be required.
+      # see: `SkinnyControllers:::Operation::Base`
+      let(:operation){ HostOperations::Read.new(nil, { subdomain: subdomain }) }
+
+      it 'finds an event' do
+        event = create(:event, domain: subdomain)
+        model = operation.run
+        expect(model).to eq event
+      end
+      #...
+```
+
+### Policies
+
+With policies, I like to test using Procs, because the setup is the same for most actions, and it's easier to set up different scenarios.
+
+```ruby
+describe PackagePolicy do
+  # will test if the owner of this object can access it
+  let(:by_owner){
+    ->(method){
+      package = create(:package)
+      # a policy takes a user and an object
+      policy = PackagePolicy.new(package.event.hosted_by, package)
+      policy.send(method)
+    }
+  }
+
+  # will test if the person registering with this package has permission
+  let(:by_registrant){
+    ->(method){
+      event = create(:event)
+      package = create(:package, event: event)
+      attendance = create(:attendance, host: event, package: package)
+      # a policy takes a user and an object
+      policy = PackagePolicy.new(attendance.attendee, package)
+      policy.send(method)
+    }
+  }
+
+  context 'can be read?' do
+    it 'by the event owner' do
+      result = by_owner.call(:read?)
+      expect(result).to eq true
+    end
+
+    it 'by a registrant' do
+      result = by_registrant.call(:read?)
+      expect(result).to eq true
+    end
+  end
+
+  context 'can be updated?' do
+    it 'by the event owner' do
+      result = by_owner.call(:update?)
+      expect(result).to eq true
+    end
+
+    it 'by a registrant' do
+      result = by_registrant.call(:update?)
+      expect(result).to eq false
+    end
+  end
+```
+
+
 ## Globally Configurable Options
 
 All of these can be set on `SkinnyControllers`,
@@ -266,17 +434,21 @@ The following options are available:
 |`action_map`| see [skinny_controllers.rb](./lib/skinny_controllers.rb#L61)| |
 
 
+
+
+
+
 -------------------------------------------------------
 
 ## How is this different from trailblazer?
 
 This may not be horribly apparent, but here is a table overviewing some highlevel differences
 
-| Feature | skinny_controllers | [trailblazer](https://github.com/apotonick/trailblazer) |
-|--|--|--|
-| Purpose | API - works very well with [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers)| General - additional featers for server-side rendered views |
-| Added Layers | Operations, Policies | Operations, Policies, Forms |
-| Validation | stay in models | moved to operations via contract block |
-| Additional objects| none | contacts, representers, callbacks, cells |
-| Rendering |  done in the controller, and up to the dev to decide how that is done. `ActiveModel::Serializers` with JSON-API is highly recommended | representers provide a way to define serializers for json, xml, json-api, etc |
-| App Structure |  same as rails. `app/operations` and `app/policies` are added | encourages a new structure 'concepts', where cells, view templates, assets, operations, etc are all under `concepts/{model-name}` |
+| Feature | - | skinny_controllers | [trailblazer](https://github.com/apotonick/trailblazer) |
+|----|----|----|----|
+| Purpose |-| API - works very well with [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers)| General - additional featers for server-side rendered views |
+| Added Layers |-| Operations, Policies | Operations, Policies, Forms |
+| Validation |-| stay in models | moved to operations via contract block |
+| Additional objects|-| none | contacts, representers, callbacks, cells |
+| Rendering |-|  done in the controller, and up to the dev to decide how that is done. `ActiveModel::Serializers` with JSON-API is highly recommended |-| representers provide a way to define serializers for json, xml, json-api, etc |
+| App Structure |-|  same as rails. `app/operations` and `app/policies` are added | encourages a new structure 'concepts', where cells, view templates, assets, operations, etc are all under `concepts/{model-name}` |

data/lib/generators/operation/USAGE

@@ -0,0 +1,5 @@
+Description:
+    Generates an operation for the given resource.
+
+Example:
+    `rails generate operation event_summary`

data/lib/generators/operation/operation_generator.rb

@@ -0,0 +1,16 @@
+class OperationGenerator < Rails::Generators::NamedBase
+  # gives us file_name
+  source_root File.expand_path('../templates', __FILE__)
+
+  def generate_layout
+    template 'operation.rb.erb', File.join('app/operations', class_path, "#{file_name}_operations.rb")
+  end
+
+  def operation_name
+    file_name.camelize
+  end
+
+  def controller_name
+    operation_name.pluralize + 'Controller'
+  end
+end

data/lib/generators/operation/templates/operation.rb.erb

@@ -0,0 +1,64 @@
+module <%= operation_name %>Operations
+
+  # Below are all the available actions an Operation can have.
+  # These directly correlate to the controller actions.  None of
+  # the operations below are required. Default functionality is basic CRUD,
+  # and to always allow the model object to return.
+  # See: SkinnyControllers::Operation::Default#run
+  #
+  # NOTE: If each operation gets big enough, it may be desirable to
+  #       move each operation in to its own file.
+  #
+  # In every operation, the following variables are available to you:
+  # - current_user
+  # - params
+  # - params_for_action - params specific to the action, if configured
+  # - action - current controller action
+  # - model_key - the underscored model_name
+  # - model_params - params based on the model_key in params
+  #
+  # Methods:
+  # - allowed? - calls allowed_for?(model)
+  # - allowed_for? - allows you to pass an object to the policy that corresponds
+  #                  to this operation
+
+  # # <%= controller_name %>#create
+  # class Create < SkinnyControllers::Operation::Base
+  #   def run
+  #    # @model is used here, because the `model` method is memoized using
+  #    # the @model instance variable
+  #    @model = model_class.new(model_params)
+  #    @model.save
+  #    @model
+  #   end
+  # end
+  # 
+  # # <%= controller_name %>#index
+  # class ReadAll < SkinnyControllers::Operation::Base
+  #   def run
+  #     # model is a list of model_class instances
+  #     model if allowed?
+  #   end
+  # end
+  # 
+  # # <%= controller_name %>#show
+  # class Read < SkinnyControllers::Operation::Base
+  #   def run
+  #     model if allowed?
+  #   end
+  # end
+  # 
+  # # <%= controller_name %>#update
+  # class Update < SkinnyControllers::Operation::Base
+  #   def run
+  #     model.update(model_params) if allowed?
+  #   end
+  # end
+  # 
+  # # <%= controller_name %>#destroy
+  # class Delete < SkinnyControllers::Operation::Base
+  #   def run
+  #     model.destroy if allowed?
+  #   end
+  # end
+end

data/lib/generators/policy/USAGE

@@ -0,0 +1,5 @@
+Description:
+    Generates a policy for the given resource.
+
+Example:
+    `rails generate policy event_summary`

data/lib/generators/policy/policy_generator.rb

@@ -0,0 +1,20 @@
+class PolicyGenerator < Rails::Generators::NamedBase
+  # gives us file_name
+  source_root File.expand_path('../templates', __FILE__)
+
+  def generate_layout
+    template 'policy.rb.erb', File.join('app/policies', class_path, "#{file_name}_policy.rb")
+  end
+
+  def policy_name
+    operation_name + 'Policy'
+  end
+
+  def operation_name
+    file_name.camelize
+  end
+
+  def controller_name
+    operation_name.pluralize + 'Controller'
+  end
+end

data/lib/generators/policy/templates/policy.rb.erb

@@ -0,0 +1,40 @@
+class <%= policy_name %> < SkinnyControllers::Policy::Base
+
+  # Below are all the available permissions. Each permission corresponds
+  # to an action in the controller.
+  # Default functionality is to return true (allow) -- so the methods
+  # below do not need to exist, unless you want to add custom logic
+  # to them.
+  #
+  # The following variables are available to you in each policy
+  # - object - the object the user is trying to access.
+  # - user - the current user
+  #
+
+  # <%= controller_name %>#index
+  def read_all?
+    default? # SkinnyControllers.allow_by_default # aka "true"
+  end
+
+  # <%= controller_name %>#show
+  def read?
+    default? # SkinnyControllers.allow_by_default # aka "true"
+  end
+
+  # <%= controller_name %>#create
+  def create?
+    default? # SkinnyControllers.allow_by_default # aka "true"
+  end
+
+  # <%= controller_name %>#update
+  def update?
+    default? # SkinnyControllers.allow_by_default # aka "true"
+  end
+
+  # <%= controller_name %>#destroy
+  def delete?
+    default? # SkinnyControllers.allow_by_default # aka "true"
+  end
+
+
+end

data/lib/generators/skinny_controller/USAGE

@@ -0,0 +1,5 @@
+Description:
+    Generates a controller with the given name, including SkinnyControllers::Diet
+
+Example:
+    `rails generate skinny_controller event_summaries`

data/lib/generators/skinny_controller/skinny_controller_generator.rb

@@ -0,0 +1,28 @@
+class SkinnyControllerGenerator < Rails::Generators::NamedBase
+  # gives us file_name
+  source_root File.expand_path('../templates', __FILE__)
+
+  def generate_layout
+    template 'skinny_controller.rb.erb', File.join('app/controllers', class_path, "#{file_name}_controller.rb")
+  end
+
+  def operation_name
+    file_name.camelize
+  end
+
+  def controller_name
+    operation_name.pluralize + 'Controller'
+  end
+
+  def parent_class
+    if defined?(::ApiController)
+      'ApiController'
+    elsif defined?(::APIController)
+      'APIController'
+    elsif defined?(::ApplicationController)
+      'ApplicationController'
+    else
+      'ActionController::Base'
+    end
+  end
+end

data/lib/generators/skinny_controller/templates/skinny_controller.rb.erb

@@ -0,0 +1,24 @@
+class <%= controller_name %> < <%= parent_class %>
+  include SkinnyControllers::Diet
+
+  def index
+    render json: model
+  end
+
+  def create
+    render json: model
+  end
+
+  def show
+    render json: model
+  end
+
+  def update
+    render json: model
+  end
+
+  def destroy
+    render json: model
+  end
+
+end

data/lib/skinny_controllers/operation/model_helpers.rb

@@ -50,7 +50,7 @@ module SkinnyControllers
 
       def model_param_name
         # model_key comes from Operation::Base
-        self.model_key || model_name.underscore
+        model_key || model_name.underscore
       end
 
       # @param [Hash] scoped_params
@@ -95,7 +95,7 @@ module SkinnyControllers
           association = association_name_from_object
           scoped.send(association)
         else
-          fail "Parent object of type #{scope[:type]} not accessible"
+          raise "Parent object of type #{scope[:type]} not accessible"
         end
       end
 

data/lib/skinny_controllers/version.rb

@@ -1,3 +1,3 @@
 module SkinnyControllers
-  VERSION = '0.7.4'
+  VERSION = '0.8.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skinny_controllers
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.8.0
 platform: ruby
 authors:
 - L. Preston Sego III
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-02 00:00:00.000000000 Z
+date: 2016-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -186,6 +186,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- lib/generators/operation/USAGE
+- lib/generators/operation/operation_generator.rb
+- lib/generators/operation/templates/operation.rb.erb
+- lib/generators/policy/USAGE
+- lib/generators/policy/policy_generator.rb
+- lib/generators/policy/templates/policy.rb.erb
+- lib/generators/skinny_controller/USAGE
+- lib/generators/skinny_controller/skinny_controller_generator.rb
+- lib/generators/skinny_controller/templates/skinny_controller.rb.erb
 - lib/skinny_controllers.rb
 - lib/skinny_controllers/default_verbs.rb
 - lib/skinny_controllers/diet.rb
@@ -225,5 +234,5 @@ rubyforge_project:
 rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
-summary: SkinnyControllers-0.7.4
+summary: SkinnyControllers-0.8.0
 test_files: []