# Rummage.Phoenix

[![Build Status](](
[![Hex Version](](
[![ downloads](](
[![Hex docs](](
[![MIT licensed](](

`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](src/images/rummage_all_together.gif)


## 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"}

## Blogs

### Current Blogs:

  - [Rummage Demo & Basics](
  - [Using Rummage.Ecto](
  - [Using Rummage.Phoenix](

### 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](#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,
      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....

  - Use `Rummage.Controller` in to controller module:

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

    # More code below....

  - 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

  - 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

Doing this itself will allow you to search, sort and paginate by updating `params` on the request.
Please check the [screenshots](#more-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...

  - #### 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](src/images_1.0/RummagePhoenixPagination.gif)

  - #### 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><%= 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](src/images_1.0/RummagePhoenixSort.gif)

  **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](src/images_1.0/RummagePhoenixSearch.gif)

  - #### 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](src/images_1.0/RummagePhoenixSearch.gif)

## More Screenshots

### Before rummage
![before pagination](src/images/before_rummage.png)

### After Pagination:

- Default pagination:

![after pagination](src/images/rummage_ecto_paginate.png)

- Custom pagination params:

![custom pagination params](src/images/custom_pagination_params.png)
![custom pagination page](src/images/custom_paginated_page.png)

### After Pagination View:

- Default
![after pagination](src/images/rummage_ecto_paginate.png)

- Custom pagination params
![phoenix pagination](src/images/rummage_phoenix_pagination.png)

### After Sort:

![custom sort params asc](src/images/custom_sort_params_asc.png)
![custom sort page asc](src/images/rummage_ecto_sort_asc.png)

![custom sort params desc](src/images/custom_sort_params_desc.png)
![custom sort page desc](src/images/rummage_ecto_sort_desc.png)

### After Sort View:

![phoenix sorting](src/images/rummage_phoenix_sorting.png)

### After Search:

![custom search params](src/images/custom_search_params.png)
![custom search page](src/images/rummage_ecto_search.png)

### After Search View:

![phoenix searching](src/images/rummage_phoenix_searching.png)