Add ability to provide a string, or :safe tuple containing HTML to be rendered on a resource's index.

Author: aglassman

lib/kaffy/resource_admin.ex

@@ -11,6 +11,35 @@ defmodule Kaffy.ResourceAdmin do
   All functions are optional.
   """
 
+  @doc """
+  Allows a description to be injected into the index view of a resource's index
+  view. This is helpful when you want to provide information to the user about the index page.
+  Return value can be a string, or {:safe, string) tuple.  If :safe tuple is used, HTML will be rendered.
+
+  `index_description/1` takes a schema and must return a `String.t()` or tuple `{:safe, String.t()}`.
+
+  If `index_description/1` is not defined, Kaffy will return nil.
+
+  ## Examples:
+
+  ```elixir
+  def index_description(resource) do
+    "This will show up on the index page."
+  end
+
+  def index_description(resource) do
+    {:safe, "This will show up on the index page.  <b>This will be bold!</b>."}
+  end
+  ```
+  """
+  def index_description(resource) do
+    Utils.get_assigned_value_or_default(
+      resource,
+      :index_description,
+      ResourceSchema.index_description(resource)
+    )
+  end
+
   @doc """
   `index/1` takes the schema module and should return a keyword list of fields and
   their options.

lib/kaffy/resource_schema.ex

@@ -19,6 +19,8 @@ defmodule Kaffy.ResourceSchema do
     end
   end
 
+  def index_description(_schema), do: nil
+
   def index_fields(schema) do
     Keyword.drop(fields(schema), fields_to_be_removed(schema))
   end

lib/kaffy/utils.ex

@@ -355,7 +355,8 @@ defmodule Kaffy.Utils do
           stylesheets: stylesheets ++ acc.stylesheets,
           javascripts: javascripts ++ acc.javascripts
         }
-      end)
+      end
+    )
   end
 
   defp env(key, default \\ nil) do

lib/kaffy_web/templates/resource/index.html.eex

@@ -22,6 +22,14 @@
 
     <div class="card-body table-responsive w-100">
       <div class="card-description">
+        <%= if index_description = Kaffy.ResourceAdmin.index_description(@my_resource) do %>
+          <div class="row">
+              <div class="col-auto mr-auto">
+                  <p><%= index_description %></p>
+              </div>
+          </div>
+        <% end %>
+
         <div class="row">
 
           <div class="col-auto mr-auto">

test/resource_admin_test.exs

@@ -7,12 +7,14 @@ defmodule Kaffy.ResourceAdminTest do
 
   defmodule CactusAdmin do
     def plural_name(_), do: "Cacti"
+    def index_description(_), do: {:safe, "Person Admin <b>Description</b>"}
   end
 
   defmodule Person do
   end
 
   defmodule PersonAdmin do
+    def index_description(_), do: "Person Admin Description"
   end
 
   defmodule Nested.Node do
@@ -43,4 +45,20 @@ defmodule Kaffy.ResourceAdminTest do
       assert ResourceAdmin.plural_name(schema: Person, admin: PersonAdmin) == "People"
     end
   end
+
+  describe "index_description/1" do
+    test "nil if index_description is not defined as function in admin" do
+      refute ResourceAdmin.index_description(schema: Nested.Node, admin: NestedNodeAdmin)
+    end
+
+    test "string if index_description is defined as function in admin" do
+      assert ResourceAdmin.index_description(schema: Person, admin: PersonAdmin) ==
+               "Person Admin Description"
+    end
+
+    test "{:safe, html} if index_description is defined as function in admin" do
+      assert ResourceAdmin.index_description(schema: Cactus, admin: CactusAdmin) ==
+               {:safe, "Person Admin <b>Description</b>"}
+    end
+  end
 end