ransack 3.0.0 → 4.0.0

data/docs/.gitignore

@@ -15,6 +15,5 @@
 .env.test.local
 .env.production.local
 
-npm-debug.log*
 yarn-debug.log*
 yarn-error.log*

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

@@ -40,7 +40,7 @@ end
                         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
+Once you've done so, you can make use of the helpers in [Ransack::Helpers::FormBuilder](https://github.com/activerecord-hackery/ransack/blob/main/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/search-matches.md

@@ -64,4 +64,4 @@ List of all possible predicates
 | `*_false` | is false | |
 
 
-See full list: https://github.com/activerecord-hackery/ransack/blob/master/lib/ransack/locale/en.yml#L15 
+See full list: https://github.com/activerecord-hackery/ransack/blob/main/lib/ransack/locale/en.yml#L16

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

@@ -11,7 +11,7 @@ mode should meet your needs.
 
 ## In your controller
 
-```jsx
+```ruby
 def index
   @q = Person.ransack(params[:q])
   @people = @q.result(distinct: true)
@@ -20,13 +20,17 @@ 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
+```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
@@ -35,7 +39,7 @@ 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
+```ruby
 Ransack.configure do |c|
   # Change default search parameter key name.
   # Default key name is :q
@@ -48,9 +52,9 @@ end
 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
+```ruby
 Ransack.configure do |c|
-  # Change whitespace stripping behaviour.
+  # Change whitespace stripping behavior.
   # Default is true
   c.strip_whitespace = false
 end
@@ -60,13 +64,13 @@ end
 
 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).
+[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
 
-```jsx
+```erb
 <%= search_form_for @q do |f| %>
 
   # Search if the name field contains...
@@ -95,7 +99,7 @@ search predicates.
 
 The `search_form_for` answer format can be set like this:
 
-```jsx
+```erb
 <%= search_form_for(@q, format: :pdf) do |f| %>
 
 <%= search_form_for(@q, format: :json) do |f| %>
@@ -105,7 +109,7 @@ The `search_form_for` answer format can be set like this:
 
 Ransack's `sort_link` helper creates table headers that are sortable links
 
-```jsx
+```erb
 <%= sort_link(@q, :name) %>
 ```
 Additional options can be passed after the column parameter, like a different
@@ -114,13 +118,13 @@ 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
+```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:
 
-```jsx
+```erb
 <%= sort_link(@q, :name) do %>
   <strong>Player Name</strong>
 <% end %>
@@ -130,14 +134,14 @@ 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
+```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:
 
-```jsx
+```erb
 <%= sort_link(@q, :last_name, [:last_name, 'first_name asc'], 'Last Name') %>
 ```
 
@@ -148,7 +152,7 @@ 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
+```erb
 <%= sort_link(@q, :last_name, %i(last_name first_name),
   default_order: { last_name: 'asc', first_name: 'desc' }) %>
 ```
@@ -162,7 +166,7 @@ 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
+```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") }
@@ -171,7 +175,7 @@ class Person < ActiveRecord::Base
 
 and you can then sort by this virtual field:
 
-```jsx
+```erb
 <%= sort_link(@q, :reverse_name) %>
 ```
 
@@ -186,7 +190,7 @@ 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
+```ruby
 Ransack.configure do |c|
   c.custom_arrows = {
     up_arrow: '<i class="custom-up-arrow-icon"></i>',
@@ -200,7 +204,7 @@ 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
+```ruby
 Ransack.configure do |c|
   c.hide_sort_order_indicators = true
 end
@@ -209,7 +213,7 @@ 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
+```erb
 <%= sort_link(@q, :name, hide_indicator: true) %>
 ```
 
@@ -219,15 +223,15 @@ 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
+```erb
 <%= sort_url(@q, :name, default_order: :desc) %>
 ```
 
-```jsx
+```erb
 <%= sort_url(@q, :last_name, [:last_name, 'first_name asc']) %>
 ```
 
-```jsx
+```erb
 <%= sort_url(@q, :last_name, %i(last_name first_name),
   default_order: { last_name: 'asc', first_name: 'desc' }) %>
 ```
@@ -238,7 +242,7 @@ The `NULLS FIRST` and `NULLS LAST` options can be used to determine whether null
 
 You may want to configure it like this:
 
-```jsx
+```ruby
 Ransack.configure do |c|
   c.postgres_fields_sort_option = :nulls_first # or :nulls_last
 end
@@ -246,7 +250,7 @@ end
 
 To treat nulls as having the lowest or highest value respectively. To force nulls to always be first or last, use
 
-```jsx
+```ruby
 Ransack.configure do |c|
   c.postgres_fields_sort_option = :nulls_always_first # or :nulls_always_last
 end
@@ -258,7 +262,7 @@ See this feature: https://www.postgresql.org/docs/13/queries-order.html
 
 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
+```ruby
 module RansackObject
 
   def self.included(base)
@@ -273,7 +277,7 @@ module RansackObject
 end
 ```
 
-```jsx
+```ruby
 class UserWithManyAttributes < ActiveRecord::Base
   include RansackObject
 end

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

@@ -9,7 +9,7 @@ title: Sorting
 
 You can add a form to capture sorting and filtering options together.
 
-```jsx
+```erb
 <div class="filters" id="filtersSidebar">
   <header class="filters-header">
     <div class="filters-header-content">

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

@@ -23,7 +23,7 @@ You can also combine predicates for OR queries:
 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
+>> 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%')
 ```
 

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/documentation.md

@@ -7,12 +7,24 @@ Ransack uses [Docusaurus](https://docusaurus.io/) for documentation. To contribu
 
 ### Local Development
 
+Switch to docs folder
+
 ```
 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.
+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
 

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

@@ -7,7 +7,7 @@ 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'
+```ruby title='index.html.erb'
 <h1>Users</h1>
 
 <%= search_form_for @q, url: dashboard_index_path do |f| %>
@@ -30,7 +30,7 @@ Example downloading a csv file preserving ransack search, based on [this gist](h
 <% end %>
 ```
 
-```jsx title='user.rb'
+```ruby title='user.rb'
 require 'csv'
 
 class User < ApplicationRecord

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

@@ -3,7 +3,7 @@ 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):
+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/tree/main/lib/ransack/locale) for more examples):
 
 ```yml
 # locales/en.yml

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

@@ -6,12 +6,12 @@ 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
+[Ransack::Locale](https://github.com/activerecord-hackery/ransack/tree/main/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):
+the translation files in [Ransack::Locale](https://github.com/activerecord-hackery/ransack/tree/main/lib/ransack/locale) for more examples):
 
 locales/en.yml:
 ```yml
@@ -27,7 +27,7 @@ en:
       gt: greater than
       lt: less than
     models:
-      person: Passanger
+      person: Passenger
     attributes:
       person:
         name: Full Name

data/docs/docs/going-further/merging-searches.md

@@ -38,4 +38,4 @@ WHERE (
 ORDER BY "people"."id" DESC
 ```
 
-Admittedly this is not as simple as it should be, but it's workable for now. (Implementing #417 could make this more straightforward.)
+Admittedly this is not as simple as it should be, but it's workable for now. (Implementing [issue 417](https://github.com/activerecord-hackery/ransack/issues/417) could make this more straightforward.)

data/docs/docs/going-further/other-notes.md

@@ -354,7 +354,7 @@ argument are not easily usable yet, because the array currently needs to be
 wrapped in an array to function (see
 [this issue](https://github.com/activerecord-hackery/ransack/issues/404)),
 which is not compatible with Ransack form helpers. For this use case, it may be
-better for now to use [ransackers](https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers) instead,
+better for now to use [ransackers](https://activerecord-hackery.github.io/ransack/going-further/ransackers) instead,
 where feasible. Pull requests with solutions and tests are welcome!
 
 ### Grouping queries by OR instead of AND

data/docs/docs/going-further/polymorphic-search.md

@@ -0,0 +1,40 @@
+---
+title: Polymorphic Searches
+sidebar_position: 14
+---
+
+When making searches from polymorphic models it is necessary to specify the type of model you are searching. 
+
+For example:
+
+Given two models
+
+```ruby
+class House < ActiveRecord::Base
+  has_one :location, as: :locatable
+end
+
+class Location < ActiveRecord::Base
+  belongs_to :locatable, polymorphic: true
+end
+```
+
+Normally (without polymorphic relationship) you would be able to search as per below:
+
+```ruby
+Location.ransack(locatable_number_eq: 100).result
+```
+
+However when this is searched you will get the following error
+
+```ruby
+ActiveRecord::EagerLoadPolymorphicError: Can not eagerly load the polymorphic association :locatable
+```
+
+In order to search for locations by house number when the relationship is polymorphic you have to specify the type of records you will be searching and construct your search as below:
+
+```ruby
+Location.ransack(locatable_of_House_type_number_eq: 100).result
+```
+
+note the `_of_House_type_` added to the search key. This allows Ransack to correctly specify the table names in SQL join queries.

data/docs/docs/going-further/saving-queries.md

@@ -72,7 +72,7 @@ class ApplicationController < ActionController::Base
   end
 
 protected
-  # GENERATE A GENERIC SESSION KEY BASED ON TEH CONTROLLER NAME
+  # GENERATE A GENERIC SESSION KEY BASED ON THE CONTROLLER NAME
   def search_key
     "#{controller_name}_search".to_sym
   end

data/docs/docs/going-further/searching-postgres.md

@@ -13,7 +13,7 @@ See [this issue](https://github.com/activerecord-hackery/ransack/issues/321) for
 
 ### Using a fixed key
 
-See here for searching on a fixed key in a JSONB column: https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers#3-search-on-a-fixed-key-in-a-jsonb--hstore-column
+See here for searching on a fixed key in a JSONB column: https://activerecord-hackery.github.io/ransack/going-further/ransackers/#postgres-columns
 
 ### Using the JSONB contains operator
 

data/docs/docs/going-further/wiki-contributors.md

@@ -0,0 +1,82 @@
+---
+title: Wiki Contributors
+sidebar_position: 20
+---
+
+Ransack previously had documentation contained in a GitHub Wiki, and this content has been merged into this documentation website. The following long list of _amazing_ people all made contributions to the Wiki:
+
+* Abinoam P. Marques Jr
+* Alex Stophel
+* Andrea Schiavini
+* Andrew Vit
+* Ben Koshy
+* Brainkurv
+* Brandan Lennox
+* Brendon Muir
+* Chris Salzberg
+* Colleen McGuckin
+* David Aldridge
+* Davidson Mohanty
+* Denis Tataurov
+* Drew Moore
+* Eike Send
+* Feodor Cherashev
+* Glauco Custódio
+* Grey Baker
+* Harold.Luo
+* Herman Singh
+* Ian Smith
+* Jake Haber
+* Jan Klimo
+* Jared Beck
+* Jon Atack
+* Juanito Fatas
+* JungaJk
+* Leo Chen
+* Leon Miller-Out
+* Luca F
+* Marc Poris
+* Matt Oakley
+* Michael Kopchick
+* Nathan Colgate
+* Nguyen Phi Viet(Sun*)
+* Nguyễn Đức Long
+* NielsKSchjoedt
+* Patrick Copeland
+* Pedro Chambino
+* Rene Hopf
+* Richa Arora
+* Rob Jones
+* Roman Sokhan
+* Ryan Bates
+* Ryan Bigg
+* Sean
+* Sean Linsley
+* Sergey
+* Sunny Ripert
+* Tanbir Hasan
+* ThuyNguyen97
+* Vanda
+* Yana Agun Siswanto
+* bonyiii
+* charly
+* chifung7
+* colorfulberry
+* ddonahue99
+* ernie
+* gaaady
+* gingerlime
+* grumpit
+* itsalongstory
+* jonatack
+* kogre
+* nguyentrungson97
+* nslocum
+* omitter
+* radar
+* rilian
+* terraplane
+* tyronewilson
+* vansy61
+* willnet
+* wzcolon

data/docs/docs/intro.md

@@ -17,7 +17,7 @@ Ransack is supported for Rails 7.0, 6.x on Ruby 2.6.6 and later.
 
 To install `ransack` and add it to your Gemfile, run
 
-```jsx title='Gemfile'
+```ruby title='Gemfile'
 gem 'ransack'
 ```
 
@@ -25,7 +25,7 @@ gem 'ransack'
 
 If you would like to use the latest updates not yet published to RubyGems, use the `main` branch:
 
-```jsx title='Gemfile'
+```ruby title='Gemfile'
 gem 'ransack', :github => 'activerecord-hackery/ransack', :branch => 'main'
 ```