garden_variety 2.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b80f333fab73447d743d99ef4cd170a997011a8e
-  data.tar.gz: ab23ee38fd1a658f8fa7a82eeac8708110346bb4
+SHA256:
+  metadata.gz: dd6dd125edefcf640a8a2aa1b629510eb3e5526551abfea71738b661c9fe1d83
+  data.tar.gz: ec5a4e29f8e1937dd74a88d11fdf087394a95cf67c56ceca177e9ce5fb9ae89e
 SHA512:
-  metadata.gz: 1a36d05543168c2739e1b2677aa4b870c534ca4a5fc340a80ae80f18e920b238c59017179cd16e5824f2bce62ac36db3ca73a4c80f98a5e8f61381de597ef336
-  data.tar.gz: a93377a1e7c252f6ad547febe70bdaedc83a62383819e04766bda20b604f5db055571d17fa7d56b5a4680eccb0d124bf54d5171787a5a1858cdb472b80cbc58f
+  metadata.gz: bd41cf0735bfabe753a7bb4b5138d76a5e9c572952d5d4fb344f344dfe44926258c1a64ffe67b66875fcae5b09d9640fb8dfb8ce742a812bcbb0cfcad80b0d21
+  data.tar.gz: ba7d049d2952075c9a431dbd76b9ced59abc89918dfdbe589a7e8e183654a769669e6396e6e4546984bddf2057e7164a7f921ee849dacdee59c1f2d1ead39177

data/README.md

@@ -2,16 +2,15 @@
 
 Delightfully boring Rails controllers.  One of the superb advantages of
 Ruby on Rails is convention over configuration.  Opinionated default
-behavior can decrease development time, and increase application
+behavior can decrease development time and increase application
 robustness (less custom code == less that can go wrong).  In service of
 this principle, *garden_variety* provides reasonable default controller
 actions, with care to allow easy override.
 
-*garden_variety* also uses the excellent
-[Pundit](https://rubygems.org/gems/pundit) gem to isolate authorization
-concerns.  If you're unfamiliar with Pundit, see its documentation for
-an explanation of policy objects and how they help controller actions
-stay DRY and boring.
+*garden_variety* also relies on the [Pundit](https://rubygems.org/gems/pundit)
+gem to isolate authorization concerns.  If you're unfamiliar with
+Pundit, see its documentation for an explanation of policy objects and
+how they help controller actions stay DRY and boring.
 
 As an example, this controller using `garden_variety`...
 
@@ -27,29 +26,26 @@ end
 class PostsController < ApplicationController
 
   def index
-    authorize(resource_class)
-    self.resources = policy_scope(list_resources)
+    authorize(self.class.model_class)
+    self.collection = policy_scope(find_collection)
   end
 
   def show
-    self.resource = find_resource
-    authorize(resource)
+    self.model = authorize(find_model)
   end
 
   def new
-    if params.key?(resource_class.model_name.param_key)
-      self.resource = vest(new_resource)
-    else
-      self.resource = new_resource
-      authorize(resource)
+    self.model = authorize(new_model)
+    if params.key?(self.class.model_class.model_name.param_key)
+      assign_attributes(model)
     end
   end
 
   def create
-    self.resource = vest(new_resource)
-    if resource.save
+    self.model = assign_attributes(authorize(new_model))
+    if model.save
       flash[:success] = flash_message(:success)
-      redirect_to resource
+      redirect_to model
     else
       flash.now[:error] = flash_message(:error)
       render :new
@@ -57,15 +53,14 @@ class PostsController < ApplicationController
   end
 
   def edit
-    self.resource = find_resource
-    authorize(resource)
+    self.model = authorize(find_model)
   end
 
   def update
-    self.resource = vest(find_resource)
-    if resource.save
+    self.model = assign_attributes(authorize(find_model))
+    if model.save
       flash[:success] = flash_message(:success)
-      redirect_to resource
+      redirect_to model
     else
       flash.now[:error] = flash_message(:error)
       render :edit
@@ -73,9 +68,8 @@ class PostsController < ApplicationController
   end
 
   def destroy
-    self.resource = find_resource
-    authorize(resource)
-    if resource.destroy
+    self.model = authorize(find_model)
+    if model.destroy
       flash[:success] = flash_message(:success)
       redirect_to action: :index
     else
@@ -86,80 +80,82 @@ class PostsController < ApplicationController
 
   private
 
-  def resource_class
+  def self.model_class
     Post
   end
 
-  def resources
+  def collection
     @posts
   end
 
-  def resources=(models)
+  def collection=(models)
     @posts = models
   end
 
-  def resource
+  def model
     @post
   end
 
-  def resource=(model)
+  def model=(model)
     @post = model
   end
 
-  def list_resources
-    resource_class.all
+  def find_collection
+    self.class.model_class.all
   end
 
-  def find_resource
-    resource_class.find(params[:id])
+  def find_model
+    self.class.model_class.find(params[:id])
   end
 
-  def new_resource
-    resource_class.new
+  def new_model
+    self.class.model_class.new
   end
 
-  def vest(model)
-    authorize(model)
+  def assign_attributes(model)
     model.assign_attributes(permitted_attributes(model))
     model
   end
 
   def flash_options
-    { resource_name: "post", resource_capitalized: "Post" }
+    { model_name: "Post" }
   end
 
   def flash_message(status)
     keys = [
-      :"posts.#{action_name}.#{status}",
-      :"posts.#{action_name}.#{status}_html",
-      :"#{action_name}.#{status}",
-      :"#{action_name}.#{status}_html",
-      :"#{status}",
-      :"#{status}_html",
+      :"flash.posts.#{action_name}.#{status}",
+      :"flash.posts.#{action_name}.#{status}_html",
+      :"flash.#{action_name}.#{status}",
+      :"flash.#{action_name}.#{status}_html",
+      :"flash.#{status}",
+      :"flash.#{status}_html",
     ]
-    helpers.translate(keys.first, default: keys.drop(1), **flash_options)
+    helpers.translate(keys.first, { default: keys.drop(1), **flash_options })
   end
 
 end
 ```
 
-The implementations of the `resource_class` and `resource` / `resources`
-accessor methods are generated based on the controller name.  They can
-be altered with an optional argument to the `garden_variety` macro.  The
-rest of the methods can be overridden as normal, a la carte.  For a
-detailed description of method behavior, see the
-[full documentation](http://www.rubydoc.info/gems/garden_variety/).
-(Note that the `authorize`, `policy_scope`, and `permitted_attributes`
-methods are provided by Pundit.)
+The `::model_class` method returns a class corresponding to the
+controller name, by default.  That value can be overridden using the
+matching `::model_class=` setter.  The `model` / `collection` accessor
+method definitions are dictated by `::model_class`.  The rest of the
+methods can be overridden as normal, a la carte.  For a detailed
+description of method behavior, see the [API documentation](
+https://www.rubydoc.info/gems/garden_variety/).  (Note that the
+`authorize`, `policy_scope`, and `permitted_attributes` methods are
+provided by Pundit.)
 
 
 ## Scaffold generator
 
-*garden_variety* includes a scaffold generator similar to the Rails
-scaffold generator:
+*garden_variety* includes a `garden:scaffold` generator similar to the
+Rails `scaffold` generator:
 
 ```
 $ rails generate garden:scaffold post title:string body:text published:boolean
+       exist  config/locales
+      create  config/locales/flash.en.yml
     generate  resource
       invoke  active_record
       create    db/migrate/19991231235959_create_posts.rb
@@ -176,11 +172,6 @@ $ rails generate garden:scaffold post title:string body:text published:boolean
       invoke    helper
       create      app/helpers/posts_helper.rb
       invoke      test_unit
-      invoke    assets
-      invoke      coffee
-      create        app/assets/javascripts/posts.coffee
-      invoke      scss
-      create        app/assets/stylesheets/posts.scss
       invoke  resource_route
        route    resources :posts
     generate  erb:scaffold
@@ -190,6 +181,7 @@ $ rails generate garden:scaffold post title:string body:text published:boolean
       create  app/views/posts/show.html.erb
       create  app/views/posts/new.html.erb
       create  app/views/posts/_form.html.erb
+      create  app/views/posts/_post.html.erb
       insert  app/controllers/posts_controller.rb
     generate  pundit:policy
       create  app/policies/post_policy.rb
@@ -206,14 +198,23 @@ generator in a few small ways:
 * No jbuilder templates.  Only HTML templates are generated.
 * `rails generate pundit:policy` is invoked for the specified model.
 
+Additionally, if you are using the [talent_scout] gem, the scaffold
+generator will invoke `rails generate talent_scout:search` for the
+specified model.  This behavior can be disabled with the
+`--skip-talent-scout` option.  For more information about integrating
+with *talent_scout*, see the [Searching with talent_scout](
+#searching-with-talent_scout) section below.
+
+[talent_scout]: https://rubygems.org/gems/talent_scout
+
 
 ## Flash messages
 
 Flash messages are defined using I18n.  The *garden_variety* installer
 (`rails generate garden:install`) will create a
-"config/locales/garden_variety.en.yml" file containing default "success"
-and "error" messages.  You can edit this file to customize those
-messages, or add your own translation files to support other languages.
+"config/locales/flash.en.yml" file containing default "success" and
+"error" messages.  You can edit this file to customize those messages,
+or add your own translation files to support other languages.
 
 As seen in the `PostsController#flash_message` method in the example
 above, a prioritized list of keys are tried when retrieving a flash
@@ -226,12 +227,11 @@ Internationalization guide for more information.)
 
 Interpolation in flash messages is also supported (as described by
 [Passing Variables to Translations]), with interpolation values provided
-by the `flash_options` method.  By default, `flash_options` provides
-`resource_name` and `resource_capitalized` values, but you can override
-it to provide your own values.
+by the `flash_options` method.  By default, `flash_options` provides a
+`model_name` value, but you can override it to provide your own values.
 
-[Safe HTML Translations]: http://guides.rubyonrails.org/i18n.html#using-safe-html-translations
-[Passing Variables to Translations]: http://guides.rubyonrails.org/i18n.html#passing-variables-to-translations
+[Safe HTML Translations]: https://guides.rubyonrails.org/i18n.html#using-safe-html-translations
+[Passing Variables to Translations]: https://guides.rubyonrails.org/i18n.html#passing-variables-to-translations
 
 
 ## Beyond garden variety behavior
@@ -240,46 +240,105 @@ it to provide your own values.
 written, including in situations where custom code is unavoidable.
 
 
-### Integrating with pagination
+### Eliminating N+1 queries
+
+With proper Russian doll caching, [N+1 queries can be a feature](
+https://youtu.be/ktZLpjCanvg?t=4m27s).  But, if you need to eliminate
+an N+1 query by using eager loading, you can override the
+`find_collection` method:
+
+```ruby
+class PostsController < ApplicationController
+  garden_variety
+
+  def find_collection
+    super.includes(:author)
+  end
+end
+```
+
 
-You can integrate your your favorite pagination gem (*may I suggest
-[foliate](https://rubygems.org/gems/foliate)?*) by overriding the
-`list_resources` method:
+### Pagination
+
+You can integrate your favorite pagination gem (*may I suggest
+[moar](https://rubygems.org/gems/moar)?*) by overriding the
+`find_collection` method:
 
 ```ruby
 class PostsController < ApplicationController
   garden_variety
 
-  def list_resources
-    paginate(super)
+  def find_collection
+    moar(super.order(:created_at))
   end
 end
 ```
 
 
-### Integrating with search
+### Searching
 
-You can also integrate search functionality by overriding the
-`list_resources` method:
+You can provide search functionality by overriding the `find_collection`
+method:
 
 ```ruby
 class PostsController < ApplicationController
   garden_variety
 
-  def list_resources
-    params[:author] ? super.where(author: params[:author]) : super
+  def find_collection
+    params[:title] ? super.where("title LIKE ?", "%#{params[:title]}%") : super
   end
 end
 ```
 
+#### Searching with talent_scout
+
+If you are using the [talent_scout] gem, the default implementation of
+`find_collection` will automatically instantiate your model search class
+-- no custom code required.  For example, if a `PostSearch` class is
+defined, `PostsController#find_collection` will be equivalent to:
+
+```ruby
+def find_collection
+  @search = PostSearch.new(params[:q])
+  @search.results
+end
+```
+
+Notice, as a side effect, the `@search` instance variable is set for
+later use in the view.
 
-### Integrating with SJR
+The model search class will be chosen based on the controller's
+`::model_class`.  For example:
 
-Server-generated JavaScript Response (SJR) controller actions are
-generally the same as conventional controller actions, with one
-difference: non-GET SJR actions render instead of redirect on success.
-*garden_variety* provides a concise syntax for overriding only
-on-success behavior of non-GET actions:
+```ruby
+class MyPostsController < ApplicationController
+  garden_variety
+
+  self.model_class = Post # find_collection will use PostSearch instead of MyPostSearch
+end
+```
+
+If a corresponding model search class is not defined, `find_collection`
+will fall back to its original non-search behavior.
+
+Alternatively, you can override the model search class directly:
+
+```ruby
+class MyPostsController < ApplicationController
+  garden_variety
+
+  self.model_class = Post
+  self.model_search_class = MyPostSearch # find_collection will use MyPostSearch
+end
+```
+
+
+### Server-generated JavaScript Responses (SJR)
+
+SJR controller actions are generally the same as conventional controller
+actions, with one difference: non-GET SJR actions render instead of
+redirect on success.  *garden_variety* provides a concise syntax for
+overriding only the on-success behavior of non-GET actions:
 
 ```ruby
 class PostsController < ApplicationController
@@ -323,7 +382,7 @@ messages.  If a redirect is replaced with a render, the flash message
 will be set such that it does not affect the next request.
 
 
-### Integrating with authentication
+### Authentication
 
 The details of integrating authentication will depend on your chosen
 authentication library.  [Devise](https://rubygems.org/gems/devise) is
@@ -359,7 +418,7 @@ this conflict, add the following line to your Clearance initializer:
 ```
 
 
-### Integrating with Form Objects
+### Form Objects
 
 The Form Object pattern is used to mitigate the complexity of handling
 forms which need special processing logic, such as context-dependent
@@ -399,10 +458,10 @@ end
 In this example, only the `new` and `create` actions are generated by
 the `garden_variety` macro.  The on-success behavior of `create` is
 overridden to redirect to `root_path`, using the concise syntax
-discussed in the [Integrating with SJR](#integrating-with-sjr) example.
-The *garden_variety* controller helper methods all work as expected
-because `RegistrationForm` responds to `assign_attributes` and `save`,
-and has a default (nullary) constructor.
+discussed in the [Server-generated JavaScript Responses (SJR)](#server-generated-javascript-responses-sjr)
+example.  The *garden_variety* controller helper methods all work as
+expected because `RegistrationForm` responds to `assign_attributes` and
+`save`, and has a default (nullary) constructor.
 
 
 ### Non-REST actions
@@ -430,20 +489,21 @@ end
 
 ```ruby
 class PublishedPostsController < ApplicationController
-  garden_variety :index, resources: :posts
+  self.model_class = Post
+  garden_variety :index
 
-  def list_resources
+  def find_collection
     super.where(published: true)
   end
 end
 ```
 
-Note the `resources:` argument to the `garden_variety` macro.  The
-resource class for `PublishedPostsController` will be overridden as
-`Post` instead of derived as `PublishedPost`.  Likewise, the `@posts`
-instance variable will be used instead of `@published_posts`.
+Notice the call to `::model_class=`.  The model class for
+`PublishedPostsController` is overridden as `Post` instead of derived as
+`PublishedPost`.  And because of this override, the `@posts` instance
+variable will be used instead of `@published_posts`.
 
-This example may be somewhat contrived, but there is an excellent talk
+This example may be somewhat contrived, but here is an excellent talk
 from RailsConf which delves deeper into the principle:
 [In Relentless Pursuit of REST](https://www.youtube.com/watch?v=HctYHe-YjnE)
 ([slides](https://speakerdeck.com/derekprior/in-relentless-pursuit-of-rest)).
@@ -451,19 +511,13 @@ from RailsConf which delves deeper into the principle:
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem "garden_variety"
-```
-
-Then execute:
+Add the gem to your Gemfile:
 
 ```bash
-$ bundle install
+$ bundle add garden_variety
 ```
 
-And finally, run the *garden_variety* install generator:
+And run the install generator:
 
 ```bash
 $ rails generate garden:install
@@ -474,9 +528,9 @@ This will also run the Pundit install generator, if necessary.
 
 ## Contributing
 
-Run `rake test` to run the tests.
+Run `bin/test` to run the tests.
 
 
 ## License
 
-[MIT License](https://opensource.org/licenses/MIT)
+[MIT License](MIT-LICENSE)

data/Rakefile

@@ -1,29 +1,3 @@
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
-
-require 'yard'
-
-YARD::Rake::YardocTask.new(:doc) do |t|
-end
-
-
-
-
-
-
+require 'bundler/setup'
 
 require 'bundler/gem_tasks'
-
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
-end
-
-
-task default: :test

data/lib/garden_variety/actions.rb

@@ -1,13 +1,13 @@
 module GardenVariety
 
-  REDIRECT_CODES = [301, 302, 303, 307, 308]
+  REDIRECT_CODES = [301, 302, 303, 307, 308].to_set
 
   module IndexAction
     # Garden variety controller +index+ action.
     # @return [void]
     def index
-      authorize(resource_class)
-      self.resources = policy_scope(list_resources)
+      authorize(self.class.model_class)
+      self.collection = policy_scope(find_collection)
     end
   end
 
@@ -15,8 +15,7 @@ module GardenVariety
     # Garden variety controller +show+ action.
     # @return [void]
     def show
-      self.resource = find_resource
-      authorize(resource)
+      self.model = authorize(find_model)
     end
   end
 
@@ -24,12 +23,8 @@ module GardenVariety
     # Garden variety controller +new+ action.
     # @return [void]
     def new
-      if params.key?(resource_class.model_name.param_key)
-        self.resource = vest(new_resource)
-      else
-        self.resource = new_resource
-        authorize(resource)
-      end
+      self.model = (model = authorize(new_model))
+      assign_attributes(model) if params.key?(self.class.model_name.param_key)
     end
   end
 
@@ -40,10 +35,10 @@ module GardenVariety
     #   @yield on-success callback, replaces default redirect
     # @return [void]
     def create
-      self.resource = vest(new_resource)
-      if resource.save
+      self.model = (model = assign_attributes(authorize(new_model)))
+      if model.save
         flash[:success] = flash_message(:success)
-        block_given? ? yield : redirect_to(resource)
+        block_given? ? yield : redirect_to(model)
         flash.discard(:success) if REDIRECT_CODES.exclude?(response.status)
       else
         flash.now[:error] = flash_message(:error)
@@ -56,8 +51,7 @@ module GardenVariety
     # Garden variety controller +edit+ action.
     # @return [void]
     def edit
-      self.resource = find_resource
-      authorize(resource)
+      self.model = authorize(find_model)
     end
   end
 
@@ -68,10 +62,10 @@ module GardenVariety
     #   @yield on-success callback, replaces default redirect
     # @return [void]
     def update
-      self.resource = vest(find_resource)
-      if resource.save
+      self.model = (model = assign_attributes(authorize(find_model)))
+      if model.save
         flash[:success] = flash_message(:success)
-        block_given? ? yield : redirect_to(resource)
+        block_given? ? yield : redirect_to(model)
         flash.discard(:success) if REDIRECT_CODES.exclude?(response.status)
       else
         flash.now[:error] = flash_message(:error)
@@ -87,9 +81,8 @@ module GardenVariety
     #   @yield on-success callback, replaces default redirect
     # @return [void]
     def destroy
-      self.resource = find_resource
-      authorize(resource)
-      if resource.destroy
+      self.model = (model = authorize(find_model))
+      if model.destroy
         flash[:success] = flash_message(:success)
         block_given? ? yield : redirect_to(action: :index)
         flash.discard(:success) if REDIRECT_CODES.exclude?(response.status)
@@ -101,8 +94,8 @@ module GardenVariety
   end
 
   # Map of controller action name to action module.  Used by the
-  # {GardenVariety::Controller::ClassMethods#garden_variety} macro to
-  # include desired controller actions.
+  # {GardenVariety::Controller::ClassMethods#garden_variety
+  # garden_variety} macro to include desired controller actions.
   ACTION_MODULES = {
     index: IndexAction,
     show: ShowAction,