ransack 4.1.1 → 4.4.0

data/docs/docs/getting-started/simple-mode.md

@@ -1,288 +0,0 @@
----
-sidebar_position: 1
-title: Simple mode
----
-
-# Simple Mode
-
-Ransack can be used in one of two modes, simple or advanced. For
-searching/filtering not requiring complex boolean logic, Ransack's simple
-mode should meet your needs.
-
-## In your controller
-
-```ruby
-def index
-  @q = Person.ransack(params[:q])
-  @people = @q.result(distinct: true)
-end
-```
-or without `distinct: true`, for sorting on an associated table's columns (in
-this example, with preloading each Person's Articles and pagination):
-
-```ruby
-def index
-  @q = Person.ransack(params[:q])
-  @people = @q.result.includes(:articles).page(params[:page])
-end
-```
-
-:::caution
-By default, searching and sorting are authorized on any column of your model. See [Authorization (allowlisting/denylisting)](/going-further/other-notes.md#authorization-allowlistingdenylisting) on how to prevent this.
-:::
-
-### Default search options
-
-#### Search parameter
-
-Ransack uses a default `:q` param key for search params. This may be changed by
-setting the `search_key` option in a Ransack initializer file (typically
-`config/initializers/ransack.rb`):
-
-```ruby
-Ransack.configure do |c|
-  # Change default search parameter key name.
-  # Default key name is :q
-  c.search_key = :query
-end
-```
-
-#### String search
-
-After version 2.4.0 when searching a string query Ransack by default strips all whitespace around the query string.
-This may be disabled by setting the `strip_whitespace` option in a Ransack initializer file:
-
-```ruby
-Ransack.configure do |c|
-  # Change whitespace stripping behavior.
-  # Default is true
-  c.strip_whitespace = false
-end
-```
-
-## In your view
-
-The two primary Ransack view helpers are `search_form_for` and `sort_link`,
-which are defined in
-[Ransack::Helpers::FormHelper](https://github.com/activerecord-hackery/ransack/blob/main/lib/ransack/helpers/form_helper.rb).
-
-### Form helper
-
-Ransack's `search_form_for` helper replaces `form_for` for creating the view search form
-
-```erb
-<%= search_form_for @q do |f| %>
-
-  # Search if the name field contains...
-  <%= f.label :name_cont %>
-  <%= f.search_field :name_cont %>
-
-  # Search if an associated articles.title starts with...
-  <%= f.label :articles_title_start %>
-  <%= f.search_field :articles_title_start %>
-
-  # Attributes may be chained. Search multiple attributes for one value...
-  <%= f.label :name_or_description_or_email_or_articles_title_cont %>
-  <%= f.search_field :name_or_description_or_email_or_articles_title_cont %>
-
-  <%= f.submit %>
-<% end %>
-```
-
-The argument of `f.search_field` has to be in this form:
- `attribute_name[_or_attribute_name]..._predicate`
-
-where `[_or_another_attribute_name]...` means any repetition of `_or_` plus the name of the attribute.
-
-`cont` (contains) and `start` (starts with) are just two of the available
-search predicates.
-
-The `search_form_for` answer format can be set like this:
-
-```erb
-<%= search_form_for(@q, format: :pdf) do |f| %>
-
-<%= search_form_for(@q, format: :json) do |f| %>
-```
-
-### Search link helper
-
-Ransack's `sort_link` helper creates table headers that are sortable links
-
-```erb
-<%= sort_link(@q, :name) %>
-```
-Additional options can be passed after the column parameter, like a different
-column title or a default sort order.
-
-If the first option after the column parameter is a String, it's considered a
-custom label for the link:
-
-```erb
-<%= sort_link(@q, :name, 'Last Name', default_order: :desc) %>
-```
-
-You can use a block if the link markup is hard to fit into the label parameter:
-
-```erb
-<%= sort_link(@q, :name) do %>
-  <strong>Player Name</strong>
-<% end %>
-```
-
-With a polymorphic association, you may need to specify the name of the link
-explicitly to avoid an `uninitialized constant Model::Xxxable` error (see issue
-[#421](https://github.com/activerecord-hackery/ransack/issues/421)):
-
-```erb
-<%= sort_link(@q, :xxxable_of_Ymodel_type_some_attribute, 'Attribute Name') %>
-```
-
-If the first option after the column parameter and/or the label parameter is an
-Array, it will be used for sorting on multiple fields:
-
-```erb
-<%= sort_link(@q, :last_name, [:last_name, 'first_name asc'], 'Last Name') %>
-```
-
-In the example above, clicking the link will sort by `last_name` and then
-`first_name`. Specifying the sort direction on a field in the array tells
-Ransack to _always_ sort that particular field in the specified direction.
-
-Multiple `default_order` fields may also be specified with a trailing options
-Hash:
-
-```erb
-<%= sort_link(@q, :last_name, %i(last_name first_name),
-  default_order: { last_name: 'asc', first_name: 'desc' }) %>
-```
-
-This example toggles the sort directions of both fields, by default
-initially sorting the `last_name` field by ascending order, and the
-`first_name` field by descending order.
-
-In the case that you wish to sort by some complex value, such as the result
-of a SQL function, you may do so using scopes. In your model, define scopes
-whose names line up with the name of the virtual field you wish to sort by,
-as so:
-
-```ruby
-class Person < ActiveRecord::Base
-  scope :sort_by_reverse_name_asc, lambda { order("REVERSE(name) ASC") }
-  scope :sort_by_reverse_name_desc, lambda { order("REVERSE(name) DESC") }
-...
-```
-
-and you can then sort by this virtual field:
-
-```erb
-<%= sort_link(@q, :reverse_name) %>
-```
-
-The trailing options Hash can also be used for passing additional options to the
-generated link, like `class:`.
-
-The sort link order indicator arrows may be globally customized by setting a
-`custom_arrows` option in an initializer file like
-`config/initializers/ransack.rb`.
-
-You can also enable a `default_arrow` which is displayed on all sortable fields
-which are not currently used in the sorting. This is disabled by default so
-nothing will be displayed:
-
-```ruby
-Ransack.configure do |c|
-  c.custom_arrows = {
-    up_arrow: '<i class="custom-up-arrow-icon"></i>',
-    down_arrow: 'U+02193',
-    default_arrow: '<i class="default-arrow-icon"></i>'
-  }
-end
-```
-
-All sort links may be displayed without the order indicator
-arrows by setting `hide_sort_order_indicators` to true in the initializer file.
-Note that this hides the arrows even if they were customized:
-
-```ruby
-Ransack.configure do |c|
-  c.hide_sort_order_indicators = true
-end
-```
-
-Without setting it globally, individual sort links may be displayed without
-the order indicator arrow by passing `hide_indicator: true` in the sort link:
-
-```erb
-<%= sort_link(@q, :name, hide_indicator: true) %>
-```
-
-### sort_url
-
-Ransack's `sort_url` helper is like a `sort_link` but returns only the url
-
-`sort_url` has the same API as `sort_link`:
-
-```erb
-<%= sort_url(@q, :name, default_order: :desc) %>
-```
-
-```erb
-<%= sort_url(@q, :last_name, [:last_name, 'first_name asc']) %>
-```
-
-```erb
-<%= sort_url(@q, :last_name, %i(last_name first_name),
-  default_order: { last_name: 'asc', first_name: 'desc' }) %>
-```
-
-### PostgreSQL's sort option
-
-The `NULLS FIRST` and `NULLS LAST` options can be used to determine whether nulls appear before or after non-null values in the sort ordering.
-
-You may want to configure it like this:
-
-```ruby
-Ransack.configure do |c|
-  c.postgres_fields_sort_option = :nulls_first # or :nulls_last
-end
-```
-
-To treat nulls as having the lowest or highest value respectively. To force nulls to always be first or last, use
-
-```ruby
-Ransack.configure do |c|
-  c.postgres_fields_sort_option = :nulls_always_first # or :nulls_always_last
-end
-```
-
-See this feature: https://www.postgresql.org/docs/13/queries-order.html
-
-#### Case Insensitive Sorting in PostgreSQL
-
-In order to request PostgreSQL to do a case insensitive sort for all string columns of a model at once, Ransack can be extended by using this approach:
-
-```ruby
-module RansackObject
-
-  def self.included(base)
-    base.columns.each do |column|
-      if column.type == :string
-        base.ransacker column.name.to_sym, type: :string do
-          Arel.sql("lower(#{base.table_name}.#{column.name})")
-        end
-      end
-    end
-  end
-end
-```
-
-```ruby
-class UserWithManyAttributes < ActiveRecord::Base
-  include RansackObject
-end
-```
-
-If this approach is taken, it is advisable to [add a functional index](https://www.postgresql.org/docs/13/citext.html).
-
-This was originally asked in [a Ransack issue](https://github.com/activerecord-hackery/ransack/issues/1201) and a solution was found on [Stack Overflow](https://stackoverflow.com/a/34677378).

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

@@ -1,71 +0,0 @@
----
-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

@@ -1,282 +0,0 @@
----
-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

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