rummage_phoenix

Full Phoenix Support for Rummage. It can be used for searching, sorting and paginating collections in phoenix.

Monthly Downloads: 124

Programming language: Elixir

License: MIT License

Tags: Framework Components    

Latest version: v2.0.0

README

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](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"}
    ]
  end
  

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 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.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
      |> Rummage.Ecto.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

Note: If you get a "MyApp.Router.Helpers is not available" exception, you can provide your router with:

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

    # More code below...
  end

or through the config:

  config :rummage_phoenix, Rummage.Phoenix, [
    default_helpers: MyApp.Web.Router.Helpers,
  ]

Note: If the path helper name is incorrect, you can specify it with:

  defmodule MyApp.ProductView do
    use MyApp.Web, :view
    use Rummage.Phoenix.View, struct: "special_product" # will become special_product_path

    # 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](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>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: :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:
  [
    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)