garden_variety 1.2 → 2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c633defda33a2f8bcd26d96f58c1bfea52c2fb9c
-  data.tar.gz: 988988d42d10f00c3f55d5690b39ec46710ed68a
+  metadata.gz: b80f333fab73447d743d99ef4cd170a997011a8e
+  data.tar.gz: ab23ee38fd1a658f8fa7a82eeac8708110346bb4
 SHA512:
-  metadata.gz: 8eee6bea8231197d118f405c320a58af2a4d73c08f2ce65ad3373142afdf895585ce528397be97640e4cabb3631c9652c1dd58c84e1dec162f732bf558aa96c1
-  data.tar.gz: 643ca6a75d537943723a1ee4fb27af838bd666dd787c08e7dea53898282201fa735be86de7acebf4f4f9a5791482a508b83919573ec3943068c30291802dad87
+  metadata.gz: 1a36d05543168c2739e1b2677aa4b870c534ca4a5fc340a80ae80f18e920b238c59017179cd16e5824f2bce62ac36db3ca73a4c80f98a5e8f61381de597ef336
+  data.tar.gz: a93377a1e7c252f6ad547febe70bdaedc83a62383819e04766bda20b604f5db055571d17fa7d56b5a4680eccb0d124bf54d5171787a5a1858cdb472b80cbc58f

data/README.md

@@ -48,8 +48,10 @@ class PostsController < ApplicationController
   def create
     self.resource = vest(new_resource)
     if resource.save
+      flash[:success] = flash_message(:success)
       redirect_to resource
     else
+      flash.now[:error] = flash_message(:error)
       render :new
     end
   end
@@ -62,8 +64,10 @@ class PostsController < ApplicationController
   def update
     self.resource = vest(find_resource)
     if resource.save
+      flash[:success] = flash_message(:success)
       redirect_to resource
     else
+      flash.now[:error] = flash_message(:error)
       render :edit
     end
   end
@@ -71,8 +75,13 @@ class PostsController < ApplicationController
   def destroy
     self.resource = find_resource
     authorize(resource)
-    resource.destroy!
-    redirect_to action: :index
+    if resource.destroy
+      flash[:success] = flash_message(:success)
+      redirect_to action: :index
+    else
+      flash.now[:error] = flash_message(:error)
+      render :show
+    end
   end
 
   private
@@ -115,6 +124,22 @@ class PostsController < ApplicationController
     model
   end
 
+  def flash_options
+    { resource_name: "post", resource_capitalized: "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",
+    ]
+    helpers.translate(keys.first, default: keys.drop(1), **flash_options)
+  end
+
 end
 ```
 
@@ -182,17 +207,60 @@ generator in a few small ways:
 * `rails generate pundit:policy` is invoked for the specified model.
 
 
+## 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.
+
+As seen in the `PostsController#flash_message` method in the example
+above, a prioritized list of keys are tried when retrieving a flash
+message.  Keys specific to the controller are tried first, followed by
+keys specific to the action, and then finally generic status keys.  For
+each level of specificity, `*_html` key variants are supported, which
+allow raw HTML to be included in flash messages and not be escaped when
+rendered.  (See the [Safe HTML Translations] section of the Rails
+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.
+
+[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
+
+
 ## Beyond garden variety behavior
 
 *garden_variety* is designed to reduce the amount of custom code
 written, including in situations where custom code is unavoidable.
 
 
+### Integrating with pagination
+
+You can integrate your your favorite pagination gem (*may I suggest
+[foliate](https://rubygems.org/gems/foliate)?*) by overriding the
+`list_resources` method:
+
+```ruby
+class PostsController < ApplicationController
+  garden_variety
+
+  def list_resources
+    paginate(super)
+  end
+end
+```
+
+
 ### Integrating with search
 
-It is possible to integrate searching functionality by overriding the
-`index` action.  However, it can be simpler to override the
-`list_resources` method instead:
+You can also integrate search functionality by overriding the
+`list_resources` method:
 
 ```ruby
 class PostsController < ApplicationController
@@ -205,22 +273,55 @@ end
 ```
 
 
-### Integrating with pagination
+### Integrating with SJR
 
-Your favorite pagination gem (*may I suggest
-[foliate](https://rubygems.org/gems/foliate)?*) can also be integrated
-by overriding the `list_resources` action:
+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 PostsController < ApplicationController
   garden_variety
 
-  def list_resources
-    paginate(super)
+  def create
+    super{ render plain: "text" } # renders text on success instead of redirect
+  end
+end
+```
+
+Thus, combining this syntax with Rails' default rendering convention:
+
+```ruby
+class PostsController < ApplicationController
+  garden_variety
+
+  def create
+    respond_to do |format|
+      format.js{ super{} } # renders "app/views/posts/create.js.erb" on success
+    end
   end
+
+  def update
+    respond_to do |format|
+      format.js{ super{} } # renders "app/views/posts/update.js.erb" on success
+    end
+  end
+
+  def destroy
+    respond_to do |format|
+      format.js{ super{} } # renders "app/views/posts/destroy.js.erb" on success
+    end
+  end
+
 end
 ```
 
+**Sidenote:** *garden_variety* automatically manages the life of flash
+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
 
@@ -287,58 +388,32 @@ end
 
 
 class RegistrationFormsController < ApplicationController
-  garden_variety :new
+  garden_variety :new, :create # only generate #new and #create actions
 
   def create
-    self.resource = vest(new_resource)
-    if resource.save
-      redirect_to root_path # redirect to front page instead of show
-    else
-      render :new
-    end
+    super{ redirect_to root_path } # redirect to home page on success
   end
 end
 ```
 
-Only the `new` controller action is generated by the `garden_variety`
-macro.  The `create` action is implemented directly in order to redirect
-to `root_path` rather than the resource itself, as would be
-conventional.  The *garden_variety* helper methods all work as expected
+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.
 
-This pattern of overriding a controller action merely to respond
-differently upon success is common enough that *garden_variety* provides
-a concise syntax for it:
-
-```ruby
-class RegistrationFormsController < ApplicationController
-  garden_variety :new, :create
-
-  def create
-    super{ redirect_to root_path }
-  end
-end
-```
-
-In the above example, the `garden_variety` macro generates a
-conventional `create` action, which is then invoked via `super` in the
-`create` override.  Here, when a block is passed to `super`, it is
-treated as an on-success callback which replaces the default redirect.
-This callback behavior is also available for the `update` and `destroy`
-actions.
-
 
 ### Non-REST actions
 
 You may also define any non-REST controller actions you wish (i.e.
 actions other than: `index`, `show`, `new`, `create`, `edit`, `update`,
-and `destroy`).  The helper methods *garden_variety* provides may be
-useful when doing so.
-
-However, before implementing a non-REST controller action, consider if
-the behavior might be better implemented as a REST action in a new
-controller.  For example, instead of the following `published` action...
+and `destroy`).  The controller helper methods *garden_variety* provides
+may be useful when doing so.  However, before implementing a non-REST
+controller action, consider if the behavior might be better implemented
+as a REST action in a new controller.  For example, instead of the
+following `published` action...
 
 ```ruby
 class PostsController < ApplicationController
@@ -388,13 +463,14 @@ Then execute:
 $ bundle install
 ```
 
-And finally, if you haven't already used and installed Pundit, run the
-Pundit installation generator:
+And finally, run the *garden_variety* install generator:
 
 ```bash
-$ rails generate pundit:install
+$ rails generate garden:install
 ```
 
+This will also run the Pundit install generator, if necessary.
+
 
 ## Contributing
 

data/lib/garden_variety/actions.rb

@@ -1,5 +1,7 @@
 module GardenVariety
 
+  REDIRECT_CODES = [301, 302, 303, 307, 308]
+
   module IndexAction
     # Garden variety controller +index+ action.
     # @return [void]
@@ -40,8 +42,11 @@ module GardenVariety
     def create
       self.resource = vest(new_resource)
       if resource.save
+        flash[:success] = flash_message(:success)
         block_given? ? yield : redirect_to(resource)
+        flash.discard(:success) if REDIRECT_CODES.exclude?(response.status)
       else
+        flash.now[:error] = flash_message(:error)
         render :new
       end
     end
@@ -65,8 +70,11 @@ module GardenVariety
     def update
       self.resource = vest(find_resource)
       if resource.save
+        flash[:success] = flash_message(:success)
         block_given? ? yield : redirect_to(resource)
+        flash.discard(:success) if REDIRECT_CODES.exclude?(response.status)
       else
+        flash.now[:error] = flash_message(:error)
         render :edit
       end
     end
@@ -81,8 +89,14 @@ module GardenVariety
     def destroy
       self.resource = find_resource
       authorize(resource)
-      resource.destroy!
-      block_given? ? yield : redirect_to(action: :index)
+      if resource.destroy
+        flash[:success] = flash_message(:success)
+        block_given? ? yield : redirect_to(action: :index)
+        flash.discard(:success) if REDIRECT_CODES.exclude?(response.status)
+      else
+        flash.now[:error] = flash_message(:error)
+        render :show
+      end
     end
   end
 

data/lib/garden_variety/controller.rb

@@ -224,5 +224,94 @@ module GardenVariety
       model.assign_attributes(permitted_attributes(model))
       model
     end
+
+    # @!visibility public
+    # Returns Hash of values for interpolation in flash messages via
+    # I18n.  By default, returns +resource_name+ and
+    # +resource_capitalized+ values appropriate to the controller.
+    # Override this method to provide your own values.  Be aware that
+    # certain option names, such as +default+ and +scope+, are reserved
+    # by the I18n gem, and can not be used for interpolation.  See the
+    # {https://www.rubydoc.info/gems/i18n I18n documentation} for more
+    # information.
+    #
+    # @return [Hash]
+    def flash_options
+      { resource_name: resource_class.model_name.human.downcase,
+        resource_capitalized: resource_class.model_name.human }
+    end
+
+    # @!visibility public
+    # Returns a flash message appropriate to the controller, the current
+    # action, and a given status.  The flash message is looked up via
+    # I18n using a prioritized list of possible keys.  The key priority
+    # is as follows:
+    #
+    # * +{controller_name}.{action_name}.{status}+
+    # * +{controller_name}.{action_name}.{status}_html+
+    # * +{action_name}.{status}+
+    # * +{action_name}.{status}_html+
+    # * +{status}+
+    # * +{status}_html+
+    #
+    # If the controller is namespaced, the namespace will prefix
+    # (dot-separated) the +{controller_name}+ portion of the key.
+    #
+    # I18n string interpolation can be used in flash messages, with
+    # interpolated values provided by the {flash_options} method.
+    #
+    # @example Key priority
+    #   ### config/locales/garden_variety.en.yml
+    #   # en:
+    #   #   success: "Success!"
+    #   #   create:
+    #   #     success: "%{resource_capitalized} created."
+    #   #   delete:
+    #   #     success: "%{resource_capitalized} deleted."
+    #   #   posts:
+    #   #     create:
+    #   #       success: "Congratulations on your new post!"
+    #
+    #   # via PostsController#create
+    #   flash_message(:success)  # == "Congratulations on your new post!"
+    #
+    #   # via PostsController#update
+    #   flash_message(:success)  # == "Success!"
+    #
+    #   # via PostsController#delete
+    #   flash_message(:success)  # == "Post deleted."
+    #
+    # @example Namespaced controller
+    #   ### config/locales/garden_variety.en.yml
+    #   # en:
+    #   #   create:
+    #   #     success: "Created new %{resource_name}."
+    #   #   update:
+    #   #     success: "Updated %{resource_name}."
+    #   #   messages:
+    #   #     drafts:
+    #   #       update:
+    #   #         success: "Draft saved."
+    #
+    #   # via Messages::DraftsController#create
+    #   flash_message(:success)  # == "Created new draft."
+    #
+    #   # via Messages::DraftsController#update
+    #   flash_message(:success)  # == "Draft saved."
+    #
+    # @param status [Symbol, String]
+    # @return [String]
+    def flash_message(status)
+      controller_key = controller_path.tr("/", I18n.default_separator)
+      keys = [
+        :"#{controller_key}.#{action_name}.#{status}",
+        :"#{controller_key}.#{action_name}.#{status}_html",
+        :"#{action_name}.#{status}",
+        :"#{action_name}.#{status}_html",
+        :"#{status}",
+        :"#{status}_html",
+      ]
+      helpers.translate(keys.shift, default: keys, **flash_options)
+    end
   end
 end

data/lib/garden_variety/version.rb

@@ -1,3 +1,3 @@
 module GardenVariety
-  VERSION = "1.2"
+  VERSION = "2.0"
 end

data/lib/generators/garden/install/install_generator.rb

@@ -0,0 +1,18 @@
+require "rails/generators/base"
+
+# @!visibility private
+module Garden
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.join(__dir__, "templates")
+
+      def copy_locales
+        directory "locales", "config/locales"
+      end
+
+      def install_pundit
+        generate("pundit:install", "--skip")
+      end
+    end
+  end
+end

data/lib/generators/garden/install/templates/locales/garden_variety.en.yml

@@ -0,0 +1,10 @@
+en:
+  create:
+    success: '%{resource_capitalized} was successfully created.'
+    error: 'Could not create %{resource_name}.'
+  update:
+    success: '%{resource_capitalized} was successfully updated.'
+    error: 'Could not update %{resource_name}.'
+  destroy:
+    success: '%{resource_capitalized} was successfully destroyed.'
+    error: 'Could not destroy %{resource_name}.'

data/lib/generators/garden/scaffold/scaffold_generator.rb

@@ -4,6 +4,8 @@ require "rails/generators/base"
 module Garden
   module Generators
     class ScaffoldGenerator < Rails::Generators::Base
+      source_root File.join(__dir__, "templates")
+
       argument :resource, type: :string
 
       # NOTE: an appropriate default value for template_engine (e.g.
@@ -20,6 +22,10 @@ module Garden
         super
       end
 
+      def ensure_locales
+        directory "../../install/templates/locales", "config/locales", skip: true
+      end
+
       def generate_scaffolding
         generate("resource", *@argv)
         generate("#{options[:template_engine]}:scaffold", *@argv)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: garden_variety
 version: !ruby/object:Gem::Version
-  version: '1.2'
+  version: '2.0'
 platform: ruby
 authors:
 - Jonathan Hefner
@@ -82,6 +82,8 @@ files:
 - lib/garden_variety/current_user_stub.rb
 - lib/garden_variety/railtie.rb
 - lib/garden_variety/version.rb
+- lib/generators/garden/install/install_generator.rb
+- lib/generators/garden/install/templates/locales/garden_variety.en.yml
 - lib/generators/garden/scaffold/scaffold_generator.rb
 homepage: https://github.com/jonathanhefner/garden_variety
 licenses: