ransack 2.3.0 → 4.1.0

data/docs/docs/getting-started/sorting.md

@@ -0,0 +1,71 @@
+---
+title: Sorting
+---
+
+
+# Sorting
+
+## Sorting in the View
+
+You can add a form to capture sorting and filtering options together.
+
+```erb
+# app/views/posts/index.html.erb
+
+<%= search_form_for @q do |f| %>
+  <%= f.label :title_cont %>
+  <%= f.search_field :title_cont %>
+
+  <%= f.submit "Search" %>
+<% end %>
+
+<table>
+  <thead>
+    <tr>
+      <th><%= sort_link(@q, :title, "Title") %></th>
+      <th><%= sort_link(@q, :category, "Category") %></th>
+      <th><%= sort_link(@q, :created_at, "Created at") %></th>
+    </tr>
+  </thead>
+
+  <tbody>
+    <% @posts.each do |post| %>
+      <tr>
+        <td><%= post.title %></td>
+        <td><%= post.category %></td>
+        <td><%= post.created_at.to_s(:long) %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+```
+
+## Sorting in the Controller
+
+To specify a default search sort field + order in the controller `index`:
+
+```ruby
+# app/controllers/posts_controller.rb
+class PostsController < ActionController::Base
+  def index
+    @q = Post.ransack(params[:q])
+    @q.sorts = 'title asc' if @q.sorts.empty?
+
+    @posts = @q.result(distinct: true)
+  end
+end
+```
+
+Multiple sorts can be set by:
+
+```ruby
+# app/controllers/posts_controller.rb
+class PostsController < ActionController::Base
+  def index
+    @q = Post.ransack(params[:q])
+    @q.sorts = ['title asc', 'created_at desc'] if @q.sorts.empty?
+
+    @posts = @q.result(distinct: true)
+  end
+end
+```

data/docs/docs/getting-started/using-predicates.md

@@ -0,0 +1,282 @@
+---
+title: Using Predicates
+---
+
+The primary method of searching in Ransack is by using what is known as *predicates*.
+
+Predicates are used within Ransack search queries to determine what information to
+match. For instance, the `cont` predicate will check to see if an attribute called
+"first_name" contains a value using a wildcard query:
+
+```ruby
+>> User.ransack(first_name_cont: 'Rya').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya%')
+```
+
+You can also combine predicates for OR queries:
+```ruby
+>> User.ransack(first_name_or_last_name_cont: 'Rya').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya%'
+   OR "users"."last_name" LIKE '%Rya%')
+```
+
+The syntax for `OR` queries on an associated model is not immediately obvious, but makes sense. Assuming a `User` `has_one` `Account` and the `Account` has `attributes` `foo` and `bar`:
+
+```ruby
+>> User.ransack(account_foo_or_account_bar_cont: 'val').result.to_sql
+=> SELECT "users".* FROM "users" INNER JOIN accounts ON accounts.user_id = users.id WHERE ("accounts.foo LIKE '%val%' OR accounts.bar LIKE '%val%')
+```
+
+Below is a list of the built-in predicates of Ransack and their opposites. You may already
+be familiar with some of the predicates, as they also exist in the ARel library.
+
+If you want to add your own, please
+see the [[Custom-Predicates|Custom Predicates]] page.
+
+**Please note:** any attempt to use a predicate for an attribute that does not exist will
+*silently fail*. For instance, this will not work when there is no `name` attribute:
+
+```ruby
+>> User.ransack(name_cont: 'Rya').result.to_sql
+=> "SELECT "users".* FROM "users"
+```
+
+## eq (equals)
+
+The `eq` predicate returns all records where a field is *exactly* equal to a given value:
+
+```ruby
+>> User.ransack(first_name_eq: 'Ryan').result.to_sql
+=> SELECT "users".* FROM "users" WHERE "users"."first_name" = 'Ryan'
+```
+
+**Opposite: `not_eq`**
+
+## matches
+
+The `matches` predicate returns all records where a field is like a given value:
+
+```ruby
+>> User.ransack(first_name_matches: 'Ryan').result.to_sql
+=> SELECT "users".* FROM "users" WHERE ("users"."first_name" LIKE 'Ryan')
+```
+
+On Postgres, the case-insensitive ILIKE will be used.
+
+**Opposite: `does_not_match`**
+
+*Note: If you want to do wildcard matching, you may be looking for the `cont`/`not_cont`
+predicates instead.*
+
+## lt (less than)
+
+The `lt` predicate returns all records where a field is less than a given value:
+
+```ruby
+>> User.ransack(age_lt: 25).result.to_sql
+=> SELECT "users".* FROM "users" WHERE ("users"."age" < 25)
+```
+
+**Opposite: `gteq` (greater than or equal to)**
+
+## lteq (less than or equal to)
+
+The `lteq` predicate returns all records where a field is less than *or equal to* a given value:
+
+```ruby
+>> User.ransack(age_lteq: 25).result.to_sql
+=> SELECT "users".* FROM "users" WHERE ("users"."age" <= 25)
+```
+
+**Opposite: `gt` (greater than)**
+
+## in
+
+The `in` predicate returns all records where a field is within a specified list:
+
+```ruby
+>> User.ransack(age_in: 20..25).result.to_sql
+=> SELECT "users".* FROM "users" WHERE "users"."age" IN (20, 21, 22, 23, 24, 25)
+```
+
+It can also take an array:
+
+```ruby
+>> User.ransack(age_in: [20, 21, 22, 23, 24, 25]).result.to_sql
+=> SELECT "users".* FROM "users" WHERE "users"."age" IN (20, 21, 22, 23, 24, 25)
+```
+
+**Opposite: `not_in`**
+
+## cont
+
+The `cont` predicate returns all records where a field contains a given value:
+
+```ruby
+>> User.ransack(first_name_cont: 'Rya').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya%')
+```
+
+**Opposite: `not_cont`**
+
+## cont_any (contains any)
+
+The `cont_any` predicate returns all records where a field contains any of the given values:
+
+```ruby
+>> User.ransack(first_name_cont_any: %w(Rya Lis)).result.to_sql
+=> SELECT "users".* FROM "users"  WHERE (("users"."first_name" LIKE '%Rya%' OR "users"."first_name" LIKE '%Lis%'))
+```
+
+**Opposite: `not_cont_any`**
+
+
+## cont_all (contains all)
+
+The `cont_all` predicate returns all records where a field contains all of the given values:
+
+```ruby
+>> User.ransack(city_cont_all: %w(Grand Rapids)).result.to_sql
+=> SELECT "users".* FROM "users"  WHERE (("users"."city" LIKE '%Grand%' AND "users"."city" LIKE '%Rapids%'))
+```
+
+**Opposite: `not_cont_all`**
+
+
+## i_cont
+
+The `i_cont` case-insensitive predicate returns all records where a field contains a given value and ignores case:
+
+```ruby
+>> User.ransack(first_name_i_cont: 'Rya').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE (LOWER("users"."first_name") LIKE '%rya%')
+```
+
+**Opposite: `not_i_cont`**
+
+## i_cont_any
+
+The `i_cont_any` case-insensitive predicate returns all records where a field contains any of the given values and ignores case:
+
+```ruby
+>> User.ransack(first_name_i_cont_any: %w(Rya Lis)).result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ((LOWER("users"."first_name") LIKE '%rya%' OR LOWER("users"."first_name") LIKE '%lis%'))
+```
+
+**Opposite: `not_i_cont_any`**
+
+
+## i_cont_all
+
+The `i_cont_all` case-insensitive predicate returns all records where a field contains all of the given values and ignores case:
+
+```ruby
+>> User.ransack(city_i_cont_all: %w(Grand Rapids)).result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ((LOWER("users"."city") LIKE '%grand%' AND LOWER("users"."city") LIKE '%rapids%'))
+```
+
+**Opposite: `not_i_cont_all`**
+
+## start (starts with)
+
+The `start` predicate returns all records where a field begins with a given value:
+
+```ruby
+>> User.ransack(first_name_start: 'Rya').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE 'Rya%')
+```
+
+**Opposite: `not_start`**
+
+## end (ends with)
+
+The `end` predicate returns all records where a field ends with a given value:
+
+```ruby
+>> User.ransack(first_name_end: 'yan').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%yan')
+```
+
+**Opposite: `not_end`**
+
+## true
+
+The `true` predicate returns all records where a field is true. The '1' indicates that
+to Ransack that you indeed want to check the truthiness of this field. The other truthy
+values are 'true', 'TRUE', 't' or 'T'.
+
+```ruby
+>> User.ransack(awesome_true: '1').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ("users"."awesome" = 't')
+```
+
+*Note: different database systems use different values to represent truth. In the above
+example, we are using SQLite3.*
+
+**Opposite: `not_true`**
+
+## false
+
+The `false` predicate returns all records where a field is false.
+
+```ruby
+>> User.ransack(awesome_false: '1').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE ("users"."awesome" = 'f')
+```
+
+**Opposite: `not_false`**
+
+*Note: the `false` predicate may be considered the opposite of the `true` predicate if the field does not contain `null` values. Otherwise, use `not_false`.*
+
+## present
+
+The `present` predicate returns all records where a field is present (not null and not a
+blank string).
+
+```ruby
+>> User.ransack(first_name_present: '1').result.to_sql
+=> SELECT "users".* FROM "users"  WHERE (("users"."first_name" IS NOT NULL AND "users"."first_name" != ''))
+```
+
+**Opposite: `blank`**
+
+## null
+
+The `null` predicate returns all records where a field is null:
+
+```ruby
+>> User.ransack(first_name_null: 1).result.to_sql
+=> SELECT "users".* FROM "users"  WHERE "users"."first_name" IS NULL
+```
+
+**Opposite: `not_null`**
+
+# URL parameter structure
+
+The search parameters are passed to ransack as a hash. The URL representation of this hash uses the bracket notation: ```hash_name[key]=value```. The hash_name is the parameter which is defined in the controller, for instance ```q```. The key is the attribute and search predicate compound, for instance ```first_name_cont```, the value is the search parameter. When searching without using the search form helpers this URL structure needs to be created manually.
+
+For example, the URL layout for searching and sorting users could looks like this:
+
+```
+/users.json?q[first_name_cont]=pete&q[last_name_cont]=jack&q[s]=created_at+desc
+```
+
+_Note that the sorting parameter ```s``` is nested within the ```q``` hash._
+
+When using JavaScript to create such a URL, a matching jQuery request could look like this:
+
+```javascript
+$.ajax({
+  url: "/users.json",
+  data: {
+    q: {
+      first_name_cont: "pete",
+      last_name_cont: "jack",
+      s: "created_at desc"
+    }
+  },
+  success: function (data){
+    console.log(data);
+  }
+});
+```

data/docs/docs/going-further/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Going further",
+  "position": 2
+}

data/docs/docs/going-further/acts-as-taggable-on.md

@@ -0,0 +1,114 @@
+---
+title: Acts-as-taggable-on
+sidebar_position: 13
+---
+
+## Using Acts As Taggable On
+
+If you have an `ActiveRecord` model and you're using [acts-as-taggable-on](https://github.com/mbleigh/acts-as-taggable-on),
+chances are you might want to search on tagged fields. Follow the instructions to install the gem and then set up your project files.
+
+### Configure the model
+
+`app/models/tasks.rb`
+
+You can call the tagging field anything you like, it just needs to be plural. No migration is needed as this is stored in the internal ActsAsTaggable tables (`tags` and `taggings`).
+
+```ruby
+class Task < ApplicationRecord
+  acts_as_taggable_on :projects
+end
+```
+
+### Controller
+
+Add a field to strong params in the controller. Use the singular name with `_list`.
+
+`app/controllers/tasks_controller.rb`
+
+```ruby
+def strong_params
+  params
+    .require(:tasks)
+    .permit(:task, :example_field, :project_list)
+```
+
+### Form
+
+We need to `send` the tag fieldname to our model, also using the singular naming.
+
+```erb
+<div class='form-group'>
+  <%= f.label :project_list %>
+  <%= f.text_field :project_list, value: @task.send(:project_list).to_s %>
+ </div>
+```
+
+Now we can collect our data via the form, with tags separated by commas.
+
+## Ransack Search
+
+Imagine you have the following two instances of `Task`:
+
+```ruby
+{ id: 1, name: 'Clean up my room',        projects: [ 'Home', 'Personal' ] }
+{ id: 2, name: 'Complete math exercises', projects: [ 'Homework', 'Study' ] }
+```
+
+When you're writing a `Ransack` search form, you can choose any of the following options:
+
+```erb
+<%= search_form_for @search do |f| %>
+  <%= f.text_field :projects_name_in   %> <!-- option a -->
+  <%= f.text_field :projects_name_eq   %> <!-- option b -->
+  <%= f.text_field :projects_name_cont %> <!-- option c -->
+<% end %>
+```
+
+### Option A - Match keys exactly
+
+Option `A` will match keys exactly. This is the solution to choose if you want to distinguish 'Home' from 'Homework': searching for 'Home' will return just the `Task` with id 1. It also allows searching for more than one tag at once (comma separated):
+- `Home, Personal` will return task 1
+- `Home, Homework` will return task 1 and 2
+
+### Option B - match key combinations
+
+Option `B` will match all keys exactly. This is the solution if you wanna search for specific combinations of tags:
+- `Home` will return nothing, as there is no Task with just the `Home` tag
+- `Home, Personal` will return task 1
+
+### Option C - match substrings
+
+Option `C` is used to match substrings. This is useful when you don't care for the exact tag, but only for part of it:
+- `Home` will return task 1 and 2 (`/Home/` matches both `"Home"` and `"Homework"`)
+
+### Option D - select from a list of tags
+
+In Option `D` we allow the user to select a list of valid tags and then search against them. We use the plural name here.
+
+```erb
+<div class='form-group'>
+  <%= f.label :projects_name, 'Project' %>
+  <%= f.select :projects_name_in, ActsAsTaggableOn::Tag.distinct.order(:name).pluck(:name) %>
+</div>
+```
+
+## Multitenancy 
+
+ActsAsTaggableOn allows scoping of tags based on another field on the model. Suppose we have a `language` field on the model, as an effective second level key. We would adjust our model to look like this:
+
+```ruby
+class Task < ApplicationRecord
+  acts_as_taggable_on :projects
+  acts_as_taggable_tenant :language
+end
+```
+
+The Ransack search is then filtered using the `for_tenant` method
+
+```erb
+<div class='form-group'>
+  <%= f.label :projects_name, 'Project' %>
+  <%= f.select :projects_name_in, ActsAsTaggableOn::Tag.for_tenant('fr').distinct.order(:name).pluck(:name) %>
+</div>
+      

data/docs/docs/going-further/associations.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 1
+title: Associations
+---
+
+### Associations
+
+You can easily use Ransack to search for objects in `has_many` and `belongs_to`
+associations.
+
+Given these associations...
+
+```ruby
+class Employee < ActiveRecord::Base
+  belongs_to :supervisor
+
+  # has attributes first_name:string and last_name:string
+end
+
+class Department < ActiveRecord::Base
+  has_many :supervisors
+
+  # has attribute title:string
+end
+
+class Supervisor < ActiveRecord::Base
+  belongs_to :department
+  has_many :employees
+
+  # has attribute last_name:string
+end
+```
+
+... and a controller...
+
+```ruby
+class SupervisorsController < ApplicationController
+  def index
+    @q = Supervisor.ransack(params[:q])
+    @supervisors = @q.result.includes(:department, :employees)
+  end
+end
+```
+
+... you might set up your form like this...
+
+```erb
+<%= search_form_for @q do |f| %>
+  <%= f.label :last_name_cont %>
+  <%= f.search_field :last_name_cont %>
+
+  <%= f.label :department_title_cont %>
+  <%= f.search_field :department_title_cont %>
+
+  <%= f.label :employees_first_name_or_employees_last_name_cont %>
+  <%= f.search_field :employees_first_name_or_employees_last_name_cont %>
+
+  <%= f.submit "search" %>
+<% end %>
+...
+<%= content_tag :table do %>
+  <%= content_tag :th, sort_link(@q, :last_name) %>
+  <%= content_tag :th, sort_link(@q, :department_title) %>
+  <%= content_tag :th, sort_link(@q, :employees_last_name) %>
+<% end %>
+```
+
+If you have trouble sorting on associations, try using an SQL string with the
+pluralized table (`'departments.title'`,`'employees.last_name'`) instead of the
+symbolized association (`:department_title)`, `:employees_last_name`).

data/docs/docs/going-further/custom-predicates.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+title: Custom predicates
+---
+
+If you'd like to add your own custom Ransack predicates:
+
+```ruby
+# config/initializers/ransack.rb
+
+Ransack.configure do |config|
+  config.add_predicate 'equals_diddly', # Name your predicate
+    # What non-compound ARel predicate will it use? (eq, matches, etc)
+    arel_predicate: 'eq',
+    # Format incoming values as you see fit. (Default: Don't do formatting)
+    formatter: proc { |v| "#{v}-diddly" },
+    # Validate a value. An "invalid" value won't be used in a search.
+    # Below is default.
+    validator: proc { |v| v.present? },
+    # Should compounds be created? Will use the compound (any/all) version
+    # of the arel_predicate to create a corresponding any/all version of
+    # your predicate. (Default: true)
+    compounds: true,
+    # Force a specific column type for type-casting of supplied values.
+    # (Default: use type from DB column)
+    type: :string,
+    # Use LOWER(column on database).
+    # (Default: false)
+    case_insensitive: true
+end
+```
+You can check all Arel predicates [here](https://github.com/rails/rails/blob/main/activerecord/lib/arel/predications.rb).
+
+If Arel does not have the predicate you are looking for, consider monkey patching it:
+
+```ruby
+# config/initializers/ransack.rb
+
+module Arel
+  module Predications
+    def gteq_or_null(other)
+      left = gteq(other)
+      right = eq(nil)
+      left.or(right)
+    end
+  end
+end
+
+Ransack.configure do |config|
+  config.add_predicate 'gteq_or_null', arel_predicate: 'gteq_or_null'
+end
+```

data/docs/docs/going-further/documentation.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 11
+title: Documentation
+---
+
+Ransack uses [Docusaurus](https://docusaurus.io/) for documentation. To contribute to the docs simply use the "Edit this page" link from any page to directly edit, or else pull the repo and edit locally.
+
+### Local Development
+
+Switch to docs folder
+
+```
+cd docs
+```
+
+Install docusaurus and other dependencies
+
+```
+yarn install
+```
+
+
+Start a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
+
+```
+yarn start
+```
+
+### Build
+
+```
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+USE_SSH=true yarn deploy
+```

data/docs/docs/going-further/exporting-to-csv.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 2
+title: CSV Export
+---
+
+Exporting to CSV
+
+Example downloading a csv file preserving ransack search, based on [this gist](https://gist.github.com/pama/adff25ed1f4b796ce088ea362a08e1c5)
+
+```ruby title='index.html.erb'
+<h1>Users</h1>
+
+<%= search_form_for @q, url: dashboard_index_path do |f| %>
+  <%= f.label :name_cont %>
+  <%= f.search_field :name_cont %>
+
+  <%= f.submit %>
+<% end %>
+
+<ul>
+  <% @users.each do |user| %>
+    <li><%= user.name %> [<%= user.devices.map {|device| device.name }.join(', ') %>]</li>
+  <% end %>
+</ul>
+
+<% if params[:q] %>
+  <%= link_to 'Export 1', dashboard_index_path({name: params[:q][:name_cont]}.merge({format: :csv})) %>
+<% else %>
+  <%= link_to 'Export 2', dashboard_index_path(format: 'csv') %>
+<% end %>
+```
+
+```ruby title='user.rb'
+require 'csv'
+
+class User < ApplicationRecord
+  has_many :devices
+
+  def self.get_csv(users)
+    CSV.generate do |csv|
+      csv << ["Name", "Devices"]
+
+      users.each do |user|
+        csv << [user.name, user.devices.map{|device| device.name}.join(', ')]
+      end
+    end
+  end
+end
+```