Rummage.Phoenix

Rummage.Phoenix is a support framework for Phoenix that can be used to manipulate Phoenix collections and Ecto models with Search, Sort and Paginate operations.

It accomplishes the above operations by using Rummage.Ecto, to paginate Ecto queries and adds Phoenix and HTML support to views and controllers. For information on how to configure Rummage.Ecto visit this page.

The best part about rummage is that all the three operations: Search, Sort and Paginate integrate seamlessly and can be configured separately. To check out their seamless integration, please check the information below.

NOTE: Rummage is not like Ransack, and doesn't intend to be either. It doesn't add functions based on search params. If you'd like to have that for a model, you can always configure Rummage to use your Search module for that model. This is why Rummage has been made configurable.

Search, Sort and Paginate seamlessly in Phoenix!

phoenix all together

Installation

This is available in Hex, the package can be installed as:

Add rummage_phoenix to your list of dependencies in mix.exs:

def deps do
  [
    {:rummage_phoenix, "~> 1.2.0"}
  ]
end

Blogs

Current Blogs:

Coming up next:

Using Rummage.Phoenix 2
Using the Rummage Search hook
Using the Rummage Sort hook
Writing a Custom Rummage.Ecto Hook
Writing a Custom Rummage.Phoenix HTML helper
Using Rummage with other Libraries: Kerosene
Using Rummage with other Libraries: Scrivener

Configuration (Optional, Not the preferred way to set `default_per_page`)

Rumamge.Phoenix can be configured globally with a default_per_page value (which can be overriden for a model). This is NOT the preferred way to set default_per_page as it might lead to conflicts. It is recommended to do it per model as show below in the Initial Setup section. If you want to set default_per_page for all the models, add it to model function in web.ex

Add rummage_phoenix config to your list of configs in dev.exs:

config :rummage_phoenix,
  Rummage.Phoenix,
  default_per_page: 5

Usage (The screenshots correspond to version 0.6.0, soon there will be screenshots for version 1.0.0)

Initial Setup

Use Rummage.Ecto in the models/ecto structs:

  defmodule MyApp.Product do
    use MyApp.Web, :model
    use Rummage.Ecto

    # More code below....
  end

Use Rummage.Controller in to controller module:

  defmodule MyApp.ProductController do
    use MyApp.Web, :controller
    use Rummage.Phoenix.Controller

    # More code below....
  end

Change the index action in the controller:

  def index(conn, params) do
    {query, rummage} = Product
      |> Product.rummage(params["rummage"])

    products = Repo.all(query)

    render conn, "index.html",
      products: products,
      rummage: rummage
  end

if using Search feature, define a search path in the router.ex (no need to define the action):

  scope "/", MyApp do
    pipe_through :browser # Use the default browser stack

    get "/", PageController, :index
    resources "/products", ProductController
  end

Doing this itself will allow you to search, sort and paginate by updating params on the request. Please check the screenshots below for details

Using Rummage.ViewHelpers

Use Rummage.View in to a view module:

  defmodule MyApp.ProductView do
    use MyApp.Web, :view
    use Rummage.Phoenix.View

    # More code below...
  end

Pagination:
Add this at the bottom of index.html.eex to render Rummage pagination links (Make sure that you pass rummage to the views from the index action in the controller) :

  <%= pagination_link(@conn, @rummage) %>

Reload and this is how your page should look:

phoenix pagination

Sorting:
Replace table headers on the index.html.eex with sort links (Make sure that the headers are actual columns in the table in the database.)

Replace this:

    <th>Name</th>
    <th>Price</th>
    <th>Category</th>

With:

    <th><%= sort_link @conn, @rummage, [field: :name, ci: true] %></th>
    <th><%= sort_link @conn, @rummage, [field: :price] %></th>

OR for Sort by associations:

    <th><%= sort_link @conn, @rummage, [field: :category_name, name: "Category Name", assoc: ["category"]] %></th>

Reload and this is how your page should look with sortable links instead of just table headers:

phoenix sorting

NOTE: Currently working on adding better elements to the views, soon the text arrow in the sort links will be replaced by an icon

Searching:
Add a search form in the index.html.eex with searchable fields:

  <%= search_form(@conn, @rummage, [fields:
  [
    name: %{label: "Search by Product Name", search_type: "ilike"},
    price: %{label: "Search by Price", search_type: "eq"},
  ], button_class: "btn",
  ]) %>

OR for Search by associations:

  <%= search_form(@conn, @rummage, [fields:
  [
    category_name: %{label: "Search by Category Name", search_type: "ilike", assoc: ["category"]}
  ], button_class: "btn",
  ]) %>

Reload and your page should look somewhat like this: phoenix searching

ALL TOGETHER:
The best part about Rummage is that all the three hooks/operations integrate seamlessly without affecting each other's functionality and therefore, you have a page looking somewhat like this:

phoenix all together