ransack 2.6.0 → 3.0.0

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: '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/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,31 @@
+---
+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
+
+```
+cd docs
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### 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)
+
+```jsx 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 %>
+```
+
+```jsx 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
+```

data/docs/docs/going-further/external-guides.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 9
+title: External resources
+---
+
+There is a plethora of material on Ransack around the internet. We've collected some here for your convenience.
+
+Do you want to have a blog post or other content on Ransack highlighted? Please just edit the page, add your content and a Pull Request will be sent to Ransack maintainers for approval.
+
+# Screencasts
+
+- [DriftingRuby: Ransack Search and Hotwire](https://www.driftingruby.com/episodes/ransack-search-and-hotwire)
+- [GoRails: Forum Series Part 6: Search with Ransack](https://gorails.com/episodes/forum-search-with-ransack)
+- [Railscast 370 - Ransack](http://railscasts.com/episodes/370-ransack)
+- [Search And Sort Ransack Associations With The Rails Ransack Gem | Ruby On Rails 6 Ransack Tutorial](https://www.youtube.com/watch?v=rtg-5EXwpbg)
+
+
+# Gems
+
+- [ActiveAdmin](https://activeadmin.info/) The Administration Framework for Rails **_uses Ransack internally_**
+- [Ransack Memory](https://github.com/richardrails/ransack_memory) Automatically save and load Ransack's filtered params into the Rail's session
+- [Mobility Ransack](https://github.com/shioyama/mobility-ransack) Search attributes translated by Mobility with Ransack.
+- [Ransack UI](https://github.com/ndbroadbent/ransack_ui) Framework for building a search UI with Ransack **_seems abandoned_**
+
+# Blogs
+
+- [Search And Sort In Ruby On Rails 6 With The Ransack Gem](https://deanin.com/blog/ransack/)
+- [Implement Ransack Gem in Ruby on Rails](https://www.botreetechnologies.com/blog/implementing-advanced-search-in-ruby-on-rails-with-ransack/)
+- [Searching and Sorting with Ransack](https://jaspercurry.medium.com/searching-and-sorting-on-rails-with-ransack-560e862e650a)
+- [How to Build Your Own ActiveAdmin Filters with Ransack](https://www.viget.com/articles/how-to-build-your-own-filters-with-ransack/)
+- [Avoid Ransack's N+1 Pitfall!](https://dev.to/husteadrobert/avoid-ransacks-n1-pitfall-33of)
+- [Filter and paging with Kaminari](https://gist.github.com/MyklClason/e4dc96fd0e009b7b3a9c84ddbb1e11d2)
+- [Pagination for Ransack Forms](https://nicholaide.github.io/ransack/2016/11/26/ransack-pagination.html)
+- [AJAX Search, Sort, Paginate with Ransack and Kaminari](https://techbrownbags.wordpress.com/2014/01/17/rails-ajax-search-sort-paginate-with-ransack-kaminari/)
+- [Searching with Ransack in Ruby on Rails](http://blog.magmalabs.io/2019/03/12/searching-with-ransack-in-ruby-on-rails.html)
+- [Role scopes with gem Ransack](https://blog.corsego.com/rolify-scopes)
+- [Searching and Sorting with Ransack](https://www.mintbit.com/blog/searching-and-sorting-with-ransack)
+- [Using custom scopes with Ransack gem in Rails](https://profilehunt.net/blog/using-custom-scopes-with-ransack-in-rails)
+- [Query Date Range With Ransack](https://lingceng.github.io/blog/2015/12/28/query-date-range-with-ransack/)
+- [ransack vs searchkick: Building a search feature in Rails](https://www.cookieshq.co.uk/posts/ransack-vs-searchkick-building-a-search-feature-in-rails)
+- [Using ransack and delegate in Rails](https://huangwenwei.com/blogs/using-ransack-and-delegate-in-rails)
+- [Using Ransack as a Search Engine](https://medium.com/@jelaniwoods/using-ransack-as-a-search-engine-92e002a68da)
+- [Advanced Search with Ransack](https://www.sitepoint.com/advanced-search-ransack/)
+- [Sort a table of records in Rails with Ransack](https://alankydd.wordpress.com/2012/03/12/sort-a-table-of-records-in-rails-with-ransack/)
+- [Ransack: Search with Multiple Checkboxes (Rails)](https://iamjosh.wordpress.com/2014/03/07/ransack-search-with-multiple-checkboxes/)
+- [Rails : Ransack : Sorting data by ratings](https://cbabhusal.wordpress.com/2017/01/03/rails-ransack-sorting-data-by-ratings/)
+- [Setting Up Rails 5 API Only App with ActiveAdmin enabled](https://rrott.com/blog/ror/rails-5-api-with-activeadmin-integration/)
+- [Ransack, the library formerly known as MetaSearch 2.0](https://ernie.io/2011/04/01/ransack-the-library-formerly-known-as-metasearch-2-0/) **_some Ransack history_**
+
+## In French
+
+- [Faciliter les recherches avec Ransack](https://www.synbioz.com/blog/tech/faciliter-les-recherches-avec-ransack)
+
+## In Vietnamese
+
+- [Ransack - công cụ tuyệt vời giúp tìm kiếm và sắp xếp dữ liệu đơn giản hơn
+](https://nddblog.com/posts/ransack-cong-cu-tuyet-voi-giup-tim-kiem-va-sap-xep-du-lieu-don-gian-hon)

data/docs/docs/going-further/form-customisation.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 4
+title: Form customisation
+---
+
+Predicate and attribute labels in forms may be specified with I18n in a translation file (see the locale files in [Ransack::Locale](https://github.com/activerecord-hackery/ransack/activerecord-hackery/ransack/tree/master/lib/ransack/locale) for more examples):
+
+```yml
+# locales/en.yml
+en:
+  ransack:
+    asc: ascending
+    desc: descending
+    predicates:
+      cont: contains
+      not_cont: not contains
+      start: starts with
+      end: ends with
+      gt: greater than
+      lt: less than
+    attributes:
+      person:
+        name: Full Name
+      article:
+        title: Article Title
+        body: Main Content
+```
+The names of attribute fields may also be changed globally or under activerecord:
+
+```yml
+# locales/en.yml
+en:
+  attributes:
+    model_name:
+      model_field1: field name1
+      model_field2: field name2
+  activerecord:
+    attributes:
+      namespace/article:
+        title: AR Namespaced Title
+      namespace_article:
+        title: Old Ransack Namespaced Title
+```
+
+To limit the predicates in the `predicate_select` form helper in a view template, pass an array of permitted predicates with `only`:
+
+```erb
+<%= f.predicate_select only: %i(cont not_cont eq not_eq blank null) %>
+```
+
+Compound predicates (`_any` & `_all`) may be removed by passing the option `compounds: false`.
+
+```erb
+<%= f.predicate_select compounds: false %>
+```
+
+Searchable attributes versus non-searchable ones may be specified as follows:
+
+```ruby
+def self.ransackable_attributes(auth_object = nil)
+  %w(searchable_attribute_1 searchable_attribute_2 ...) + _ransackers.keys
+end
+```

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

@@ -0,0 +1,53 @@
+---
+sidebar_position: 3
+title: i18n
+---
+
+# i18n and Ransack
+
+Ransack translation files are available in
+[Ransack::Locale](https://github.com/activerecord-hackery/ransack/lib/ransack/locale). You may also be interested in one of the
+many translations for Ransack available at
+http://www.localeapp.com/projects/2999.
+
+Predicate and attribute translations in forms may be specified as follows (see
+the translation files in [Ransack::Locale](https://github.com/activerecord-hackery/ransack/lib/ransack/locale) for more examples):
+
+locales/en.yml:
+```yml
+en:
+  ransack:
+    asc: ascending
+    desc: descending
+    predicates:
+      cont: contains
+      not_cont: not contains
+      start: starts with
+      end: ends with
+      gt: greater than
+      lt: less than
+    models:
+      person: Passanger
+    attributes:
+      person:
+        name: Full Name
+      article:
+        title: Article Title
+        body: Main Content
+```
+
+Attribute names may also be changed globally, or under `activerecord`:
+
+```yml
+en:
+  attributes:
+    model_name:
+      model_field1: field name1
+      model_field2: field name2
+  activerecord:
+    attributes:
+      namespace/article:
+        title: AR Namespaced Title
+      namespace_article:
+        title: Old Ransack Namespaced Title
+```