Add a guide for using Rails view variants

This adds a guide and two examples of using Rails' view variant support.

Closes thoughtbot#2578

https://guides.rubyonrails.org/layouts_and_rendering.html#the-variants-option

Author: goosys

docs/guides.md

@@ -5,3 +5,4 @@ title: Guides
 - [Hiding Dashboards from the Sidebar](./guides/hiding_dashboards_from_sidebar)
 - [Customising the search](./guides/customising_search)
 - [Scoping HasMany Relations](./guides/scoping_has_many_relations.md)
+- [Switching templates with view variants](./guides/switching_templates_with_view_variants.md)

docs/guides/switching_templates_with_view_variants.md

@@ -0,0 +1,45 @@
+---
+title: Switching templates with view variants
+---
+
+You can switch to different templates using Rails' support for [view
+variants][], which can be used to override the template used inside the
+controller.
+
+By setting the `request.variant` option to any value (in this case, `:admin`)
+at any point in any controller, you can add a new variant to Rails' template
+lookup tree (in this case, `.html+admin.erb`).
+
+For example, to add a button to become the admin to view certain functionality:
+
+```ruby
+class CustomersController < Admin::ApplicationController
+  before_action :with_variant, only: %i[index]
+
+  private
+
+  def with_variant
+    if @current_user.admin?
+      request.variant = :admin
+    end
+  end
+end
+```
+
+```erb
+<!-- app/views/admin/customers/_index_header.html.erb -->
+<p class="identity__banner">
+  You are logged in as <em><%= pundit_user.name %></em>.
+  <%= link_to("Become the Admin", become_admin_customer_path("admin"),
+        class: "identity__become-action")%>
+</p>
+```
+
+```erb
+<!-- app/views/admin/customers/_index_header.html+admin.erb -->
+<p class="identity__banner identity__banner--admin">
+  You are logged in as <em><%= pundit_user.name %></em>.
+</p>
+```
+
+[view variants]: https://guides.rubyonrails.org/layouts_and_rendering.html#the-variants-option

spec/example_app/app/controllers/admin/customers_controller.rb

@@ -1,5 +1,7 @@
 module Admin
   class CustomersController < Admin::ApplicationController
+    before_action :with_variant, only: %i[index]
+
     def become
       user_id = params[:id]
       if user_id == "admin"
@@ -15,5 +17,11 @@ def become
     def scoped_resource
       Customer.where(hidden: false)
     end
+
+    def with_variant
+      if @current_user.admin?
+        request.variant = :admin
+      end
+    end
   end
 end

spec/example_app/app/controllers/admin/stats_controller.rb

@@ -1,10 +1,20 @@
 module Admin
   class StatsController < Admin::ApplicationController
+    before_action :with_variant, only: %i[index]
+
     def index
       @stats = {
         customer_count: Customer.count,
         order_count: Order.count
       }
     end
+
+    private
+
+    def with_variant
+      if @current_user.admin?
+        request.variant = :admin
+      end
+    end
   end
 end

spec/example_app/app/views/admin/customers/_index_header.html+admin.erb

@@ -0,0 +1,5 @@
+<% content_for(:header_middle) do %>
+  <p class="identity__banner identity__banner--admin">You are logged in as <em><%= pundit_user.name %></em>.</p>
+<% end %>
+
+<%= render template: 'administrate/application/_index_header', locals: local_assigns %>

spec/example_app/app/views/admin/customers/_index_header.html.erb

@@ -1,5 +1,5 @@
 <% content_for(:header_middle) do %>
-  <p class="identity__banner<%= " identity__banner--admin" if pundit_user.admin? %>">You are logged in as <em><%= pundit_user.name %></em>. <%= link_to("Become the Admin", become_admin_customer_path("admin"), class: "identity__become-action") unless pundit_user.admin? %></p>
+  <p class="identity__banner">You are logged in as <em><%= pundit_user.name %></em>. <%= link_to("Become the Admin", become_admin_customer_path("admin"), class: "identity__become-action")%></p>
 <% end %>
 
 <%= render template: 'administrate/application/_index_header', locals: local_assigns %>

spec/example_app/app/views/admin/stats/index.html+admin.erb

@@ -0,0 +1,7 @@
+<div style="padding: 20px">
+  <h1>Stats</h1>
+  <br>
+  <p><b>Total Customers:</b> <%= @stats[:customer_count] %></h1>
+  <br>
+  <p><b>Total Orders:</b> <%= @stats[:order_count] %></h1>
+</div>

spec/example_app/app/views/admin/stats/index.html.erb

@@ -1,7 +1,5 @@
 <div style="padding: 20px">
   <h1>Stats</h1>
   <br>
-  <p><b>Total Customers:</b> <%= @stats[:customer_count] %></h1>
-  <br>
-  <p><b>Total Orders:</b> <%= @stats[:order_count] %></h1>
+  <p>Stats are only visible to Admin. <%= link_to("Become the Admin", become_admin_customer_path("admin"), class: "identity__become-action") %></p>
 </div>