Searching, Sorting and Pagination in Elixir & Phoenix with Rummage: Part 3

Now that we have set up an application to work with Rummage.Ecto, let’s see how to add HTML support to it. In this part we will be learning how to add Rummage.Phoenix to our application.

Prerequisites

By now, you should have a functioning Phoenix application with models, views and controllers, its routes defined in the web/router.ex and Rummage.Ecto added it its models. If you don’t have all this set up, I suggest you go to part 2 of this series and follow the instructions to add Rummage.Ecto to a Phoenix app.

Context: The app that we are working on has products which belong to categories. Therefore, category field on the index page shown above is actually the category_name of the category that a product belongs to.

Adding rummage_phoenix to the application

Let us start by adding rummage_phoenix in the list of deps to the application’s mix.exs.

Add rummage_phoenix to deps

Now, run mix deps.get to fetch rummage_phoenix package. Since I have already fetched this dependency, mine is using a locally cached version.

Fetch the package, rummage_ecto, from hex.

Using Rummage.Phoenix in the views

Rummage.Phoenix doesn’t need configuration, as long as you have setup desired configurations for Rummage.Ecto.

We can use the view helpers provided by Rummage.Phoenix by adding the following line of code to product_view.ex:

Use Rummage.Phoenix features in view

For simple applications (like ours), the above setup should suffice, but if you’re application is using complex namespaces, then it is recommended to pass along router helpers and the struct name (model name) that corresponds to the view:

Use Rummage.Phoenix with helpers and struct as options

NOTE: If you don’t provide any Router Helper in either the config or the model, then Rummage will default it to AppName.Router.Helpers. Similarly, if you don’t provide a struct, Rummage will default it to :model_name_lowercased (which should work in most of the cases). So in this app, we could do without providing those options.

Using Rummage.Phoenix view helpers in templates

First let us change our controller to pass rummage variable to the views. The variable rummage, holds the parameters of all the operations and is returned along with a queryable after a rummage lifecycle.

Pass rummage variable to the view

Let’s start with the simplest: Pagination!

In order to add pagination links to products/index.html.eex, add the following code to the file:

Add pagination link to index.html.eex

Start up a phoenix server and go to the index route. Your page should look somewhat like this:

Rummage Phoenix with Pagination links

Simple enough? For more details about Rummage’s default Pagination hook, click here and to for its HTML support click here.

Next comes: Sort!

In order to add sort links to products/index.html.eex, add the following code to the file:

Add sort links to products index page

In the above example, ci means case insensitive. For more details about Rummage’s default Sort hook, click here and to for its HTML support click here.

Now, going to the index route should look somewhat like this:

Rummage Phoenix Sort

Next comes: Search!

Before adding search, make sure that your controller uses Rummage.Phoenix.Controller:

Use Rummage.Phoenix.Controller

Rummage.Phoenix.Controller is required to sanitize params in a particular way, which is expected by Rummage.Ecto. Think of it like a before_hook which happens between a Rummage.Phoenix passing params to the controller and Rummage.Ecto responding the params. We are planning to make this a configurable feature in future Rummage versions where a developer will be able to provide a custom before_hook before each operation.

In order to add search forms to products/index.html.eex, add the following code to the file:

Add search form to index

In the above example, ci means case insensitive. For more details about Rummage’s default Sort hook, click here and to for its HTML support click here.

For information about different search types, click here.

Now, going to the index route should look somewhat like this:

Rummage Phoenix Search

Just play around with these link and see everything that you can do.

Now that we have added basic Rummage.Phoenix, in the next part we will add associations based HTML to this application.

Previous:

Coming Soon..

  • Searching, Sorting and Pagination with Elixir & Phoenix: Part 4
  • Advanced Rummage: Utilizing the Rummage Search hook
  • Advanced Rummage: Utilizing the Rummage Sort hook
  • Advanced Rummage: Writing a Custom Rummage.Ecto Hook
  • Advanced Rummage: Writing a Custom Rummage.Phoenix HTML helper
  • Using Rummage with other Libraries: Kerosene
  • Using Rummage with other Libraries: Scrivener