{"id":15501455,"url":"https://github.com/annkissam/rummage_phoenix","last_synced_at":"2025-04-05T04:13:24.845Z","repository":{"id":50392393,"uuid":"82206727","full_name":"annkissam/rummage_phoenix","owner":"annkissam","description":"Full Phoenix Support for Rummage. It can be used for searching, sorting and paginating collections in phoenix.","archived":false,"fork":false,"pushed_at":"2022-07-08T11:59:25.000Z","size":2643,"stargazers_count":150,"open_issues_count":10,"forks_count":37,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-29T03:09:19.075Z","etag":null,"topics":["elixir","elixir-library","elixir-programming-language","metasearch","pagination","phoenix","ransack","rummage","search","searching","sort","sorting"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/annkissam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-16T17:23:47.000Z","updated_at":"2025-01-24T00:04:50.000Z","dependencies_parsed_at":"2022-09-18T15:54:23.796Z","dependency_job_id":null,"html_url":"https://github.com/annkissam/rummage_phoenix","commit_stats":null,"previous_names":["excipients/rummage_phoenix"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annkissam%2Frummage_phoenix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annkissam%2Frummage_phoenix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annkissam%2Frummage_phoenix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annkissam%2Frummage_phoenix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/annkissam","download_url":"https://codeload.github.com/annkissam/rummage_phoenix/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284951,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","elixir-library","elixir-programming-language","metasearch","pagination","phoenix","ransack","rummage","search","searching","sort","sorting"],"created_at":"2024-10-02T09:04:24.788Z","updated_at":"2025-04-05T04:13:24.820Z","avatar_url":"https://github.com/annkissam.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rummage.Phoenix\n\n[![Build Status](https://travis-ci.org/aditya7iyengar/rummage_phoenix.svg?branch=master)](https://travis-ci.org/aditya7iyengar/rummage_phoenix)\n[![Hex Version](http://img.shields.io/hexpm/v/rummage_phoenix.svg?style=flat)](https://hex.pm/packages/rummage_phoenix)\n[![hex.pm downloads](https://img.shields.io/hexpm/dt/rummage_phoenix.svg)](https://hex.pm/packages/rummage_phoenix)\n[![Hex docs](http://img.shields.io/badge/hex.pm-docs-green.svg?style=flat)](https://hexdocs.pm/rummage_phoenix)\n[![docs](https://inch-ci.org/github/aditya7iyengar/rummage_phoenix.svg)](http://inch-ci.org/github/aditya7iyengar/rummage_phoenix)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/aditya7iyengar/rummage_phoenix/master/LICENSE)\n\n`Rummage.Phoenix` is a support framework for `Phoenix` that can be used to manipulate `Phoenix` collections and `Ecto`\nmodels with Search, Sort and Paginate operations.\n\nIt accomplishes the above operations by using `Rummage.Ecto`, to paginate `Ecto` queries and adds Phoenix and HTML\nsupport to views and controllers. For information on how to configure `Rummage.Ecto` visit\n[this](https://github.com/Excipients/rummage_ecto) page.\n\nThe best part about rummage is that all the three operations: `Search`, `Sort` and `Paginate` integrate seamlessly and\ncan be configured separately. To check out their seamless integration, please check the information below.\n\n**NOTE: `Rummage` is not like `Ransack`, and doesn't intend to be either. It doesn't add functions based on search params.\nIf you'd like to have that for a model, you can always configure `Rummage` to use your `Search` module for that model. This\nis why Rummage has been made configurable.**\n\n________________________________________________________________________________________________\n\n**Search, Sort and Paginate seamlessly in Phoenix!**\n\n![phoenix all together](src/images/rummage_all_together.gif)\n\n________________________________________________________________________________________________\n\n## Installation\n\nThis is [available in Hex](https://hexdocs.pm/rummage_phoenix/), the package can be installed as:\n\n  - Add `rummage_phoenix` to your list of dependencies in `mix.exs`:\n\n    ```elixir\n    def deps do\n      [\n        {:rummage_phoenix, \"~\u003e 1.2.0\"}\n      ]\n    end\n    ```\n\n## Blogs\n\n### Current Blogs:\n\n  - [Rummage Demo \u0026 Basics](https://medium.com/@aditya7iyengar/searching-sorting-and-pagination-in-elixir-phoenix-with-rummage-part-1-933106ec50ca#.der0yrnvq)\n  - [Using Rummage.Ecto](https://medium.com/@aditya7iyengar/searching-sorting-and-pagination-in-elixir-phoenix-with-rummage-part-2-8e36558984c2#.vviioi5ia)\n  - [Using Rummage.Phoenix](https://medium.com/@aditya7iyengar/searching-sorting-and-pagination-in-elixir-phoenix-with-rummage-part-3-7cf5023bc226#.q08478ud2)\n\n### Coming up next:\n\n  - Using Rummage.Phoenix 2\n  - Using the Rummage Search hook\n  - Using the Rummage Sort hook\n  - Writing a Custom Rummage.Ecto Hook\n  - Writing a Custom Rummage.Phoenix HTML helper\n  - Using Rummage with other Libraries: Kerosene\n  - Using Rummage with other Libraries: Scrivener\n\n\n## Configuration (Optional, Not the preferred way to set `default_per_page`)\n\n`Rumamge.Phoenix` can be configured globally with a `default_per_page` value (which can be overriden for a model).\nThis is **NOT** the preferred way to set `default_per_page` as it might lead to conflicts. It is recommended to\ndo it per model as show below in the [Initial Setup](#initial-setup) section. If you want to set `default_per_page`\nfor all the models, add it to `model` function in `web.ex`\n\n  - Add `rummage_phoenix` config to your list of configs in `dev.exs`:\n\n    ```elixir\n    config :rummage_phoenix,\n      Rummage.Phoenix,\n      default_per_page: 5\n    ```\n\n## Usage (The screenshots correspond to version 0.6.0, soon there will be screenshots for version 1.0.0)\n\n### Initial Setup\n\n  - Use `Rummage.Controller` in to controller module:\n\n  ```elixir\n  defmodule MyApp.ProductController do\n    use MyApp.Web, :controller\n    use Rummage.Phoenix.Controller\n\n    # More code below....\n  end\n  ```\n\n  - Change the `index` action in the controller:\n\n  ```elixir\n  def index(conn, params) do\n    {query, rummage} = Product\n      |\u003e Rummage.Ecto.rummage(params[\"rummage\"])\n\n    products = Repo.all(query)\n\n    render conn, \"index.html\",\n      products: products,\n      rummage: rummage\n  end\n  ```\n\n  - if using Search feature, define a `search` path in the `router.ex` (no need to define the action):\n\n  ```elixir\n  scope \"/\", MyApp do\n    pipe_through :browser # Use the default browser stack\n\n    get \"/\", PageController, :index\n    resources \"/products\", ProductController\n  end\n  ```\n\nDoing this itself will allow you to search, sort and paginate by updating `params` on the request.\nPlease check the [screenshots](#more-screenshots) below for details\n\n\n### Using Rummage.ViewHelpers\n\n  - Use `Rummage.View` in to a view module:\n\n  ```elixir\n  defmodule MyApp.ProductView do\n    use MyApp.Web, :view\n    use Rummage.Phoenix.View\n\n    # More code below...\n  end\n  ```\n\n  Note: If you get a \"MyApp.Router.Helpers is not available\" exception, you can provide your router with:\n\n  ```elixir\n  defmodule MyApp.ProductView do\n    use MyApp.Web, :view\n    use Rummage.Phoenix.View, helpers: MyApp.Web.Router.Helpers\n\n    # More code below...\n  end\n  ```\n\n  or through the config:\n\n  ```\n  config :rummage_phoenix, Rummage.Phoenix, [\n    default_helpers: MyApp.Web.Router.Helpers,\n  ]\n  ```\n\n  Note: If the path helper name is incorrect, you can specify it with:\n\n  ```elixir\n  defmodule MyApp.ProductView do\n    use MyApp.Web, :view\n    use Rummage.Phoenix.View, struct: \"special_product\" # will become special_product_path\n\n    # More code below...\n  end\n  ```\n\n\n  - #### Pagination:\n  Add this at the bottom of `index.html.eex` to render `Rummage` pagination links (Make sure that you\n  pass `rummage` to the views from the `index` action in the controller) :\n\n  ```elixir\n  \u003c%= pagination_link(@conn, @rummage) %\u003e\n  ```\n\n  Reload and this is how your page should look:\n\n  ![phoenix pagination](src/images_1.0/RummagePhoenixPagination.gif)\n\n\n  - #### Sorting:\n  Replace table headers on the `index.html.eex` with sort links (Make sure that the headers are actual columns in the\n  table in the database.)\n\n  Replace this:\n  ```elixir\n    \u003cth\u003eName\u003c/th\u003e\n    \u003cth\u003ePrice\u003c/th\u003e\n    \u003cth\u003eCategory\u003c/th\u003e\n  ```\n\n  With:\n  ```elixir\n    \u003cth\u003e\u003c%= sort_link @conn, @rummage, [field: :name, ci: true] %\u003e\u003c/th\u003e\n    \u003cth\u003e\u003c%= sort_link @conn, @rummage, [field: :price] %\u003e\u003c/th\u003e\n  ```\n\n  OR for Sort by associations:\n  ```elixir\n    \u003cth\u003e\u003c%= sort_link @conn, @rummage, [field: :name, name: \"Category Name\", assoc: [\"category\"]] %\u003e\u003c/th\u003e\n  ```\n\n  Reload and this is how your page should look with sortable links instead of just table headers:\n\n  ![phoenix sorting](src/images_1.0/RummagePhoenixSort.gif)\n\n  **NOTE: Currently working on adding better elements to the views, soon the text\n  arrow in the sort links will be replaced by an icon**\n\n  - ### Searching:\n  Add a search form in the `index.html.eex` with searchable fields:\n\n  ```elixir\n  \u003c%= search_form(@conn, @rummage, [fields:\n  [\n    name: %{label: \"Search by Product Name\", search_type: \"ilike\"},\n    price: %{label: \"Search by Price\", search_type: \"eq\"},\n  ], button_class: \"btn\",\n  ]) %\u003e\n  ```\n  OR for Search by associations:\n\n  ```elixir\n  \u003c%= search_form(@conn, @rummage, [fields:\n  [\n    name: %{label: \"Search by Category Name\", search_type: \"ilike\", assoc: [\"category\"]}\n  ], button_class: \"btn\",\n  ]) %\u003e\n  ```\n\n  Reload and your page should look somewhat like this:\n  ![phoenix searching](src/images_1.0/RummagePhoenixSearch.gif)\n\n  - #### ALL TOGETHER:\n  The best part about `Rummage` is that all the three hooks/operations integrate seamlessly without affecting each other's functionality\n  and therefore, you have a page looking somewhat like this:\n\n  ![phoenix all together](src/images_1.0/RummagePhoenixSearch.gif)\n\n## More Screenshots\n\n### Before rummage\n![before pagination](src/images/before_rummage.png)\n\n### After Pagination:\n\n- Default pagination:\n\n![after pagination](src/images/rummage_ecto_paginate.png)\n\n- Custom pagination params:\n\n![custom pagination params](src/images/custom_pagination_params.png)\n![custom pagination page](src/images/custom_paginated_page.png)\n\n### After Pagination View:\n\n- Default\n![after pagination](src/images/rummage_ecto_paginate.png)\n\n- Custom pagination params\n![phoenix pagination](src/images/rummage_phoenix_pagination.png)\n\n### After Sort:\n\n![custom sort params asc](src/images/custom_sort_params_asc.png)\n![custom sort page asc](src/images/rummage_ecto_sort_asc.png)\n\n\n![custom sort params desc](src/images/custom_sort_params_desc.png)\n![custom sort page desc](src/images/rummage_ecto_sort_desc.png)\n\n### After Sort View:\n\n![phoenix sorting](src/images/rummage_phoenix_sorting.png)\n\n### After Search:\n\n![custom search params](src/images/custom_search_params.png)\n![custom search page](src/images/rummage_ecto_search.png)\n\n### After Search View:\n\n![phoenix searching](src/images/rummage_phoenix_searching.png)\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannkissam%2Frummage_phoenix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fannkissam%2Frummage_phoenix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannkissam%2Frummage_phoenix/lists"}