README.md

Rummage.Ecto

If you're looking for full Phoenix support, Rummage.Phoenix uses Rummage.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 Rummage.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.

To see an example usage of rummage, check this repository.

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, "~> 2.0.0-rc.0"}]
  end

Blogs

Current Blogs:

• Rummage Demo & Basics
• Using Rummage.Ecto
• Using Rummage.Phoenix: Part 1

Coming up next:

• Using Rummage.Phoenix: Part 2
• Using the Rummage Search hook
• Using the Rummage Sort hook
• Writing a Custom Rummage.Ecto Hook
• Writing a Custom Rummage.Phoenix HTML helper

Hooks

• Hooks are modules (that use Rummage.Ecto.Hook) and implement callbacks for Rummage.Ecto.Hook behaviour. Each ecto operation which can transform the query is defined by a Hook. Hooks have run/2 function using which they can transform an Ecto.Queryable variable and have format_params/3 function using which they can transform params passed to them through rummage_ecto

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,
    search: MyApp.SearchModule

• For configuring a repo:

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

• Other config options are: repo, sort, paginate, per_page

• Rummage.Ecto can be configured globally with a 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 Rummage's Pagination) to the rummage_ecto configuration in config.exs:

config :rummage_ecto, Rummage.Ecto,
  repo: MyApp.Repo,
  per_page: 10

• And you should be able to use Rummage.Ecto with any Ecto 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,
  repo: MyApp.Repo,
  search: MyApp.SearchModule,
  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 with the call to Rummage.Ecto. This overrides the default repo set in the configuration:

{queryable, rummage} = Product
  |> Rummage.Ecto.rummage(rummage, repo: MyApp.Repo2)

• And you should be able to use Rummage.Ecto with Product model which is in a different Repo than the default one.

Examples

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

rummage = %{
  search: %{field_1 => %{search_type: :like, search_term: "field_!"}},
  sort: %{field: :field1, order: :asc},
  paginate: %{per_page: 5, page: 1}
}

{queryable, rummage} = Product
  |> Rummage.Ecto.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:

rummage = %{
  search: %{field_1 => %{search_type: :like, search_term: "field_!"}},
  sort: %{field: :field1, order: :asc},
  paginate: %{per_page: 5, page: 1}
}