Add tooltip to search

You can add collection filters to a dashboard and then use them in the
search bar on the index page. eg. `email:[email protected]`

However, these collection filters are not discoverable. You have to know
about them already to know how to use them.

This change introduces a tooltip which lists the available collection
filters, allowing all users to discover what is available.

Closes #2750

app/controllers/administrate/application_controller.rb

@@ -10,12 +10,14 @@ def index
       resources = order.apply(resources)
       resources = paginate_resources(resources)
       page = Administrate::Page::Collection.new(dashboard, order: order)
+      filters = Administrate::Search.new(scoped_resource, dashboard, search_term).valid_filters
 
       render locals: {
         resources: resources,
         search_term: search_term,
         page: page,
-        show_search_bar: show_search_bar?
+        show_search_bar: show_search_bar?,
+        filters: filters
       }
     end
 

app/views/administrate/application/_index_header.html.erb

@@ -15,6 +15,19 @@
       search_term: search_term,
       resource_name: display_resource_name(page.resource_name)
     ) %>
+
+    <% if filters.any? %>
+      <button popovertarget="search-tooltip" class="button--alt" style="margin-right: 2rem;">?</button>
+
+      <div popover id="search-tooltip" role="tooltip" style="padding: 2rem;">
+        <p>Use filters to refine your search:</p>
+        <ul>
+          <% filters.keys.each do |filter_key| %>
+          <li><strong><%= filter_key %></strong>:&lt;value&gt;</li>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
   <% end %>
 
   <div>

app/views/administrate/application/index.html.erb

@@ -29,6 +29,7 @@ It renders the `_table` partial to display details about the resources.
     search_term: search_term,
     page: page,
     show_search_bar: show_search_bar,
+    filters: filters,
   )
 %>
 

lib/administrate/search.rb

@@ -63,6 +63,14 @@ def run
       end
     end
 
+    def valid_filters
+      if @dashboard.class.const_defined?(:COLLECTION_FILTERS)
+        @dashboard.class.const_get(:COLLECTION_FILTERS).stringify_keys
+      else
+        {}
+      end
+    end
+
     private
 
     def apply_filter(filter, filter_param, resources)
@@ -116,14 +124,6 @@ def search_results(resources)
         .where(query_template, *query_values)
     end
 
-    def valid_filters
-      if @dashboard.class.const_defined?(:COLLECTION_FILTERS)
-        @dashboard.class.const_get(:COLLECTION_FILTERS).stringify_keys
-      else
-        {}
-      end
-    end
-
     def attribute_types
       @dashboard.class.const_get(:ATTRIBUTE_TYPES)
     end

spec/features/search_spec.rb

@@ -25,6 +25,49 @@ def have_a_search_bar
     end
   end
 
+  describe "search bar tooltip" do
+    def have_a_search_tooltip
+      have_css("button[popovertarget=search-tooltip]")
+    end
+
+    it "is visible when the current dashboard has collection filters" do
+      visit admin_customers_path
+
+      expect(page).to have_a_search_tooltip
+    end
+
+    context "when clicked" do
+      it "shows a popover with the available filters" do
+        visit admin_customers_path
+        click_on "?"
+
+        expect(page).to have_content("Use filters to refine your search:")
+        expect(page).to have_content("vip:<value>")
+        expect(page).to have_content("kind:<value>")
+      end
+    end
+
+    it "is hidden when the current dashboard has no collection filters" do
+      CustomerDashboard::COLLECTION_FILTERS = {}.freeze
+
+      visit admin_customers_path
+
+      expect(page).not_to have_a_search_tooltip
+    end
+
+    it "is hidden when nothing is searchable in the current dashboard" do
+      CustomerDashboard::ATTRIBUTE_TYPES.each do |_name, field_class|
+        allow(field_class).to(
+          receive(:searchable?).and_return(false)
+        )
+      end
+
+      visit admin_customers_path
+
+      expect(page).not_to have_a_search_tooltip
+    end
+  end
+
   scenario "admin searches for customer by email", :js do
     query = "[email protected]"
     perfect_match = create(:customer, email: "[email protected]")