ransack 2.6.0 → 3.0.0

data/docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

data/docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

data/docs/blog/2022-03-27-ransack-3.0.0.md

@@ -0,0 +1,20 @@
+---
+slug: ransack-3-0-0
+title: Ransack 3.0.0
+authors:
+  name: Sean Carroll
+  title: Ransack Core Team
+tags: [ransack, release]
+---
+
+Ransack has been a part of many Rubyists toolboxes for years and 3.0.0 is a major release. We have a number of new features and one breaking change. As part of 3.0.0, we decided to launch this documentation website, merging in the Wiki and the content from the README.
+
+With 3.0.0 we are hoping to re-energise the community, we need help on closing out old issues, refactoring the codebase and even some design work.
+
+I also wanted to let you know that Ernie Miller (creator of Ransack) has decided to leave the project completely, he has this message for the community:
+
+> While my own personal development efforts have been spent elsewhere as of late, I'm keenly aware of how many people still depend on some of the software I originally wrote all those years ago.
+
+> That's why I'm grateful to be able to step away from the ActiveRecord Hackery organization (and, specifically, maintenance of Ransack) without impacting those users. I'm thankful that Sean, David, Greg, and others will continue to support users, and wish them the best as they move forward without me!
+
+Please join me in thanking Ernie for bringing Ransack to life, I personally think it is one of the most amazing Rails libraries out there.

data/docs/docs/getting-started/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Getting started",
+  "position": 2
+}

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

@@ -0,0 +1,46 @@
+---
+sidebar_position: 2
+title: Advanced Mode
+---
+
+
+"Advanced" searches Rails's nested attributes functionality in order to
+generate complex queries with nested AND/OR groupings, etc. This takes a bit
+more work but can generate some pretty cool search interfaces that put a lot of
+power in the hands of your users.
+
+A notable drawback with these searches is
+that the increased size of the parameter string will typically force you to use
+the HTTP POST method instead of GET.
+
+
+## Tweak your routes
+
+```ruby
+resources :people do
+  collection do
+    match 'search' => 'people#search', via: [:get, :post], as: :search
+  end
+end
+```
+
+## Add a controller action
+
+```ruby
+def search
+  index
+  render :index
+end
+```
+
+## Update your form
+
+```erb
+<%= search_form_for @q, url: search_people_path,
+                        html: { method: :post } do |f| %>
+```
+
+Once you've done so, you can make use of the helpers in [Ransack::Helpers::FormBuilder](https://github.com/activerecord-hackery/ransack/lib/ransack/helpers/form_builder.rb) to
+construct much more complex search forms, such as the one on the
+[demo app](http://ransack-demo.herokuapp.com/users/advanced_search)
+(source code [here](https://github.com/activerecord-hackery/ransack_demo)).

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

@@ -0,0 +1,47 @@
+---
+sidebar_position: 3
+title: Configuration
+---
+
+
+
+Ransack may be easily configured. The best place to put configuration is in an initializer file at `config/initializers/ransack.rb`, containing code such as:
+
+```ruby
+Ransack.configure do |config|
+
+  # Change default search parameter key name.
+  # Default key name is :q
+  config.search_key = :query
+
+  # Raise errors if a query contains an unknown predicate or attribute.
+  # Default is true (do not raise error on unknown conditions).
+  config.ignore_unknown_conditions = false
+
+  # Globally display sort links without the order indicator arrow.
+  # Default is false (sort order indicators are displayed).
+  # This can also be configured individually in each sort link (see the README).
+  config.hide_sort_order_indicators = true
+
+end
+```
+
+## Custom search parameter key name
+
+Sometimes there are situations when the default search parameter name cannot be used, for instance,
+if there are two searches on one page. Another name may be set using the `search_key` option in the `ransack` or `search` methods in the controller, and in the `@search_form_for` method in the view.
+
+### In the controller
+
+```ruby
+@search = Log.ransack(params[:log_search], search_key: :log_search)
+# or
+@search = Log.search(params[:log_search], search_key: :log_search)
+```
+
+### In the view
+
+```erb
+<%= f.search_form_for @search, as: :log_search %>
+<%= sort_link(@search) %>
+```

data/docs/docs/getting-started/search-matches.md

@@ -0,0 +1,67 @@
+---
+title: Search Matchers
+---
+
+### Search Matchers
+
+List of all possible predicates
+
+
+| Predicate | Description | Notes |
+| ------------- | ------------- |-------- |
+| `*_eq`  | equal  | |
+| `*_not_eq` | not equal | |
+| `*_matches` | matches with `LIKE` | e.g. `q[email_matches]=%@gmail.com`|
+| `*_does_not_match` | does not match with `LIKE` | |
+| `*_matches_any` | Matches any | |
+| `*_matches_all` | Matches all  | |
+| `*_does_not_match_any` | Does not match any | |
+| `*_does_not_match_all` | Does not match all | |
+| `*_lt` | less than | |
+| `*_lteq` | less than or equal | |
+| `*_gt` | greater than | |
+| `*_gteq` | greater than or equal | |
+| `*_present` | not null and not empty | Only compatible with string columns. Example: `q[name_present]=1` (SQL: `col is not null AND col != ''`) |
+| `*_blank` | is null or empty. | (SQL: `col is null OR col = ''`) |
+| `*_null` | is null | |
+| `*_not_null` | is not null | |
+| `*_in` | match any values in array | e.g. `q[name_in][]=Alice&q[name_in][]=Bob` |
+| `*_not_in` | match none of values in array | |
+| `*_lt_any` | Less than any |  SQL: `col < value1 OR col < value2` |
+| `*_lteq_any` | Less than or equal to any | |
+| `*_gt_any` | Greater than any | |
+| `*_gteq_any` | Greater than or equal to any | |
+| `*_lt_all` | Less than all | SQL: `col < value1 AND col < value2` |
+| `*_lteq_all` | Less than or equal to all | |
+| `*_gt_all` | Greater than all | |
+| `*_gteq_all` | Greater than or equal to all | |
+| `*_not_eq_all` | none of values in a set | |
+| `*_start` | Starts with | SQL: `col LIKE 'value%'` |
+| `*_not_start` | Does not start with | |
+| `*_start_any` | Starts with any of | |
+| `*_start_all` | Starts with all of | |
+| `*_not_start_any` | Does not start with any of | |
+| `*_not_start_all` | Does not start with all of | |
+| `*_end` | Ends with | SQL: `col LIKE '%value'` |
+| `*_not_end` | Does not end with | |
+| `*_end_any` | Ends with any of | |
+| `*_end_all` | Ends with all of | |
+| `*_not_end_any` | | |
+| `*_not_end_all` | | |
+| `*_cont` | Contains value | uses `LIKE` |
+| `*_cont_any` | Contains any of | |
+| `*_cont_all` | Contains all of | |
+| `*_not_cont` | Does not contain |
+| `*_not_cont_any` | Does not contain any of | |
+| `*_not_cont_all` | Does not contain all of | |
+| `*_i_cont` | Contains value with case insensitive | uses `ILIKE` |
+| `*_i_cont_any` | Contains any of values with case insensitive | |
+| `*_i_cont_all` | Contains all of values with case insensitive | |
+| `*_not_i_cont` | Does not contain with case insensitive |
+| `*_not_i_cont_any` | Does not contain any of values with case insensitive | |
+| `*_not_i_cont_all` | Does not contain all of values with case insensitive | |
+| `*_true` | is true | |
+| `*_false` | is false | |
+
+
+See full list: https://github.com/activerecord-hackery/ransack/blob/master/lib/ransack/locale/en.yml#L15 

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

@@ -0,0 +1,284 @@
+---
+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
+
+```jsx
+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):
+
+```jsx
+def index
+  @q = Person.ransack(params[:q])
+  @people = @q.result.includes(:articles).page(params[:page])
+end
+```
+
+### 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`):
+
+```jsx
+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:
+
+```jsx
+Ransack.configure do |c|
+  # Change whitespace stripping behaviour.
+  # 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/lib/ransack/helpers/form_helper.rb).
+
+### Form helper
+
+Ransack's `search_form_for` helper replaces `form_for` for creating the view search form
+
+```jsx
+<%= 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:
+
+```jsx
+<%= 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
+
+```jsx
+<%= 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:
+
+```jsx
+<%= 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:
+
+```jsx
+<%= 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)):
+
+```jsx
+<%= 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:
+
+```jsx
+<%= 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:
+
+```jsx
+<%= 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:
+
+```jsx
+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:
+
+```jsx
+<%= 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:
+
+```jsx
+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:
+
+```jsx
+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:
+
+```jsx
+<%= 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`:
+
+```jsx
+<%= sort_url(@q, :name, default_order: :desc) %>
+```
+
+```jsx
+<%= sort_url(@q, :last_name, [:last_name, 'first_name asc']) %>
+```
+
+```jsx
+<%= 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:
+
+```jsx
+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
+
+```jsx
+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:
+
+```jsx
+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
+```
+
+```jsx
+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

@@ -0,0 +1,79 @@
+---
+title: Sorting
+---
+
+
+# Sorting
+
+## Sorting in the View
+
+You can add a form to capture sorting and filtering options together.
+
+```jsx
+<div class="filters" id="filtersSidebar">
+  <header class="filters-header">
+    <div class="filters-header-content">
+      <h3>Filters</h3>
+    </div>
+  </header>
+
+  <div class="filters-content">
+    <%= search_form_for @q,
+          class: 'form',
+          url: articles_path,
+          html: { autocomplete: 'off', autocapitalize: 'none' } do |f| %>
+
+      <div class="form-group">
+        <%= f.label :title_cont, t('Filter_by_keyword') %>
+        <%= f.search_field :title_cont %>
+      </div>
+
+      <%= render partial: 'filters/date_title_sort', locals: { f: f } %>
+
+      <div class="form-group">
+        <%= f.label :grade_level_gteq, t('Grade_level') %> >=
+        <%= f.search_field :grade_level_gteq  %>
+      </div>
+
+      <div class="form-group">
+        <%= f.label :readability_gteq, t('Readability') %> >=
+        <%= f.search_field :readability_gteq  %>
+      </div>
+
+      <div class="form-group">
+        <i><%= @articles.total_count %> articles</i>
+      </div>
+
+      <div class="form-group">
+        <hr/>
+        <div class="filters-header-content">
+          <%= link_to request.path, class: 'form-link' do %>
+            <i class="far fa-undo icon-l"></i><%= t('Clear_all') %>
+          <% end %>
+
+          <%= f.submit t('Filter'), class: 'btn btn-primary' %>
+        </div>
+      </div>    
+    <% end %>
+  </div>
+</div>
+```
+
+
+## Sorting in the Controller
+
+To specify a default search sort field + order in the controller `index`:
+
+```ruby
+@search = Post.ransack(params[:q])
+@search.sorts = 'name asc' if @search.sorts.empty?
+@posts = @search.result.paginate(page: params[:page], per_page: 20)
+```
+
+Multiple sorts can be set by:
+
+```ruby
+@search = Post.ransack(params[:q])  
+@search.sorts = ['name asc', 'created_at desc'] if @search.sorts.empty?
+@posts = @search.result.paginate(page: params[:page], per_page: 20)
+```