wallaby-view 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbb2b53edfd05292aa8277741b572b703f952befd6048c4592f9f1eea60e6cb0
-  data.tar.gz: 57fb94ffc44a1b6cd67a9e20939c3535b74d6c5a2283237f69548551d437eb44
+  metadata.gz: 7f9bf01cc8876f03b073afdaa8b322f00d781ff50fefd39f2eaac22f8feb535d
+  data.tar.gz: 04e7113c6650b3b756d886d859d08369f96beb39c2f2e5ffac4d8ba5c44c16c9
 SHA512:
-  metadata.gz: 4fe5edfe3875669399eab479e38cab13b549926348f0d402796f66b5f19c914e95e3f15b088e91292575436cb838cdfd57cf82ed980e493859602ee16d2c3e68
-  data.tar.gz: 5e3557307cc24027184dc95eca8eb6945815f7b5b99a0182618a4ccee64fcd083b401421d5fd08c5eb71a3c2ecea7594ee53329b318399ac21d7e1cb0f2d8e4c
+  metadata.gz: bd9d7a5a6985bfd6e317a44d8adf737a8e5639227e154fed90bdb2ac7230d6094efd0bebf5a60763826571b3cbc574365a1bf22d4dd4a6f326df279fd4f049e4
+  data.tar.gz: 7658edb6c169b0e577043856abe82583b3312a24c514cb4355584e15e2c2dd695dca2994731207a51f9b48c6e4575f0ece43c4de06edb133aae387db555fcbfa

data/README.md

@@ -7,11 +7,14 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/d3e924dd70cc12562eab/test_coverage)](https://codeclimate.com/github/wallaby-rails/wallaby-view/test_coverage)
 [![Inch CI](https://inch-ci.org/github/wallaby-rails/wallaby-view.svg?branch=master)](https://inch-ci.org/github/wallaby-rails/wallaby-view)
 
-`Wallaby::View` is a Ruby gem that extends Rails layout/template/partial inheritance chain to allow searching layout/template/partial using theme name and action name.
+**Wallaby::View** extends Rails template/partial inheritance chain to be able to:
+
+- organize partials in `#{controller_path}/#{action}` fashion on top of Rails' controller fashion by extending Rails' [\_prefixes](https://github.com/rails/rails/blob/master/actionview/lib/action_view/view_paths.rb#L90).
+- configure the theme (a set of layout/templates/partials starting with the theme prefix).
 
 ## Install
 
-Add `Wallaby::View` to `Gemfile`.
+Add **Wallaby::View** to `Gemfile`.
 
 ```ruby
 gem 'wallaby-view'
@@ -23,7 +26,7 @@ And re-bundle.
 bundle install
 ```
 
-Include `Wallaby::View` in the target controller (e.g. `ApplicationController`):
+Include **Wallaby::View** in the controller (e.g. **ApplicationController**):
 
 ```ruby
 # app/controllers/application_controller
@@ -43,7 +46,7 @@ class ApplicationController < ActionController::Base
 end
 
 # app/controllers/admin/application_controller
-class Admin::ApplicationController < ApplicationController
+class Admin::ApplicationController < ::ApplicationController
   self.theme_name = 'secure'
 end
 
@@ -54,7 +57,7 @@ class Admin::UsersController < Admin::ApplicationController
 end
 ```
 
-By using `Wallaby::View`, the lookup folder order of `admin/application#edit` action becomes:
+By using **Wallaby::View**, a template/partial for the `admin/application#edit` action will be looked up in the following folder order from top to bottom:
 
 - app/views/admin/application/edit
 - app/views/admin/application
@@ -63,18 +66,22 @@ By using `Wallaby::View`, the lookup folder order of `admin/application#edit` ac
 - app/views/application/edit
 - app/views/application
 
-Then it is possible to create a relative partial in one of the above folder for `admin/application#edit` action, for instance:
+Then it depends on how a relative partial should be shared, the partial can be created in one of the above folders.
+For example, if a `form` partial is designed specifically for `admin/application#edit` action, then it can be created in `admin/application/edit` folder as below:
+
+```erb
+<%# app/views/admin/application/edit/_form.html.erb %>
+a form for `admin/application#edit`
+```
+
+Then in the `admin/application#edit` template, rendering the relative `form` partial will result in using the above partial.
 
 ```erb
 <%# app/views/admin/application/edit.html.erb %>
 <% render 'form' %>
-
-<%# app/views/secure/edit/_form.html.erb %>
-This form partial is under `secure` theme and `edit` action,
-but still can be rendered by `admin/application#edit` action
 ```
 
-For `admin/users#edit` action, since `mapping_actions` option is set, `edit` will be mapped to `form`.
+For `admin/users#edit` action, since `mapping_actions` option is set, `edit` will be mapped to `form`, and `form` will be added to the prefixes as well.
 Therefore, the lookup folder order of `admin/users#edit` becomes:
 
 - app/views/admin/users/edit
@@ -95,7 +102,7 @@ Therefore, the lookup folder order of `admin/users#edit` becomes:
 
 ## Advanced Usage
 
-It is possible to override the `_prefixes` method to make more changes to the prefixes:
+It is possible to override the `_prefixes` method to make more changes to the prefixes before suffixing them with the action name:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -109,14 +116,13 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-Then the lookup folder order of `application#edit` becomes:
+Then the lookup folder order of e.g. `application#edit` becomes:
 
 - app/views/application/edit
 - app/views/application
 - app/views/last_resort/edit
 - app/views/last_resort
 
-
 ## Documentation
 
 - [API Reference](https://www.rubydoc.info/gems/wallaby-view)

data/lib/wallaby/view.rb

@@ -11,35 +11,18 @@ require 'wallaby/view/custom_prefixes'
 
 module Wallaby # :nodoc:
   # To extend Rails prefixes and improve lookup performance.
+  #
+  # For example, include {Wallaby::View} module in the controller:
+  #
+  # ```
+  # # app/controllers/application_controller
+  # class ApplicationController < ActionController::Base
+  #   include Wallaby::View
+  # end
+  # ```
   module View
     extend ActiveSupport::Concern
 
-    # This is the method executed when this module is included by other modules.
-    #
-    # Basically, it renames the methods so that it is possible
-    # to access the original methods after overriding them:
-    #
-    # 1. Rename the following original methods:
-    #
-    #     - rename {https://github.com/rails/rails/blob/master/actionview/lib/action_view/view_paths.rb#L97
-    #       lookup_context} to {Wallaby::View::ActionViewable#original_lookup_context original_lookup_context}
-    #     - rename {https://github.com/rails/rails/blob/master/actionview/lib/action_view/view_paths.rb#L90 _prefixes}
-    #       to {Wallaby::View::ActionViewable#original_prefixes original_prefixes}
-    #
-    # 2. Override the original methods:
-    #
-    #     - rename {Wallaby::View::ActionViewable#override_lookup_context override_lookup_context}
-    #       to {Wallaby::View::ActionViewable#lookup_context lookup_context}
-    #     - rename {Wallaby::View::ActionViewable#override_prefixes override_prefixes}
-    #       to {Wallaby::View::ActionViewable#\_prefixes \_prefixes}
-    # @param mod [Module]
-    def self.included(mod)
-      mod.send :alias_method, :original_lookup_context, :lookup_context
-      mod.send :alias_method, :original_prefixes, :_prefixes
-      mod.send :alias_method, :lookup_context, :override_lookup_context
-      mod.send :alias_method, :_prefixes, :override_prefixes
-    end
-
     COMMA = ',' # :nodoc:
     EMPTY_STRING = '' # :nodoc:
     DOT_RB = '.rb' # :nodoc:
@@ -49,5 +32,14 @@ module Wallaby # :nodoc:
 
     include ActionViewable
     include Themeable
+
+    included do
+      # NOTE: Basically, it renames the methods so that it is possible
+      # to access the original methods after overriding them:
+      alias_method :original_lookup_context, :lookup_context
+      alias_method :original_prefixes, :_prefixes
+      alias_method :lookup_context, :override_lookup_context
+      alias_method :_prefixes, :override_prefixes
+    end
   end
 end

data/lib/wallaby/view/action_viewable.rb

@@ -7,15 +7,13 @@ module Wallaby
     module ActionViewable
       extend ActiveSupport::Concern
 
-      class << self
-        # @!attribute prefix_options
-        # It stores the options for {#_prefixes}. It can inherit options from superclass.
-        # @return [Hash] prefix options
-      end
-
-      class_methods do
+      module ClassMethods # :nodoc:
+        # @!attribute[w] prefix_options
         attr_writer :prefix_options
 
+        # @!attribute[r] prefix_options
+        # It stores the options for {#_prefixes}. It can inherit options from superclass.
+        # @return [Hash] prefix options
         def prefix_options
           @prefix_options ||= superclass.try(:prefix_options)
         end
@@ -48,7 +46,7 @@ module Wallaby
       # @param prefixes [Array<String>] the base prefixes
       # @param action_name [String] the action name to add to the prefixes list
       # @param themes [String] the theme name to add to the prefixes list
-      # @param options [Hash] the options for {Wallaby::View::CustomPrefixes}
+      # @param options [Hash] the options that {Wallaby::View::CustomPrefixes} accepts
       # @return [Array<String>]
 
       # (see #_prefixes)

data/lib/wallaby/view/custom_prefixes.rb

@@ -9,15 +9,18 @@ module Wallaby
       # @return [Array<String>]
       # @see Wallaby::View::ActionViewable#_prefixes
       attr_reader :prefixes
+
       # @!attribute [r] action_name
       # Action name to be added
       # @return [String]
       attr_reader :action_name
+
       # @!attribute [r] themes
       # Themes to be inserted
       # @return [Array<Hash>]
       # @see Wallaby::View::Themeable#.themes
       attr_reader :themes
+
       # @!attribute [r] options
       # Options for extending the given prefixes
       # @return [Hash]
@@ -28,6 +31,7 @@ module Wallaby
       #   Wallaby::View::CustomPrefixes.execute(
       #     prefixes: ['users', 'application'], action_name: 'index'
       #   )
+      #
       #   # => [
       #   #   'users/index',
       #   #   'users',
@@ -39,6 +43,7 @@ module Wallaby
       #     prefixes: ['users', 'application'], action_name: 'index',
       #     themes: [{ theme_name: 'secure', theme_path: 'users' }]
       #   )
+      #
       #   # => [
       #   #   'users/index',
       #   #   'users',
@@ -52,6 +57,7 @@ module Wallaby
       #     prefixes: ['users', 'application'], action_name: 'edit',
       #     options: { mapping_actions: { 'edit' => 'form' } }
       #   )
+      #
       #   # => [
       #   #   'users/form',
       #   #   'users',
@@ -94,8 +100,10 @@ module Wallaby
         end
       end
 
-      private
+      protected
 
+      # @yield [array] To allow the array to be further modified
+      # @yieldparam [Array<String>] array
       # @return [Array<String>]
       def new_prefixes
         prefixes.dup.try do |array|
@@ -105,20 +113,18 @@ module Wallaby
           # in {Wallaby::View::ActionViewable#override_prefixes}
           new_array = yield array if block_given?
 
-          # If the above block doesn't return an array,
-          # it's assumed that `array` is changed
+          # If the above block doesn't return a new array, it returns the old `array`.
           new_array.is_a?(Array) ? new_array : array
         end
       end
 
-      # Action name actions
-      # @return [Array<String>]
+      # @return [Array<String>] Action names
       def actions
         @actions ||= [action_name, mapped_action_name].compact
       end
 
-      # Insert theme name into the prefixes
-      # @param [Array] array
+      # Insert theme names into the prefixes
+      # @param [Array<String>] array
       def insert_themes_into(array)
         themes.each do |theme|
           index = array.index theme[:theme_path]

data/lib/wallaby/view/themeable.rb

@@ -6,8 +6,7 @@ module Wallaby
     module Themeable
       extend ActiveSupport::Concern
 
-      class << self
-        # @!attribute theme_name
+      module ClassMethods # :nodoc:
         # The theme name is used to specify the layout and prefixes
         # so that a set of theme implementation for the frontend (html/css/javascript)
         # can be applied
@@ -27,6 +26,7 @@ module Wallaby
         #
         #     def index
         #       _prefixes
+        #
         #       # =>
         #       # [
         #       #   'admin/application/index',
@@ -37,8 +37,22 @@ module Wallaby
         #       #   'application'
         #       # ]
         #     end
-        #     end
+        #   end
+        # @param theme_name [String]
+        # @param options [Hash] same options as Rails'
+        #   {https://api.rubyonrails.org/classes/ActionView/Layouts/ClassMethods.html#method-i-layout
+        #   layout} method
+        def theme_name=(theme_name, **options, &block)
+          layout theme_name, options, &block
+          @theme_path = theme_name && controller_path || nil
+          @theme_name = theme_name || nil
+        end
+
+        # @!attribute [r] theme_name
         # @return [String, nil] theme name
+        def theme_name
+          defined?(@theme_name) && @theme_name || superclass.try(:theme_name)
+        end
 
         # @!attribute [r] theme
         # @example Once theme is set, the metadata will be set as well:
@@ -46,6 +60,7 @@ module Wallaby
         #     self.theme_name = 'secure'
         #
         #     self.theme
+        #
         #     # =>
         #     # {
         #     #   theme_name: 'secure',
@@ -53,25 +68,6 @@ module Wallaby
         #     # }
         #   end
         # @return [Hash] theme metadata
-
-        # @!attribute [r] themes
-        # @return [Array<Hash>] a list of {.theme} metadata
-      end
-
-      class_methods do
-        # (see .theme_name)
-        def theme_name=(theme_name, **options, &block)
-          layout theme_name, options, &block
-          @theme_path = theme_name && controller_path || nil
-          @theme_name = theme_name || nil
-        end
-
-        # (see .theme_name)
-        def theme_name
-          defined?(@theme_name) && @theme_name || superclass.try(:theme_name)
-        end
-
-        # (see .theme)
         def theme
           defined?(@theme_name) && @theme_name && {
             theme_name: @theme_name,
@@ -79,7 +75,8 @@ module Wallaby
           } || superclass.try(:theme)
         end
 
-        # (see .themes)
+        # @!attribute [r] themes
+        # @return [Array<Hash>] a list of {#theme} metadata
         def themes
           list = superclass.try(:themes) || []
           list.prepend theme if defined?(@theme_name) && @theme_name

data/lib/wallaby/view/version.rb

@@ -2,6 +2,6 @@
 
 module Wallaby
   module View
-    VERSION = '0.1.4' # :nodoc:
+    VERSION = '0.1.5' # :nodoc:
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wallaby-view
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Tian Chen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-28 00:00:00.000000000 Z
+date: 2020-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -104,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Wallaby View to extend Rails layout/template/partial inheritance chain.