ransack 2.6.0 → 3.0.0

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

@@ -0,0 +1,331 @@
+---
+sidebar_position: 6
+title: Ransackers
+---
+
+## Add custom search functions
+
+The main premise behind Ransack is to provide access to **Arel predicate methods**. Ransack provides special methods, called _ransackers_, for creating additional search functions via Arel.
+
+A `ransacker` method can **return any Arel node that allows the usual predicate methods**. Custom `ransacker`s are an expert feature, and require a thorough understanding of Arel.
+
+## Arel
+
+Here are some resources for more information about Arel:
+
+* [Using Arel to Compose SQL Queries](https://robots.thoughtbot.com/using-arel-to-compose-sql-queries)
+* [The definitive guide to Arel, the SQL manager for Ruby](http://jpospisil.com/2014/06/16/the-definitive-guide-to-arel-the-sql-manager-for-ruby.html)
+* [Creating Advanced Active Record DB Queries with Arel](https://www.cloudbees.com/blog/creating-advanced-active-record-db-queries-arel)
+
+Ransacker methods enable search customization and are placed in the model. Arguments may be passed to a ransacker method via `ransacker_args` (see Example #6 below).
+
+Ransackers, like scopes, are not a cure-all. Many use cases can be better solved with a standard Ransack search on a dedicated database search field, which is faster, index-able, and scales better than converting/ransacking data on the fly.
+
+## Example Ransackers
+
+### Search on field
+
+_Search on the `name` field reversed:_
+```ruby
+# in the model:
+ransacker :reversed_name, formatter: proc { |v| v.reverse } do |parent|
+  parent.table[:name]
+end
+```
+### Search using Datetime
+
+_Convert a user `string` input and a database `datetime` field to the same `date` format to find all records with a `datetime` field (`created_at` in this example) equal to that date :_
+
+```ruby
+# in the model:
+ransacker :created_at do
+  Arel.sql('date(created_at)')
+end
+```
+```erb
+in the view:
+<%= f.search_field(
+  :created_at_date_equals, placeholder: t(:date_format)
+  ) %>
+...
+<%= sort_link(@search, :created_at, default_order: :desc) %>
+```
+
+```ruby
+# config/initializers/ransack.rb
+Ransack.configure do |config|
+  config.add_predicate 'date_equals',
+    arel_predicate: 'eq',
+    formatter: proc { |v| v.to_date },
+    validator: proc { |v| v.present? },
+    type: :string
+end
+```
+
+#### 2.1
+It seems to be enough to change the model only, but don't forget to define the type that will returned as well.
+
+```ruby
+# in the model:
+ransacker :created_at, type: :date do
+  Arel.sql('date(created_at)')
+end
+```
+
+#### 2.2. Postgresql with time zones
+
+If you're using different time zones for Rails and Postgresql you should expect to have some problems using the above solution.
+Example:
+- Rails at GMT -03:00
+- Postgresql at GMT -00:00 (UTC)
+
+A timestamp like `2019-07-18 01:21:29.826484` will be truncated to `2019-07-18`.
+But for your Rails application `2019-07-18 01:21:29.826484` is `2019-07-17 22:21:29.826484` at your time zone (GMT -03:00). So it should be truncated to `2019-07-17` instead.
+
+
+So, you should convert the timestamp to your current Rails time zone before extracting the date.
+
+```ruby
+# in the model:
+ransacker :created_at, type: :date do
+  Arel.sql("date(created_at at time zone 'UTC' at time zone '#{Time.zone.name}')")
+end
+```
+
+Note that `Time.zone.name` should return a time zone string suitable for Postgresql.
+
+### Postgres columns
+
+_Search on a fixed key in a jsonb / hstore column:_
+
+In this example, we are searching a table with a column called `properties` for records containing a key called `link_type`.
+
+For anything up to and including Rails 4.1, add this to your model
+```ruby
+ransacker :link_type do |parent|    
+  Arel::Nodes::InfixOperation.new('->>', parent.table[:properties], 'link_type')
+end
+```
+When using Rails 4.2+ (Arel 6.0+), wrap the value in a `build_quoted` call
+```ruby
+ransacker :link_type do |parent|    
+  Arel::Nodes::InfixOperation.new('->>', parent.table[:properties], Arel::Nodes.build_quoted('link_type'))
+end
+```
+In the view, with a search on `link_type_eq` using a collection select (for example with options like 'twitter', 'facebook', etc.), if the user selects 'twitter', Ransack will run a query like:
+```
+SELECT * FROM "foos" WHERE "foos"."properties" ->> 'link_type' = 'twitter';
+```
+
+To use the JSONB contains operator @> see here: [[PostgreSQL JSONB searches]].
+
+### Type conversions
+
+_Convert an `integer` database field to a `string` in order to be able to use a `cont` predicate (instead of the usual `eq` which works out of the box with integers) to find all records where an integer field (`id` in this example) **contains** an input string:_
+
+Simple version, using PostgreSQL:
+```ruby
+# in the model:
+ransacker :id do
+  Arel.sql("to_char(id, '9999999')")
+end
+```
+and the same, using MySQL:
+```ruby
+ransacker :id do
+  Arel.sql("CONVERT(#{table_name}.id, CHAR(8))")
+end
+```
+A more complete version (using PostgreSQL) that adds the table name to avoid ambiguity and strips spaces from the input:
+```ruby
+ransacker :id do
+  Arel.sql(
+    "regexp_replace(
+      to_char(\"#{table_name}\".\"id\", '9999999'), ' ', '', 'g')"
+  )
+end
+```
+In the view, for all 3 versions:
+```erb
+<%= f.search_field :id_cont, placeholder: 'Id' %>
+...
+<%= sort_link(@search, :id) %>
+```
+
+### Concatenated fields
+
+_Search on a concatenated full name from `first_name` and `last_name` (several examples):_
+```ruby
+# in the model:
+ransacker :full_name do |parent|
+  Arel::Nodes::InfixOperation.new('||',
+    parent.table[:first_name], parent.table[:last_name])
+end
+
+# or, to insert a space between `first_name` and `last_name`:
+ransacker :full_name do |parent|
+  Arel::Nodes::InfixOperation.new('||',
+    Arel::Nodes::InfixOperation.new('||',
+      parent.table[:first_name], ' '
+    ),
+    parent.table[:last_name]
+  )
+end
+# Caveat: with Arel >= 6 the separator ' ' string in the
+# preceding example needs to be quoted as follows:
+ransacker :full_name do |parent|
+  Arel::Nodes::InfixOperation.new('||',
+    Arel::Nodes::InfixOperation.new('||',
+      parent.table[:first_name], Arel::Nodes.build_quoted(' ')
+    ),
+    parent.table[:last_name]
+  )
+end
+
+# works also in mariadb
+ransacker :full_name do |parent|
+  Arel::Nodes::NamedFunction.new('concat_ws',
+    [Arel::Nodes::SqlLiteral.new("' '"), parent.table[:first_name], parent.table[:last_name]])
+end
+
+# case insensitive lookup
+ransacker :full_name, formatter: proc { |v| v.mb_chars.downcase.to_s } do |parent|
+  Arel::Nodes::NamedFunction.new('LOWER',
+    [Arel::Nodes::NamedFunction.new('concat_ws',
+      [Arel::Nodes::SqlLiteral.new("' '"), parent.table[:first_name], parent.table[:last_name]])])
+end
+```
+
+### Passing arguments
+
+_Passing arguments to a ransacker:_
+Arguments may be passed to a ransacker method via `ransacker_args`:
+```ruby
+
+class Person
+  ransacker :author_max_title_of_article_where_body_length_between,
+  args: [:parent, :ransacker_args] do |parent, args|
+    min, max = args
+    query = <<-SQL
+      (SELECT MAX(articles.title)
+         FROM articles
+        WHERE articles.person_id = people.id
+          AND CHAR_LENGTH(articles.body) BETWEEN #{min.to_i} AND #{max.to_i}
+        GROUP BY articles.person_id
+      )
+    SQL
+    Arel.sql(query)
+  end
+end
+
+# Usage
+Person.ransack(
+  conditions: [{
+    attributes: {
+      '0' => {
+        name: 'author_max_title_of_article_where_body_length_between',
+        ransacker_args: [10, 100]
+      }
+    },
+    predicate_name: 'cont',
+    values: ['Ransackers can take arguments']
+  }]
+)
+
+=> SELECT "people".* FROM "people" WHERE (
+     (SELECT MAX(articles.title)
+        FROM articles
+       WHERE articles.person_id = people.id
+         AND CHAR_LENGTH(articles.body) BETWEEN 10 AND 100
+       GROUP BY articles.person_id
+     )
+   LIKE '%Ransackers can take arguments%')
+   ORDER BY "people"."id" DESC
+```
+
+### Dropdowns
+
+_Adding the attribute values associated with a column name to a searchable attribute in a dropdown options (instead of a traditional column name coming from a table). This is useful if using an associated table which is acting as a join table between a parent table and domain table. This will cache the data as the selections:_
+
+```ruby
+# in the model:
+Model.pluck(:name).each do |ground|
+  ransacker ground.to_sym do |parent|
+    Arel::Nodes::InfixOperation.new('AND',
+      Arel::Nodes::InfixOperation.new('=', parent.table[:gor_name], ground),
+      parent.table[:status]
+    )
+  end
+end
+
+# This will not include the column names in the dropdown
+def self.ransackable_attributes(auth_object = nil)
+  %w() + _ransackers.keys
+end
+```
+
+### Testing for existence
+
+_Testing for the existence of a row in another table via a join:_
+
+```ruby
+# in the model:
+ransacker :price_exists do |parent|
+  # SQL syntax for PostgreSQL -- others may differ
+  # This returns boolean true or false
+  Arel.sql("(select exists (select 1 from prices where prices.book_id = books.id))")
+end
+```
+
+In the view
+```haml
+  %td= f.select :price_exists_true, [["Any", 2], ["No", 0], ["Yes", 1]]
+```
+
+### Associations
+
+_Performing a query on an association with a differing class name:_
+
+Say we have a model "SalesAccount", which represents a relationship between two users,
+one being designated as a "sales_rep". We want to query SalesAccounts by
+the name of the sales_rep:
+
+```ruby
+# in the model:
+class SalesAccount < ActiveRecord::Base
+  belongs_to :user
+  belongs_to :sales_rep, class_name: :User
+
+# in the controller:
+  # The line below would lead to errors thrown later if not for the
+  # "joins(:sales_reps)".
+  @q = SalesAccount.includes(:user).joins(:sales_rep).ransack(params[:q])
+  @sales_accounts = @q.result(distinct: true)
+```
+
+In the view:
+```erb
+<%= f.search_field :sales_rep_name_start %>
+```
+
+### Search on translations
+
+_Search for a translated value in a jsonb column:_
+
+_Note: There is also a gem, [Mobility Ransack](https://github.com/shioyama/mobility-ransack), which allows you to search on translated attributes independent of their storage backend._
+
+This will work with any `jsonb` data type. In this case I have a column translated with [Mobility](https://github.com/shioyama/mobility) called `name` with the value `{'en': "Hello", 'es': "Hola"}`.
+
+```ruby
+ransacker :name do |parent|    
+  Arel::Nodes::InfixOperation.new('->>', parent.table[:name], Arel::Nodes.build_quoted(Mobility.locale))
+end
+```
+
+_If using Rails 4.1 or under, remove the `build_quoted` call._
+
+You can then search for `name_eq` or `name_cont` and it will do the proper SQL.
+
+***
+
+Please feel free to contribute further code examples!

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

@@ -0,0 +1,36 @@
+---
+title: Versions and Releases
+sidebar_position: 11
+---
+
+
+## Semantic Versioning
+
+Ransack attempts to follow semantic versioning in the format of `x.y.z`, where:
+
+`x` stands for a major version (new features that are not backward-compatible).
+
+`y` stands for a minor version (new features that are backward-compatible).
+
+`z` stands for a patch (bug fixes).
+
+In other words: `Major.Minor.Patch`.
+
+
+## Release Process
+
+*For the maintainers of Ransack.*
+
+To release a new version of Ransack and publish it to RubyGems, take the following steps:
+
+- Create a new release, marked `Prerelease`.
+- Update the versions file to the new release, commit and push to `master`.
+- Update the [`version.rb`](https://github.com/activerecord-hackery/ransack/lib/ransack/version.rb) file to the new release, commit and push to `master`.
+- From the terminal, run the following commands:
+
+```bash
+rake build
+rake release
+```
+
+![Create a Release](img/create_release.png)

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

@@ -0,0 +1,82 @@
+---
+sidebar_position: 7
+title: Saving queries
+---
+
+## Ransack Memory Gem
+
+The [Ransack Memory](https://github.com/richardrails/ransack_memory) gem accomplishes this.
+
+## Custom solution
+
+If you want a custom solution, you can build it yourself. My ransack AJAX searching doesn’t save your search parameters across transactions. In this post I’ll show you how to easily add this capability in a generic way.
+
+In this example I added AJAX search ability to index pages.
+
+```ruby
+def index
+  @search = ComponentDefinition.search(search_params)
+  # make name the default sort column
+  @search.sorts = 'name' if @search.sorts.empty?
+  @component_definitions = @search.result().page(params[:page])
+end
+```
+
+I added methods(search_params, clear_search_index) in the ApplicationController to add a level of abstraction from the search gem I was using. Turns out this made things super easy, especially considering I won’t have to update my code generation tools for index pages.
+
+```ruby
+class ApplicationController < ActionController::Base
+  def search_params
+    params[:q]
+  end
+  def clear_search_index
+    if params[:search_cancel]
+      params.delete(:search_cancel)
+      if(!search_params.nil?)
+        search_params.each do |key, param|
+          search_params[key] = nil
+        end
+      end
+    end
+  end
+end
+```
+
+I decided to store the ransack search parameters, params[:q], in the session. To make the session parameter unique I used a key creed from the controllers name and “_search”.
+
+```ruby
+class ApplicationController < ActionController::Base
+
+  # CHECK THE SESSION FOR SEARCH PARAMETERS IS THEY AREN'T IN THE REQUEST
+  def search_params
+    if params[:q] == nil
+        params[:q] = session[search_key]
+    end
+    if params[:q]
+          session[search_key] = params[:q]
+        end
+        params[:q]
+  end
+  # DELETE SEARCH PARAMETERS FROM THE SESSION
+  def clear_search_index
+      if params[:search_cancel]
+        params.delete(:search_cancel)
+        if(!search_params.nil?)
+            search_params.each do |key, param|
+                search_params[key] = nil
+            end
+        end
+        # REMOVE FROM SESSION
+        session.delete(search_key)
+      end
+  end
+
+protected
+  # GENERATE A GENERIC SESSION KEY BASED ON TEH CONTROLLER NAME
+  def search_key
+    "#{controller_name}_search".to_sym
+  end
+end
+```
+
+Based on [Saving queries](https://techbrownbags.wordpress.com/2015/02/18/rails-save-ransack-search-queries/)

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

@@ -0,0 +1,57 @@
+---
+sidebar_position: 8
+title: Postgres searches
+---
+
+Searching on Postgres-specific column types.
+
+## Postgres Array searches
+
+See [this issue](https://github.com/activerecord-hackery/ransack/issues/321) for details.
+
+## PostgreSQL JSONB searches
+
+### 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
+
+### Using the JSONB contains operator
+
+To fully use the power of the JSONB column you may want to filter on any key though:
+
+Install the [ActiveRecordExtended](https://github.com/GeorgeKaraszi/ActiveRecordExtended) gem to add the `contains` arel predicate to your project. It let's you use the [Postgres contains operator @>](https://www.postgresql.org/docs/12/functions-json.html#FUNCTIONS-JSONB-OP-TABLE).
+
+Add a custom predicate in the `config/initializers/ransack.rb` file:
+```ruby
+Ransack.configure do |config|
+  config.add_predicate 'jcont', arel_predicate: 'contains', formatter: proc { |v| JSON.parse(v) }
+end
+```
+
+Now you can ransack the JSONB columns using the _jcont predicate. For example the Person model has a `data` JSONB column, find entries where the column contains the {"group": "experts"} key-value pair:
+
+    Person.ransack(data_jcont: '{"group": "experts"}').result.to_sql
+
+    SELECT "persons".* FROM "persons" WHERE "persons"."data" @> '"{\"group\": \"experts\"}"'
+
+If you have a GIN index on that column, the database will quickly be able to find that result.
+
+### Treating the column as a string
+
+Warning: This method converts the column to a string and matches the given string to the result. This will be slow on large data_sets and does not make good use of the JSONB capabilities of Postgres, such as indexes.
+
+```ruby
+class Contact < ApplicationRecord
+  ransacker :within_json do |parent|
+    Arel.sql("table.jsonb_data::text")
+  end
+end
+
+Contact.all.ransack("within_json_cont" => "my")
+```
+
+Will generate
+
+`SELECT "contacts".* FROM "contacts" WHERE contacts.json_data ILIKE '%my%'`
+
+Note that this search treats the entire JSON as string, including parens, etc. i.e. you can search for e.g.: `Contact.all.ransack("within_json_cont" => '{"key": "value"}')`

data/docs/docs/intro.md

@@ -0,0 +1,99 @@
+---
+sidebar_position: 1
+slug: '/'
+---
+
+# Introduction
+
+Ransack will help you easily add **searching to your Rails application**, without any additional dependencies.
+
+There are advanced searching solutions around, like ElasticSearch or Algolia. **Ransack** will do the job for many Rails websites, without the need to run additional infrastructure or work in a different language. With Ransack you do it all with standard Ruby and ERB.
+
+Ready to move beyond the basics? Use **advanced features** like i18n and extensive configuration options.
+
+Ransack is supported for Rails 7.0, 6.x on Ruby 2.6.6 and later.
+
+## Installation
+
+To install `ransack` and add it to your Gemfile, run
+
+```jsx title='Gemfile'
+gem 'ransack'
+```
+
+### Bleeding edge
+
+If you would like to use the latest updates not yet published to RubyGems, use the `main` branch:
+
+```jsx title='Gemfile'
+gem 'ransack', :github => 'activerecord-hackery/ransack', :branch => 'main'
+```
+
+### Demo application
+
+The [Ransack Demo application](https://github.com/activerecord-hackery/ransack_demo) shows how to create [simple](http://ransack-demo.herokuapp.com) and
+[advanced](http://ransack-demo.herokuapp.com/users/advanced_search) search forms for your Ruby on Rails application.
+
+
+## Issues tracker
+
+* Before filing an issue, please read the [Contributing Guide](https://github.com/activerecord-hackery/ransack/CONTRIBUTING.md).
+* 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_.
+* Please consider adding a branch with a failing spec describing the problem.
+* Contributions are welcome. :smiley:
+* Please do not use the issue tracker for personal support requests. Stack Overflow is a better place for that where a wider community can help you!
+
+
+## Contributions
+
+To support the project:
+
+* Consider supporting us via [Open Collective](https://opencollective.com/ransack/backers/badge.svg)
+* Use Ransack in your apps, and let us know if you encounter anything that's
+broken or missing. A failing spec to demonstrate the issue is awesome. A pull
+request with passing tests is even better!
+* Before filing an issue or pull request, be sure to read and follow the
+[Contributing Guide](https://github.com/activerecord-hackery/ransack/CONTRIBUTING.md).
+* Please use Stack Overflow or other sites for questions or discussion not
+directly related to bug reports, pull requests, or documentation improvements.
+* Spread the word on Twitter, Facebook, and elsewhere if Ransack's been useful
+to you. The more people who are using the project, the quicker we can find and
+fix bugs!
+
+## Contributors
+
+Ransack was created by [Ernie Miller](http://twitter.com/erniemiller) and is developed and maintained by:
+* [Sean Carroll](https://github.com/scarroll32)
+* [Deivid Rodriguez](https://github.com/deivid-rodriguez)
+* [Greg Molnar](https://github.com/gregmolnar)
+* [A great group of contributors](https://github.com/activerecord-hackery/ransack/graphs/contributors).
+- Ransack's logo is designed by [Anıl Kılıç](https://github.com/anilkilic).
+
+Alumni Maintainers
+- [Jon Atack](http://twitter.com/jonatack)
+- [Ryan Bigg](http://twitter.com/ryanbigg)
+
+This project exists thanks to all the people who contribute. <img src="https://opencollective.com/ransack/contributors.svg?width=890&button=false" />
+
+
+## Backers
+
+Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/ransack#backer)]
+
+<a href="https://opencollective.com/ransack#backers" target="_blank"><img src="https://opencollective.com/ransack/backers.svg?width=890" /></a>
+
+
+## Sponsors
+
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/ransack#sponsor)]
+
+<a href="https://opencollective.com/ransack/sponsor/0/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/0/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/1/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/1/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/2/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/2/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/3/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/3/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/4/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/4/avatar.svg"/ ></a>
+<a href="https://opencollective.com/ransack/sponsor/5/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/5/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/6/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/6/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/7/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/7/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/8/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/8/avatar.svg" /></a>
+<a href="https://opencollective.com/ransack/sponsor/9/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/9/avatar.svg" /></a>