ransack 3.0.1 → 3.2.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (36) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/test.yml +16 -31
  3. data/CHANGELOG.md +49 -0
  4. data/CONTRIBUTING.md +5 -5
  5. data/Gemfile +2 -2
  6. data/README.md +4 -4
  7. data/docs/docs/getting-started/simple-mode.md +24 -24
  8. data/docs/docs/getting-started/sorting.md +1 -1
  9. data/docs/docs/getting-started/using-predicates.md +1 -1
  10. data/docs/docs/going-further/acts-as-taggable-on.md +114 -0
  11. data/docs/docs/going-further/exporting-to-csv.md +2 -2
  12. data/docs/docs/going-further/merging-searches.md +1 -1
  13. data/docs/docs/going-further/polymorphic-search.md +40 -0
  14. data/docs/docs/going-further/wiki-contributors.md +1 -1
  15. data/docs/docs/intro.md +2 -2
  16. data/docs/docusaurus.config.js +14 -1
  17. data/docs/package.json +3 -2
  18. data/docs/yarn.lock +1311 -546
  19. data/lib/polyamorous/activerecord_6.1_ruby_2/reflection.rb +11 -1
  20. data/lib/polyamorous/activerecord_7.1_ruby_2/join_association.rb +1 -0
  21. data/lib/polyamorous/activerecord_7.1_ruby_2/join_dependency.rb +1 -0
  22. data/lib/polyamorous/activerecord_7.1_ruby_2/reflection.rb +1 -0
  23. data/lib/ransack/adapters/active_record/context.rb +17 -49
  24. data/lib/ransack/adapters/active_record/ransack/nodes/condition.rb +2 -10
  25. data/lib/ransack/constants.rb +0 -3
  26. data/lib/ransack/helpers/form_helper.rb +1 -1
  27. data/lib/ransack/nodes/value.rb +1 -1
  28. data/lib/ransack/version.rb +1 -1
  29. data/ransack.gemspec +3 -3
  30. data/spec/helpers/polyamorous_helper.rb +2 -8
  31. data/spec/ransack/helpers/form_helper_spec.rb +12 -0
  32. data/spec/ransack/nodes/value_spec.rb +115 -0
  33. metadata +15 -11
  34. data/lib/polyamorous/activerecord_6.0_ruby_2/join_association.rb +0 -20
  35. data/lib/polyamorous/activerecord_6.0_ruby_2/join_dependency.rb +0 -79
  36. data/lib/polyamorous/activerecord_6.0_ruby_2/reflection.rb +0 -11
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2599d5bd405561f9dd3c9b1b585baef6132a23653ebaf079f65aa7a326b20998
4
- data.tar.gz: '0899eeb3faebe29e31c6ec2ec248d1b106f6fdb5175532fdb55b82abce928d19'
3
+ metadata.gz: f4ce966153aee54a3e24eb4ec775569926813ed7273839e5d042dbbc6b3addf8
4
+ data.tar.gz: 4d96b0ecae077f0096494a99f90e8cfb3555140fe194c79ed691b2760319e51c
5
5
  SHA512:
6
- metadata.gz: 0cd85c2c70494e50e4ce67351a3abb7822424372fbe5e3062415b7c3471094883f955cf6c6c57f1f783442b68d18593c0d8a220e4f1f1e68c9e1e48d80b2d9be
7
- data.tar.gz: 24c878aceb15a2a914f4c99743df78af82aef65fda072301678bde8307ed0dfafc5506366929babf19524a221d2a57d191d7d3e4ebb2bf73760f5b4b6928d082
6
+ metadata.gz: 5d23fb2ddc8ef40489c40e02202b3d051305252c21b5f6c2823478442ce326990b22a26ee46861212b690ada0632328ce6c5065cba238bd185eecc46fd5555c5
7
+ data.tar.gz: 5dffd2910eefdfe2633d13a4b7d36838340f45fb484f025fed264e5df5b69c730df16257f11e7425a0852f99255b1f22e970c6407a9f5f4c59c2ca027f6e8804
@@ -11,17 +11,12 @@ jobs:
11
11
  fail-fast: false
12
12
  matrix:
13
13
  rails:
14
- - v7.0.0
15
- - v6.1.4
16
- - v6.0.4
17
- - 6-0-stable
14
+ - v7.0.3
15
+ - v6.1.6
18
16
  ruby:
19
- - 3.0.2
20
- - 2.7.4
21
- - 2.6.7
22
- exclude:
23
- - rails: v7.0.0
24
- ruby: 2.6.7
17
+ - 3.1.2
18
+ - 3.0.4
19
+ - 2.7.6
25
20
  env:
26
21
  DB: sqlite3
27
22
  RAILS: ${{ matrix.rails }}
@@ -42,17 +37,12 @@ jobs:
42
37
  fail-fast: false
43
38
  matrix:
44
39
  rails:
45
- - v7.0.0
46
- - v6.1.4
47
- - v6.0.4
48
- - 6-0-stable
40
+ - v7.0.3
41
+ - v6.1.6
49
42
  ruby:
50
- - 3.0.2
51
- - 2.7.4
52
- - 2.6.7
53
- exclude:
54
- - rails: v7.0.0
55
- ruby: 2.6.7
43
+ - 3.1.2
44
+ - 3.0.4
45
+ - 2.7.6
56
46
  env:
57
47
  DB: mysql
58
48
  RAILS: ${{ matrix.rails }}
@@ -82,17 +72,12 @@ jobs:
82
72
  fail-fast: false
83
73
  matrix:
84
74
  rails:
85
- - v7.0.0
86
- - v6.1.4
87
- - v6.0.4
88
- - 6-0-stable
75
+ - v7.0.3
76
+ - v6.1.6
89
77
  ruby:
90
- - 3.0.2
91
- - 2.7.4
92
- - 2.6.7
93
- exclude:
94
- - rails: v7.0.0
95
- ruby: 2.6.7
78
+ - 3.1.2
79
+ - 3.0.4
80
+ - 2.7.6
96
81
  env:
97
82
  DB: postgres
98
83
  RAILS: ${{ matrix.rails }}
@@ -135,7 +120,7 @@ jobs:
135
120
  - name: Set up Ruby
136
121
  uses: ruby/setup-ruby@v1
137
122
  with:
138
- ruby-version: 3.0.2
123
+ ruby-version: 3.1.2
139
124
  - name: Install dependencies
140
125
  run: bundle install
141
126
  - name: Run bug report templates
data/CHANGELOG.md CHANGED
@@ -2,6 +2,55 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 3.2.1 - 2022-05-24
6
+
7
+ * Add search functionality to documentation site.
8
+ PR [1329](https://github.com/activerecord-hackery/ransack/pull/1329)
9
+
10
+ * Fix contributing URLs and syntax highlight in `README.md`.
11
+ PR [1326](https://github.com/activerecord-hackery/ransack/pull/1326)
12
+
13
+ * Cast PostgreSQL's `timestamptz` columns to time.
14
+ PR [1325](https://github.com/activerecord-hackery/ransack/pull/1325)
15
+
16
+ * Add Ruby and ERB syntax highlighting support to documentation site.
17
+ PR [1324](https://github.com/activerecord-hackery/ransack/pull/1324)
18
+
19
+ * Fix a wrong link in `CHANGELOG.md`.
20
+ PR [1323](https://github.com/activerecord-hackery/ransack/pull/1323)
21
+
22
+ * Fix links to bug report templates in `CONTRIBUTING.md`.
23
+ PR [1321](https://github.com/activerecord-hackery/ransack/pull/1321)
24
+
25
+ ## 3.2.0 - 2022-05-08
26
+
27
+ * Drop Rails 6.0 support.
28
+ PR [1318](https://github.com/activerecord-hackery/ransack/pull/1318)
29
+
30
+ * Exclude "host" from params sent to url generator.
31
+ PR [1317](https://github.com/activerecord-hackery/ransack/pull/1317)
32
+
33
+ ## 3.1.0 - 2022-04-21
34
+
35
+ * Fix predicate name in "Using Predicates" documentation page.
36
+ PR [1313](https://github.com/activerecord-hackery/ransack/pull/1313)
37
+
38
+ * Drop Ruby 2.6 support.
39
+ PR [1311](https://github.com/activerecord-hackery/ransack/pull/1311)
40
+
41
+ * Allow Ransack to be used with Rails 7.1.0.alpha.
42
+ PR [1309](https://github.com/activerecord-hackery/ransack/pull/1309)
43
+
44
+ * Put contributor list last in documentation site.
45
+ PR [1308](https://github.com/activerecord-hackery/ransack/pull/1308)
46
+
47
+ * Add `acts-as-taggable-on` and polymorphic searches to documentation.
48
+ PR [1306](https://github.com/activerecord-hackery/ransack/pull/1306)
49
+ PR [1312](https://github.com/activerecord-hackery/ransack/pull/1312)
50
+
51
+ * Add full link to issue about merging searches to documentation.
52
+ PR [1305](https://github.com/activerecord-hackery/ransack/pull/1305)
53
+
5
54
  ## 3.0.1 - 2022-04-08
6
55
 
7
56
  * Fix `:data` option to `sort_link` being incorrectly appended to the generated
data/CONTRIBUTING.md CHANGED
@@ -20,14 +20,14 @@ Steps:
20
20
  reported.
21
21
 
22
22
  2. **Check if the issue has been fixed** — try to reproduce it using the
23
- `master` branch in the repository.
23
+ `main` branch in the repository.
24
24
 
25
25
  3. **Isolate the real problem** — make sure the issue is really a bug in
26
26
  Ransack and not in your code or another gem.
27
27
 
28
28
  4. **Report the issue** by providing the link to a self-contained
29
- gist like [this](https://github.com/activerecord-hackery/ransack/blob/run_bug_report_templates/bug_report_templates/test-ransack-scope-and-column-same-name.rb) or
30
- [this](https://github.com/activerecord-hackery/ransack/blob/run_bug_report_templates/bug_report_templates/test-ransacker-arel-present-predicate.rb). Please use
29
+ gist like [this](https://github.com/activerecord-hackery/ransack/blob/main/bug_report_templates/test-ransack-scope-and-column-same-name.rb) or
30
+ [this](https://github.com/activerecord-hackery/ransack/blob/main/bug_report_templates/test-ransacker-arel-present-predicate.rb). Please use
31
31
  these code examples as a bug-report template for your Ransack issue!
32
32
 
33
33
  If you do not provide a self-contained gist and would like your issue to be reviewed, do provide at a minimum:
@@ -64,7 +64,7 @@ Here's a quick guide:
64
64
  2. Create a thoughtfully-named branch for your changes (`git checkout -b my-new-feature`).
65
65
 
66
66
  3. Install the development dependencies by running `bundle install`.
67
- To install rails other than latest (set in Gemfile): `RAILS='6-0-stable' bundle install`
67
+ To install rails other than latest (set in Gemfile): `RAILS='6-1-stable' bundle install`
68
68
 
69
69
  4. Begin by running the tests. We only take pull requests with passing tests,
70
70
  and it's great to know that you have a clean slate:
@@ -123,7 +123,7 @@ Here's a quick guide:
123
123
 
124
124
  12. Push the branch up to your fork on GitHub
125
125
  (`git push origin my-new-feature`) and from GitHub submit a pull request to
126
- Ransack's `master` branch.
126
+ Ransack's `main` branch.
127
127
 
128
128
  At this point you're waiting on us. We like to at least comment on, if not
129
129
  accept, pull requests within three business days (and, typically, one business
data/Gemfile CHANGED
@@ -3,7 +3,7 @@ gemspec
3
3
 
4
4
  gem 'rake'
5
5
 
6
- rails = ENV['RAILS'] || '6-0-stable'
6
+ rails = ENV['RAILS'] || '6-1-stable'
7
7
 
8
8
  rails_version = case rails
9
9
  when /\// # A path
@@ -15,7 +15,7 @@ rails_version = case rails
15
15
  end
16
16
 
17
17
  gem 'faker', '~> 2.0'
18
- gem 'sqlite3', ::Gem::Version.new(rails_version == 'main' ? '6.2.0.alpha' : rails_version) >= ::Gem::Version.new('6-0-stable') ? '~> 1.4.1' : '~> 1.3.3'
18
+ gem 'sqlite3', '~> 1.4.1'
19
19
  gem 'pg', '~> 1.0'
20
20
  gem 'pry', '~> 0.12.2'
21
21
  gem 'byebug'
data/README.md CHANGED
@@ -24,7 +24,7 @@ Ransack is supported for Rails 7.0, 6.x on Ruby 2.6.6 and later.
24
24
 
25
25
  To install `ransack` and add it to your Gemfile, run
26
26
 
27
- ```jsx title='Gemfile'
27
+ ```ruby title='Gemfile'
28
28
  gem 'ransack'
29
29
  ```
30
30
 
@@ -32,7 +32,7 @@ gem 'ransack'
32
32
 
33
33
  If you would like to use the latest updates not yet published to RubyGems, use the `main` branch:
34
34
 
35
- ```jsx title='Gemfile'
35
+ ```ruby title='Gemfile'
36
36
  gem 'ransack', :github => 'activerecord-hackery/ransack', :branch => 'main'
37
37
  ```
38
38
 
@@ -42,7 +42,7 @@ There is [extensive documentation on Ransack](https://activerecord-hackery.githu
42
42
 
43
43
  ## Issues tracker
44
44
 
45
- * Before filing an issue, please read the [Contributing Guide](https://github.com/activerecord-hackery/ransack/CONTRIBUTING.md).
45
+ * Before filing an issue, please read the [Contributing Guide](CONTRIBUTING.md).
46
46
  * File an issue if a bug is caused by Ransack, is new (has not already been reported), and _can be reproduced from the information you provide_.
47
47
  * Please consider adding a branch with a failing spec describing the problem.
48
48
  * Contributions are welcome. :smiley:
@@ -58,7 +58,7 @@ To support the project:
58
58
  broken or missing. A failing spec to demonstrate the issue is awesome. A pull
59
59
  request with passing tests is even better!
60
60
  * Before filing an issue or pull request, be sure to read and follow the
61
- [Contributing Guide](https://github.com/activerecord-hackery/ransack/CONTRIBUTING.md).
61
+ [Contributing Guide](CONTRIBUTING.md).
62
62
  * Please use Stack Overflow or other sites for questions or discussion not
63
63
  directly related to bug reports, pull requests, or documentation improvements.
64
64
  * Spread the word on Twitter, Facebook, and elsewhere if Ransack's been useful
@@ -11,7 +11,7 @@ mode should meet your needs.
11
11
 
12
12
  ## In your controller
13
13
 
14
- ```jsx
14
+ ```ruby
15
15
  def index
16
16
  @q = Person.ransack(params[:q])
17
17
  @people = @q.result(distinct: true)
@@ -20,7 +20,7 @@ end
20
20
  or without `distinct: true`, for sorting on an associated table's columns (in
21
21
  this example, with preloading each Person's Articles and pagination):
22
22
 
23
- ```jsx
23
+ ```ruby
24
24
  def index
25
25
  @q = Person.ransack(params[:q])
26
26
  @people = @q.result.includes(:articles).page(params[:page])
@@ -35,7 +35,7 @@ Ransack uses a default `:q` param key for search params. This may be changed by
35
35
  setting the `search_key` option in a Ransack initializer file (typically
36
36
  `config/initializers/ransack.rb`):
37
37
 
38
- ```jsx
38
+ ```ruby
39
39
  Ransack.configure do |c|
40
40
  # Change default search parameter key name.
41
41
  # Default key name is :q
@@ -48,7 +48,7 @@ end
48
48
  After version 2.4.0 when searching a string query Ransack by default strips all whitespace around the query string.
49
49
  This may be disabled by setting the `strip_whitespace` option in a Ransack initializer file:
50
50
 
51
- ```jsx
51
+ ```ruby
52
52
  Ransack.configure do |c|
53
53
  # Change whitespace stripping behaviour.
54
54
  # Default is true
@@ -66,7 +66,7 @@ which are defined in
66
66
 
67
67
  Ransack's `search_form_for` helper replaces `form_for` for creating the view search form
68
68
 
69
- ```jsx
69
+ ```erb
70
70
  <%= search_form_for @q do |f| %>
71
71
 
72
72
  # Search if the name field contains...
@@ -95,7 +95,7 @@ search predicates.
95
95
 
96
96
  The `search_form_for` answer format can be set like this:
97
97
 
98
- ```jsx
98
+ ```erb
99
99
  <%= search_form_for(@q, format: :pdf) do |f| %>
100
100
 
101
101
  <%= search_form_for(@q, format: :json) do |f| %>
@@ -105,7 +105,7 @@ The `search_form_for` answer format can be set like this:
105
105
 
106
106
  Ransack's `sort_link` helper creates table headers that are sortable links
107
107
 
108
- ```jsx
108
+ ```erb
109
109
  <%= sort_link(@q, :name) %>
110
110
  ```
111
111
  Additional options can be passed after the column parameter, like a different
@@ -114,13 +114,13 @@ column title or a default sort order.
114
114
  If the first option after the column parameter is a String, it's considered a
115
115
  custom label for the link:
116
116
 
117
- ```jsx
117
+ ```erb
118
118
  <%= sort_link(@q, :name, 'Last Name', default_order: :desc) %>
119
119
  ```
120
120
 
121
121
  You can use a block if the link markup is hard to fit into the label parameter:
122
122
 
123
- ```jsx
123
+ ```erb
124
124
  <%= sort_link(@q, :name) do %>
125
125
  <strong>Player Name</strong>
126
126
  <% end %>
@@ -130,14 +130,14 @@ With a polymorphic association, you may need to specify the name of the link
130
130
  explicitly to avoid an `uninitialized constant Model::Xxxable` error (see issue
131
131
  [#421](https://github.com/activerecord-hackery/ransack/issues/421)):
132
132
 
133
- ```jsx
133
+ ```erb
134
134
  <%= sort_link(@q, :xxxable_of_Ymodel_type_some_attribute, 'Attribute Name') %>
135
135
  ```
136
136
 
137
137
  If the first option after the column parameter and/or the label parameter is an
138
138
  Array, it will be used for sorting on multiple fields:
139
139
 
140
- ```jsx
140
+ ```erb
141
141
  <%= sort_link(@q, :last_name, [:last_name, 'first_name asc'], 'Last Name') %>
142
142
  ```
143
143
 
@@ -148,7 +148,7 @@ Ransack to _always_ sort that particular field in the specified direction.
148
148
  Multiple `default_order` fields may also be specified with a trailing options
149
149
  Hash:
150
150
 
151
- ```jsx
151
+ ```erb
152
152
  <%= sort_link(@q, :last_name, %i(last_name first_name),
153
153
  default_order: { last_name: 'asc', first_name: 'desc' }) %>
154
154
  ```
@@ -162,7 +162,7 @@ of a SQL function, you may do so using scopes. In your model, define scopes
162
162
  whose names line up with the name of the virtual field you wish to sort by,
163
163
  as so:
164
164
 
165
- ```jsx
165
+ ```ruby
166
166
  class Person < ActiveRecord::Base
167
167
  scope :sort_by_reverse_name_asc, lambda { order("REVERSE(name) ASC") }
168
168
  scope :sort_by_reverse_name_desc, lambda { order("REVERSE(name) DESC") }
@@ -171,7 +171,7 @@ class Person < ActiveRecord::Base
171
171
 
172
172
  and you can then sort by this virtual field:
173
173
 
174
- ```jsx
174
+ ```erb
175
175
  <%= sort_link(@q, :reverse_name) %>
176
176
  ```
177
177
 
@@ -186,7 +186,7 @@ You can also enable a `default_arrow` which is displayed on all sortable fields
186
186
  which are not currently used in the sorting. This is disabled by default so
187
187
  nothing will be displayed:
188
188
 
189
- ```jsx
189
+ ```ruby
190
190
  Ransack.configure do |c|
191
191
  c.custom_arrows = {
192
192
  up_arrow: '<i class="custom-up-arrow-icon"></i>',
@@ -200,7 +200,7 @@ All sort links may be displayed without the order indicator
200
200
  arrows by setting `hide_sort_order_indicators` to true in the initializer file.
201
201
  Note that this hides the arrows even if they were customized:
202
202
 
203
- ```jsx
203
+ ```ruby
204
204
  Ransack.configure do |c|
205
205
  c.hide_sort_order_indicators = true
206
206
  end
@@ -209,7 +209,7 @@ end
209
209
  Without setting it globally, individual sort links may be displayed without
210
210
  the order indicator arrow by passing `hide_indicator: true` in the sort link:
211
211
 
212
- ```jsx
212
+ ```erb
213
213
  <%= sort_link(@q, :name, hide_indicator: true) %>
214
214
  ```
215
215
 
@@ -219,15 +219,15 @@ Ransack's `sort_url` helper is like a `sort_link` but returns only the url
219
219
 
220
220
  `sort_url` has the same API as `sort_link`:
221
221
 
222
- ```jsx
222
+ ```erb
223
223
  <%= sort_url(@q, :name, default_order: :desc) %>
224
224
  ```
225
225
 
226
- ```jsx
226
+ ```erb
227
227
  <%= sort_url(@q, :last_name, [:last_name, 'first_name asc']) %>
228
228
  ```
229
229
 
230
- ```jsx
230
+ ```erb
231
231
  <%= sort_url(@q, :last_name, %i(last_name first_name),
232
232
  default_order: { last_name: 'asc', first_name: 'desc' }) %>
233
233
  ```
@@ -238,7 +238,7 @@ The `NULLS FIRST` and `NULLS LAST` options can be used to determine whether null
238
238
 
239
239
  You may want to configure it like this:
240
240
 
241
- ```jsx
241
+ ```ruby
242
242
  Ransack.configure do |c|
243
243
  c.postgres_fields_sort_option = :nulls_first # or :nulls_last
244
244
  end
@@ -246,7 +246,7 @@ end
246
246
 
247
247
  To treat nulls as having the lowest or highest value respectively. To force nulls to always be first or last, use
248
248
 
249
- ```jsx
249
+ ```ruby
250
250
  Ransack.configure do |c|
251
251
  c.postgres_fields_sort_option = :nulls_always_first # or :nulls_always_last
252
252
  end
@@ -258,7 +258,7 @@ See this feature: https://www.postgresql.org/docs/13/queries-order.html
258
258
 
259
259
  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:
260
260
 
261
- ```jsx
261
+ ```ruby
262
262
  module RansackObject
263
263
 
264
264
  def self.included(base)
@@ -273,7 +273,7 @@ module RansackObject
273
273
  end
274
274
  ```
275
275
 
276
- ```jsx
276
+ ```ruby
277
277
  class UserWithManyAttributes < ActiveRecord::Base
278
278
  include RansackObject
279
279
  end
@@ -9,7 +9,7 @@ title: Sorting
9
9
 
10
10
  You can add a form to capture sorting and filtering options together.
11
11
 
12
- ```jsx
12
+ ```erb
13
13
  <div class="filters" id="filtersSidebar">
14
14
  <header class="filters-header">
15
15
  <div class="filters-header-content">
@@ -23,7 +23,7 @@ You can also combine predicates for OR queries:
23
23
  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`:
24
24
 
25
25
  ```ruby
26
- >> User.ransack(account_foo_or_account_bar: 'val').result.to_sql
26
+ >> User.ransack(account_foo_or_account_bar_cont: 'val').result.to_sql
27
27
  => SELECT "users".* FROM "users" INNER JOIN accounts ON accounts.user_id = users.id WHERE ("accounts.foo LIKE '%val%' OR accounts.bar LIKE '%val%')
28
28
  ```
29
29
 
@@ -0,0 +1,114 @@
1
+ ---
2
+ title: Acts-as-taggable-on
3
+ sidebar_position: 13
4
+ ---
5
+
6
+ ## Using Acts As Taggable On
7
+
8
+ If you have an `ActiveRecord` model and you're using [acts-as-taggable-on](https://github.com/mbleigh/acts-as-taggable-on),
9
+ chances are you might want to search on tagged fields. Follow the instructions to install the gem and then set up your project files.
10
+
11
+ ### Configure the model
12
+
13
+ `app/models/tasks.rb`
14
+
15
+ 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`).
16
+
17
+ ```ruby
18
+ class Task < ApplicationRecord
19
+ acts_as_taggable_on :projects
20
+ end
21
+ ```
22
+
23
+ ### Controller
24
+
25
+ Add a field to strong params in the controller. Use the singular name with `_list`.
26
+
27
+ `app/controllers/tasks_controller.rb`
28
+
29
+ ```ruby
30
+ def strong_params
31
+ params
32
+ .require(:tasks)
33
+ .permit(:task, :example_field, :project_list)
34
+ ```
35
+
36
+ ### Form
37
+
38
+ We need to `send` the tag fieldname to our model, also using the singular naming.
39
+
40
+ ```erb
41
+ <div class='form-group'>
42
+ <%= f.label :project_list %>
43
+ <%= f.text_field :project_list, value: @task.send(:project_list).to_s %>
44
+ </div>
45
+ ```
46
+
47
+ Now we can collect our data via the form, with tags separated by commas.
48
+
49
+ ## Ransack Search
50
+
51
+ Imagine you have the following two instances of `Task`:
52
+
53
+ ```ruby
54
+ { id: 1, name: 'Clean up my room', projects: [ 'Home', 'Personal' ] }
55
+ { id: 2, name: 'Complete math exercises', projects: [ 'Homework', 'Study' ] }
56
+ ```
57
+
58
+ When you're writing a `Ransack` search form, you can choose any of the following options:
59
+
60
+ ```erb
61
+ <%= search_form_for @search do |f| %>
62
+ <%= f.text_field :projects_name_in %> <!-- option a -->
63
+ <%= f.text_field :projects_name_eq %> <!-- option b -->
64
+ <%= f.text_field :projects_name_cont %> <!-- option c -->
65
+ <% end %>
66
+ ```
67
+
68
+ ### Option A - Match keys exactly
69
+
70
+ 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):
71
+ - `Home, Personal` will return task 1
72
+ - `Home, Homework` will return task 1 and 2
73
+
74
+ ### Option B - match key combinations
75
+
76
+ Option `b` will match all keys exactly. This is the solution if you wanna search for specific combinations of tags:
77
+ - `Home` will return nothing, as there is no Task with just the `Home` tag
78
+ - `Home, Personal` will return task 1
79
+
80
+ ### Option C - match substrings
81
+
82
+ 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:
83
+ - `Home` will return task 1 and 2 (`/Home/` matches both `"Home"` and `"Homework"`)
84
+
85
+ ### Option D - select from a list of tags
86
+
87
+ In Option D we allow the user to select a list of valid tags and then search againt them. We use the plural name here.
88
+
89
+ ```erb
90
+ <div class='form-group'>
91
+ <%= f.label :projects_name, 'Project' %>
92
+ <%= f.select :projects_name_in, ActsAsTaggableOn::Tag.distinct.order(:name).pluck(:name) %>
93
+ </div>
94
+ ```
95
+
96
+ ## Multitenancy
97
+
98
+ 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:
99
+
100
+ ```ruby
101
+ class Task < ApplicationRecord
102
+ acts_as_taggable_on :projects
103
+ acts_as_taggable_tenant :language
104
+ end
105
+ ```
106
+
107
+ The Ransack search is then filtered using the `for_tenant` method
108
+
109
+ ```erb
110
+ <div class='form-group'>
111
+ <%= f.label :projects_name, 'Project' %>
112
+ <%= f.select :projects_name_in, ActsAsTaggableOn::Tag.for_tenant('fr').distinct.order(:name).pluck(:name) %>
113
+ </div>
114
+
@@ -7,7 +7,7 @@ Exporting to CSV
7
7
 
8
8
  Example downloading a csv file preserving ransack search, based on [this gist](https://gist.github.com/pama/adff25ed1f4b796ce088ea362a08e1c5)
9
9
 
10
- ```jsx title='index.html.erb'
10
+ ```ruby title='index.html.erb'
11
11
  <h1>Users</h1>
12
12
 
13
13
  <%= 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
30
30
  <% end %>
31
31
  ```
32
32
 
33
- ```jsx title='user.rb'
33
+ ```ruby title='user.rb'
34
34
  require 'csv'
35
35
 
36
36
  class User < ApplicationRecord
@@ -38,4 +38,4 @@ WHERE (
38
38
  ORDER BY "people"."id" DESC
39
39
  ```
40
40
 
41
- Admittedly this is not as simple as it should be, but it's workable for now. (Implementing #417 could make this more straightforward.)
41
+ 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.)
@@ -0,0 +1,40 @@
1
+ ---
2
+ title: Polymorphic Searches
3
+ sidebar_position: 14
4
+ ---
5
+
6
+ When making searches from polymorphic models it is necessary to specify the type of model you are searching.
7
+
8
+ For example:
9
+
10
+ Given two models
11
+
12
+ ```ruby
13
+ class House < ActiveRecord::Base
14
+ has_one :location, as: :locatable
15
+ end
16
+
17
+ class Location < ActiveRecord::Base
18
+ belongs_to :locatable, polymorphic: true
19
+ end
20
+ ```
21
+
22
+ Normally (without polymorphic relationship) you would be able to search as per below:
23
+
24
+ ```ruby
25
+ Location.ransack(locatable_number_eq: 100).result
26
+ ```
27
+
28
+ However when this is searched you will get the following error
29
+
30
+ ```ruby
31
+ ActiveRecord::EagerLoadPolymorphicError: Can not eagerly load the polymorphic association :locatable
32
+ ```
33
+
34
+ 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:
35
+
36
+ ```ruby
37
+ Location.ransack(locatable_of_House_type_number_eq: 100).result
38
+ ```
39
+
40
+ note the `_of_House_type_` added to the search key. This allows Ransack to correctly specify the table names in SQL join queries.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: Wiki Contributors
3
- sidebar_position: 12
3
+ sidebar_position: 20
4
4
  ---
5
5
 
6
6
  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:
data/docs/docs/intro.md CHANGED
@@ -17,7 +17,7 @@ Ransack is supported for Rails 7.0, 6.x on Ruby 2.6.6 and later.
17
17
 
18
18
  To install `ransack` and add it to your Gemfile, run
19
19
 
20
- ```jsx title='Gemfile'
20
+ ```ruby title='Gemfile'
21
21
  gem 'ransack'
22
22
  ```
23
23
 
@@ -25,7 +25,7 @@ gem 'ransack'
25
25
 
26
26
  If you would like to use the latest updates not yet published to RubyGems, use the `main` branch:
27
27
 
28
- ```jsx title='Gemfile'
28
+ ```ruby title='Gemfile'
29
29
  gem 'ransack', :github => 'activerecord-hackery/ransack', :branch => 'main'
30
30
  ```
31
31