api_presenter 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9e411385a8bd85df6bc3efe9f1ec418d5608f26f
-  data.tar.gz: a7da14574b9aabd4501edafd1555feb16246ff05
+SHA256:
+  metadata.gz: b9b45f72f53a0f0d6ddf34ba993ec0a6f5cbcd6fd7f2b8b2436d5963d2f50296
+  data.tar.gz: 48d1037e5b1af28c574b421996e9350e119fddc89024aeb7bbb7b059f9cec8e7
 SHA512:
-  metadata.gz: 810bfdd0b1932949b0d6984ac1b0935467de3e5d27858f05890b906447aa2124fc0beee23c0cf95a5d624df168a2e20eb2b38d567650c685e291a905724859a4
-  data.tar.gz: 29e3508ed61708ae44f7f4470e9687a0131d0e56a991b307ba1519ebd6b6755d92ff7903a26f7af6d25b6bd78d8f62b4a742332439d5b9b758f6bfc08e65f583
+  metadata.gz: 696d7eb80f9327f58f44ab02adfdc14da7a204fa4ae18ac360bde122f5953b55fc986cfa8489fa69c0f4372f3de1d525047512b3e4344b68e35fe3e1fb0f8c54
+  data.tar.gz: 1df07f9a061b26b111c00ce52b57a6f89911b914fd787e9e008254da9bf5d01c350ea29af57ea948dd5836b6e2723d979ab946053fd842fb973cbe6c574022e5

data/.travis.yml

@@ -1,4 +1,4 @@
 language: ruby
 rvm:
   - 2.2.2
-before_install: gem install bundler -v 1.10.3
+before_install: gem install bundler -v 2.2.12

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.4.1 (2016-11-10)
+
+Bug fix: include `ApplicationApiPresenter` in presenter lookup path.
+
+## 0.4.0 (2016-11-10)
+
+Adds presenter generator.
+
+## 0.3.0 (2016-11-09)
+
+Adds configuration options and generator.
+
 ## 0.2.4 (2016-11-07)
 
 Logical restructure. No API changes.

data/README.md

@@ -1,13 +1,11 @@
 # ApiPresenter
 
-A much longer readme is coming, including best practices and cautions, but in the meantime lets keep it simple...
+REST APIs provide a concise and conventional means of retrieving resources for a client. But in the real world, clients often have additional data requirements beyond the specifically requested resource(s):
 
-When creating RESTful APIs for web or mobile clients, there are a couple of desirable endpoint behaviors:
+1. Current user permissions for the returned records, so that the client can intelligently draw its UI (ex: edit/delete buttons).
+2. Associated data, to mitigate total number of requests (ex: return authors with posts).
 
-* Include permissions so that the client can intelligently draw its UI (ex: edit/delete buttons), while maintaining a single source of truth
-* Allow inclusion of associated data to mitigate total number of requests
-
-ApiPresenter does both of these things, plus a bit more.
+ApiPresenter provides both of these things, plus a bit more.
 
 ## Installation
 
@@ -27,7 +25,7 @@ Or install it yourself as:
 
 ## Usage
 
-We'll use a simple blog as the usage example for this gem. The blog has the following model structure:
+ApiPresenter is well suited to large, relational systems. We'll use a blog as the usage example for this gem. The blog has the following model structure:
 
 ```ruby
 class Category < ActiveRecord::Base
@@ -52,16 +50,22 @@ class User < ActiveRecord::Base
 end
 ```
 
+Usage examples will be in the context of requesting posts as the primary collection.
+
 ### 0. Generate config file
 
 `rails g api_presenter:config`
 
-Generates a configuration file that allows you to override the default querystring params used by the `presenter` concern. More to come.
+Generate your configuration file. Currently, ApiPresenter allows customization of querystring parameter names for including policies and associated resources (see below). More configuration options to come.
 
 ### 1. Create your Presenter
 
+Generate a presenter class for your ActiveRecord model. The generator will also ensure the presence of an `ApplicationApiPresenter` base class for centralized methods.
+
+`rails g api_presenter:presenter post`
+
 ```ruby
-class PostPresenter < ApiPresenter::Base
+class PostPresenter < ApplicationApiPresenter
   def associations_map
     {
       categories:     { associations: { sub_category: :category } },
@@ -80,21 +84,15 @@ class PostPresenter < ApiPresenter::Base
 end
 ```
 
-Presenters can define up to three methods:
+Presenters can define three opt-in methods:
 
-* `associations_map` The business-dictated includable resources for the ActiveRecord model (`Post`, in this case). Consists of the model name as key and traversal required to preload/load them. In most cases, the value of `associations` will correspond directly to associations on the primary model.
+* `associations_map` Associated resources that you would like to be includable with the primary collection. Consists of the model name as key and the traversal required to preload/load them. In most cases, the value of `associations` will correspond directly to associations on the primary model.
 * `policy_methods` A list of Pundit policy methods to resolve for the primary collection if policies are requested.
-* `policy_associations` Additional records to preload in order to optimize policies that must traverse asscoiations.
+* `policy_associations` Additional associations to preload in order to optimize policies that must traverse asscoiations.
 
 ### 2. Enable your controllers
 
-Your presentable collection can be an `ActiveRecord::Relation`, an array of records, or even a single record. Just call `present` on it from your controller action. The preloads will be performed, and the included collections/policies will be available in the `@presenter` instance variable.
-
-The following querystring params are used by the supplied controller concern's `present` method:
-
-* `count [Boolean]` Pass true if you just want a count of the primary collection
-* `policies [Boolean]` Pass true if you want to resolve policies for the primary collection records
-* `include [String, Array]` A comma-delimited list or array of collection names (camelCase or under_scored) to include with the primary collection
+Include the supplied controller concern at your `ApplicationController` level, or on a specific controller. This concern provides the `present` method, which can be called on an `ActiveRecord::Relation`, an array of records, or even a single record (preloading of associated collections is only performed for relations).
 
 ```ruby
 class ApplicationController
@@ -107,6 +105,7 @@ class PostsController < ApplicationController
   #   GET /posts?include=categories,subCategories,users&policies=true
   #
   def index
+    authorize Post
     posts = PostQuery.records(current_user, params)
     present posts
   end
@@ -115,23 +114,32 @@ class PostsController < ApplicationController
   #   GET /posts/:id?include=categories,subCategories,users&policies=true
   #
   def show
-    post = Post.find(params[:id])
-    present post
+    @post = Post.find(params[:id])
+    authorize @post
+    present @post
   end
 end
 ```
 
+Controller params are used to tell the presenter what to load. The default param keys are `count`, `policies`, and `include`:
+
+* `count [Boolean]` Pass true if you just want a count of the primary collection.
+* `policies [Boolean]` Pass true if you want to resolve policies for the primary collection.
+* `include [String, Array]` A comma-delimited list or array of collection names (camelCase or under_scored) to include with the primary collection.
+
 ### 3. Render the result
 
-How you ultimately render the primary collection and the data produced by ApiPresenter is up to you. `@presenter` has the following properties:
+After calling the `present` method in a controller action, you access your processed collection through the `@presenter` instance variable. How you ultimately render the data produced by ApiPresenter is up to you.
 
-* `collection` The primary collection that was passed into the presenter.
-* `total_count` When using Kaminari or another pagination method that defines a `total_count` property, returns unpaginated count. If the primary collection is not an `ActiveRecord::Relation`, simply returns the number of records.
-* `included_collection_names` Convenience method that returns an array of included collecton model names.
-* `included_collections` A hash of included collections, consisting of the model name and corresponding records.
-* `policies` An array of resolved policies for the primary collection.
+`@presenter` has the following properties:
 
-Here's an example of how you might render this using JBduiler:
+* `collection [Array<ActiveRecord::Base>]` The primary collection that was passed into the presenter. Empty if count requested.
+* `total_count [Integer]` When using Kaminari or another pagination method that defines a `total_count` property, returns unpaginated count. If the primary collection is not an `ActiveRecord::Relation`, simply returns the number of records.
+* `included_collection_names [Array<Symbol>]` Convenience method that returns an array of included collection model names.
+* `included_collections [Hash]` A hash of included collections, consisting of the model name and corresponding records.
+* `policies [Array<Hash>]` An array of resolved policies for the primary collection.
+
+Here's an example of how you might render your data using JBduiler:
 
 ### api/posts/index.json.jbuilder
 
@@ -168,7 +176,7 @@ end
 
 ### 4. Output
 
-Using the code above, our call to `GET /posts` would result in the following JSON:
+Using the code above, our call to `GET /posts?include=categories,subCategories,users&policies=true` would result in the following JSON:
 
 ```json
 {
@@ -198,7 +206,7 @@ Using the code above, our call to `GET /posts` would result in the following JSO
 }
 ```
 
-And similarily, for `GET /posts/1`:
+And similarily, for `GET /posts/1?include=categories,subCategories,users&policies=true`:
 
 ```json
 {
@@ -226,12 +234,12 @@ And similarily, for `GET /posts/1`:
 
 ### Conditional includes
 
-There are a number of ways you can conditionally include resources, depending, for insatnce, on user type.
+There are a number of ways you can conditionally include resources, depending, for instance, on user type.
 
 #### Add conditions inside `associations_map` method
 
 ```ruby
-class PostPresenter < ApiPresenter::Base
+class PostPresenter < ApiApplicationPresenter
   def associations_map
     current_user.admin? ? admin_associations_map : user_associations_map
   end
@@ -257,7 +265,7 @@ end
 
 #### Use `condition` property within `association_map` definition
 
-Via inline string:
+##### Via inline string
 
 ```ruby
 class PostPresenter < ApiPresenter::Base
@@ -271,7 +279,7 @@ class PostPresenter < ApiPresenter::Base
 end
 ```
 
-Via method call:
+##### Via method call
 
 ```ruby
 class PostPresenter < ApiPresenter::Base
@@ -303,12 +311,10 @@ end
 
 ## TODO
 
-* More doc
 * Decouple from Pundit
 * Make index policy checking on includes optional
 * Allow custom collection names
 * Add test helper to assert presenter was called for a given controller action
-* Add presenter generator
 
 ## Development
 
@@ -318,7 +324,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/api_presenter.
+Bug reports and pull requests are welcome on GitHub at https://github.com/uberllama/api_presenter.
 
 
 ## License

data/api_presenter.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "activesupport", ">= 3.0.0"
   spec.add_dependency "pundit"
   spec.add_development_dependency "activerecord", ">= 4.2.3"
-  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "bundler", "~> 2.2.12"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "sqlite3"

data/lib/api_presenter/base.rb

@@ -14,8 +14,8 @@ module ApiPresenter
     #
     # @return [ApiPresenter::Base]
     #
-    def self.call(**kwargs)
-      new(kwargs).call
+    def self.call(current_user: nil, relation:, params: {})
+      new(current_user: current_user, relation: relation, params: params).call
     end
 
     # @param current_user [User]                          Optional. current_user context.

data/lib/api_presenter/concerns/presentable.rb

@@ -55,6 +55,7 @@ module ApiPresenter
       def presenter_klass(klass)
         "#{klass.name}Presenter".safe_constantize ||
         "#{klass.base_class.name}Presenter".safe_constantize ||
+        "ApplicationApiPresenter".safe_constantize ||
         ApiPresenter::Base
       end
 

data/lib/api_presenter/version.rb

@@ -1,3 +1,3 @@
 module ApiPresenter
-  VERSION = "0.3.0"
+  VERSION = "1.0.0"
 end

data/lib/generators/api_presenter/config/USAGE

@@ -1 +1,8 @@
-Creates configuration file
+Description:
+    Generates configuration filee.
+
+Example:
+    rails generate api_presenter:config
+
+    This will create:
+        config/initializers/api_presenter.rb

data/lib/generators/api_presenter/config/config_generator.rb

@@ -4,7 +4,7 @@ module ApiPresenter
       source_root File.expand_path('../templates', __FILE__)
 
       def copy_config_file
-        copy_file 'api_presenter_config.rb', 'config/initializers/api_presenter_config.rb'
+        copy_file('config.rb', 'config/initializers/api_presenter.rb')
       end
     end
   end

data/lib/generators/api_presenter/presenter/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Generates an API presenter for an ActiveRecord model with the given name, and a base class ApplicationApiPresenter unless already exists.
+
+Example:
+    rails generate api_presenter:presenter post
+
+    This will create:
+      app/presenters/application_api_presenter.rb
+      app/presenters/post_presenter.rb

data/lib/generators/api_presenter/presenter/presenter_generator.rb

@@ -0,0 +1,17 @@
+module ApiPresenter
+  module Generators
+    class PresenterGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+
+      def create_application_presenter
+        unless File.exist?('app/presenters/application_api_presenter.rb')
+          copy_file('application_presenter.rb', 'app/presenters/application_api_presenter.rb')
+        end
+      end
+
+      def create_presenter
+        template('presenter.rb', File.join('app/presenters', class_path, "#{file_name}_presenter.rb"))
+      end
+    end
+  end
+end

data/lib/generators/api_presenter/presenter/templates/application_presenter.rb

@@ -0,0 +1,2 @@
+class ApplicationApiPresenter < ApiPresenter::Base
+end

data/lib/generators/api_presenter/presenter/templates/presenter.rb

@@ -0,0 +1,13 @@
+class <%= class_name %>Presenter < ApplicationApiPresenter
+  def associations_map
+    {}
+  end
+
+  def policy_methods
+    []
+  end
+
+  def policy_associations
+    []
+  end
+end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: api_presenter
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Yuval Kordov
 - Little Blimp
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2016-11-09 00:00:00.000000000 Z
+date: 2022-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -59,14 +59,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: 2.2.12
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: 2.2.12
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -139,12 +139,16 @@ files:
 - lib/api_presenter/version.rb
 - lib/generators/api_presenter/config/USAGE
 - lib/generators/api_presenter/config/config_generator.rb
-- lib/generators/api_presenter/config/templates/api_presenter_config.rb
+- lib/generators/api_presenter/config/templates/config.rb
+- lib/generators/api_presenter/presenter/USAGE
+- lib/generators/api_presenter/presenter/presenter_generator.rb
+- lib/generators/api_presenter/presenter/templates/application_presenter.rb
+- lib/generators/api_presenter/presenter/templates/presenter.rb
 homepage: http://github.com/uberllama/api_presenter
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -159,9 +163,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.6
-signing_key: 
+rubygems_version: 3.0.9
+signing_key:
 specification_version: 4
 summary: Return associations and policies with API responses
 test_files: []