Getting Started

Installation

Refine is primarily meant to be installed within a Rails project (>= 6.0) using Webpack or EsBuild. You are welcome to install in other setups as you are able.

Add the gem to your Gemfile:

gem "refine-rails"

Add the npm package:

yarn add @clickfunnels/refine-stimulus

Run bundle and yarn

Import the Stimulus Controllers to your application. Typically this is in app/javascript/controllers/index.js

import { controllerDefinitions as refineControllers } from "@clickfunnels/refine-stimulus"
application.load(refineControllers)

Add jquery (necessary for our custom select elements)

yarn add jquery

Add to index.js or the appropriate place in your application

import jquery from 'jquery'
window.jQuery = jquery
window.$ = jquery

Implement a Filter class in app/filters that inherits from Refine::Filter or use the generator.

rails generate filter contact name:text created_at:date id:numeric

Use this class to define the conditions that can be filtered. Example (Contacts Filter on a Contact Model)

# app/filters/contacts_filter.rb
class ContactsFilter < Refine::Filter
  include Refine::Conditions
  @@default_stabilizer = Refine::Stabilizers::UrlEncodedStabilizer

  def initial_query
    Contact.all
  end

  def conditions
    [
      TextCondition.new("name"),
      DateCondition.new("created_at"),
      NumericCondition.new("id"),
    ]
  end
end

Apply the filter in your contacts_controller.

# contacts_controller.rb
  def index
    # Sets refine filter
    apply_filter(ContactsFilter, initial_query: (Contact.sort_by_params(params[:sort], sort_direction)))
    @pagy, @contacts = pagy(@refine_filter.get_query)
 
    # Uncomment to authorize with Pundit
    # authorize @contacts
  end

Add the following to your view to render a button that activates the filter. In the example above it would be in contacts/index.

<%= render partial: '/filter_builder_dropdown' %>

You should see a working filter

Optional

If you are using Tailwind v3 and want to use the provided styles, import the stylesheet in your application. Typically this is in app/assets/stylesheets/application.tailwind.css

@import '@clickfunnels/refine-stimulus/app/assets/stylesheets/index.tailwind.css';