Rummage.Ecto

If you're looking for full Phoenix support, Rummage.Phoenix uses Rumamge.Ecto and adds HTML and Controller support to it. You can check Rummage.Phoenix out by clicking here

Please refer for CHANGELOG for version specific changes

Rummage.Ecto is a light weight, but powerful framework that can be used to alter Ecto queries with Search, Sort and Paginate operations.

It accomplishes the above operations by using Hooks, which are modules that implement Rumamge.Ecto.Hook behavior. Each operation: Search, Sort and Paginate have their hooks defined in Rummage. By doing this, Rummage is completely configurable.

For example, if you don't like one of the hooks of Rummage, but you do like the other two, you can configure Rummage to not use it and write your own custom hook.

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

Installation

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

• Add rummage_ecto to your list of dependencies in mix.exs:

  def deps do
    [{:rummage_ecto, "~> 1.0.0"}]
  end

Configuration

• NOTE: This is Optional. If no configuration is provided, Rummage will use default hooks and AppName.Repo as the repo

• If you want to override any of the Rummage default hooks, add rummage_ecto config to your list of configs in dev.exs:

  config :rummage_ecto,
    Rummage.Ecto,
    default_search: MyApp.SearchModule

• For configuring a repo:

  config :rummage_ecto,
    Rummage.Ecto,
    default_repo: MyApp.Repo # This can be overridden per model basis, if need be.

• Other config options are: default_repo, default_sort, default_paginate, default_per_page

• Rumamge.Ecto can be configured globally with a default_per_page value (which can be overridden for a model). If you want to set different per_page for different the models, add it to model.exs file while using Rummage.Ecto as shown in the Advanced Usage Section.

Usage

Rummage.Ecto comes with a lot of powerful features which are available right away, without writing a whole lot of code. Below are the ways Rummage.Ecto can be used:

Basic Usage:

• Add the Repo of your app and the desired per_page (if using Rumamge's Pagination) to the rummage_ecto configuration in config.exs:

config :rummage_ecto, Rummage.Ecto,
  default_repo: MyApp.Repo,
  default_per_page: 10

• Use Rummage.Ecto in the models or ecto_structs:

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

  # More code below....
end

• And you should be able to use Rummage.Ecto with Product model.

Advanced Usage:

• If you'd like to override any of Rummage's default hooks with your custom hook, add the CustomHook of your app with the desired operation to the rummage_ecto configuration in config.exs:

config :rummage_ecto, Rummage.Ecto,
  default_repo: MyApp.Repo,
  default_search: MyApp.SearchModule,
  default_paginate: MyApp.PaginateModule

• When using Rummage.Ecto with an app that has multiple Repos, or when there's a need to configure Repo per model basis, it can be passed along with the use statement of Rummage.Ecto in the models or ecto_structs:

defmodule MyApp.Product do
  use MyApp.Web, :model
  use Rummage.Ecto, repo: MyApp.SecondRepo, per_page: 10

  # More code below....
end

• And you should be able to use Rummage.Ecto with Product model.

Blogs

Current Blogs:

• Rummage Demo & Basics
• Using Rummage.Ecto

Coming up next:

• Using Rummage.Phoenix
• 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

Examples

• Setting up the application above will allow us to do the following:

rummage = %{
  "search" => %{"field_1" => %{"assoc" => [], "search_type" => "like", "search_term" => "field_!"}
  "sort" => %{"assoc" => [], "field" => "field_1.asc"},
  "paginate" => %{"per_page" => "5", "page" => "1"}
}

{queryable, rummage} = queryable
  |> Product.rummage(rummage)

products = queryable
|> Product.another_operation # <-- Since `Rummage` is Ecto, we can pipe the result queryable into another queryable operation.
|> Repo.all

• Rummage responds to params with keys: search, sort and/or paginate. It doesn't need to have all the keys, or any keys for that matter. If invalid keys are passed, they won't alter any operations in rummage. Here's an example of Rummage params:

%{
  "search" => %{"field_1" => %{"assoc" => [], "search_type" => "like", "search_term" => "field_!"}
  "sort" => %{"assoc" => [], "field" => "field_1.asc"},
  "paginate" => %{"per_page" => "5", "page" => "1"}
}