ransack 4.2.1 → 4.4.0

data/docs/docs/going-further/acts-as-taggable-on.md

@@ -1,114 +0,0 @@
----
-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/associations.md

@@ -1,70 +0,0 @@
----
-sidebar_position: 1
-title: Associations
----
-
-### Associations
-
-You can easily use Ransack to search for objects in `has_many` and `belongs_to`
-associations.
-
-Given these associations...
-
-```ruby
-class Employee < ActiveRecord::Base
-  belongs_to :supervisor
-
-  # has attributes first_name:string and last_name:string
-end
-
-class Department < ActiveRecord::Base
-  has_many :supervisors
-
-  # has attribute title:string
-end
-
-class Supervisor < ActiveRecord::Base
-  belongs_to :department
-  has_many :employees
-
-  # has attribute last_name:string
-end
-```
-
-... and a controller...
-
-```ruby
-class SupervisorsController < ApplicationController
-  def index
-    @q = Supervisor.ransack(params[:q])
-    @supervisors = @q.result.includes(:department, :employees)
-  end
-end
-```
-
-... you might set up your form like this...
-
-```erb
-<%= search_form_for @q do |f| %>
-  <%= f.label :last_name_cont %>
-  <%= f.search_field :last_name_cont %>
-
-  <%= f.label :department_title_cont %>
-  <%= f.search_field :department_title_cont %>
-
-  <%= f.label :employees_first_name_or_employees_last_name_cont %>
-  <%= f.search_field :employees_first_name_or_employees_last_name_cont %>
-
-  <%= f.submit "search" %>
-<% end %>
-...
-<%= content_tag :table do %>
-  <%= content_tag :th, sort_link(@q, :last_name) %>
-  <%= content_tag :th, sort_link(@q, :department_title) %>
-  <%= content_tag :th, sort_link(@q, :employees_last_name) %>
-<% end %>
-```
-
-If you have trouble sorting on associations, try using an SQL string with the
-pluralized table (`'departments.title'`,`'employees.last_name'`) instead of the
-symbolized association (`:department_title)`, `:employees_last_name`).

data/docs/docs/going-further/custom-predicates.md

@@ -1,52 +0,0 @@
----
-sidebar_position: 1
-title: Custom predicates
----
-
-If you'd like to add your own custom Ransack predicates:
-
-```ruby
-# config/initializers/ransack.rb
-
-Ransack.configure do |config|
-  config.add_predicate 'equals_diddly', # Name your predicate
-    # What non-compound ARel predicate will it use? (eq, matches, etc)
-    arel_predicate: 'eq',
-    # Format incoming values as you see fit. (Default: Don't do formatting)
-    formatter: proc { |v| "#{v}-diddly" },
-    # Validate a value. An "invalid" value won't be used in a search.
-    # Below is default.
-    validator: proc { |v| v.present? },
-    # Should compounds be created? Will use the compound (any/all) version
-    # of the arel_predicate to create a corresponding any/all version of
-    # your predicate. (Default: true)
-    compounds: true,
-    # Force a specific column type for type-casting of supplied values.
-    # (Default: use type from DB column)
-    type: :string,
-    # Use LOWER(column on database).
-    # (Default: false)
-    case_insensitive: true
-end
-```
-You can check all Arel predicates [here](https://github.com/rails/rails/blob/main/activerecord/lib/arel/predications.rb).
-
-If Arel does not have the predicate you are looking for, consider monkey patching it:
-
-```ruby
-# config/initializers/ransack.rb
-
-module Arel
-  module Predications
-    def gteq_or_null(other)
-      left = gteq(other)
-      right = eq(nil)
-      left.or(right)
-    end
-  end
-end
-
-Ransack.configure do |config|
-  config.add_predicate 'gteq_or_null', arel_predicate: 'gteq_or_null'
-end
-```

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

@@ -1,43 +0,0 @@
----
-sidebar_position: 11
-title: Documentation
----
-
-Ransack uses [Docusaurus](https://docusaurus.io/) for documentation. To contribute to the docs simply use the "Edit this page" link from any page to directly edit, or else pull the repo and edit locally.
-
-### Local Development
-
-Switch to docs folder
-
-```
-cd docs
-```
-
-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
-
-```
-yarn build
-```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-### Deployment
-
-Using SSH:
-
-```
-USE_SSH=true yarn deploy
-```

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

@@ -1,49 +0,0 @@
----
-sidebar_position: 2
-title: CSV Export
----
-
-Exporting to CSV
-
-Example downloading a csv file preserving ransack search, based on [this gist](https://gist.github.com/pama/adff25ed1f4b796ce088ea362a08e1c5)
-
-```ruby title='index.html.erb'
-<h1>Users</h1>
-
-<%= search_form_for @q, url: dashboard_index_path do |f| %>
-  <%= f.label :name_cont %>
-  <%= f.search_field :name_cont %>
-
-  <%= f.submit %>
-<% end %>
-
-<ul>
-  <% @users.each do |user| %>
-    <li><%= user.name %> [<%= user.devices.map {|device| device.name }.join(', ') %>]</li>
-  <% end %>
-</ul>
-
-<% if params[:q] %>
-  <%= link_to 'Export 1', dashboard_index_path({name: params[:q][:name_cont]}.merge({format: :csv})) %>
-<% else %>
-  <%= link_to 'Export 2', dashboard_index_path(format: 'csv') %>
-<% end %>
-```
-
-```ruby title='user.rb'
-require 'csv'
-
-class User < ApplicationRecord
-  has_many :devices
-
-  def self.get_csv(users)
-    CSV.generate do |csv|
-      csv << ["Name", "Devices"]
-
-      users.each do |user|
-        csv << [user.name, user.devices.map{|device| device.name}.join(', ')]
-      end
-    end
-  end
-end
-```

data/docs/docs/going-further/external-guides.md

@@ -1,57 +0,0 @@
----
-sidebar_position: 9
-title: External resources
----
-
-There is a plethora of material on Ransack around the internet. We've collected some here for your convenience.
-
-Do you want to have a blog post or other content on Ransack highlighted? Please just edit the page, add your content and a Pull Request will be sent to Ransack maintainers for approval.
-
-# Screencasts
-
-- [DriftingRuby: Ransack Search and Hotwire](https://www.driftingruby.com/episodes/ransack-search-and-hotwire)
-- [GoRails: Forum Series Part 6: Search with Ransack](https://gorails.com/episodes/forum-search-with-ransack)
-- [Railscast 370 - Ransack](http://railscasts.com/episodes/370-ransack)
-- [Search And Sort Ransack Associations With The Rails Ransack Gem | Ruby On Rails 6 Ransack Tutorial](https://www.youtube.com/watch?v=rtg-5EXwpbg)
-
-
-# Gems
-
-- [ActiveAdmin](https://activeadmin.info/) The Administration Framework for Rails **_uses Ransack internally_**
-- [Ransack Memory](https://github.com/richardrails/ransack_memory) Automatically save and load Ransack's filtered params into the Rail's session
-- [Mobility Ransack](https://github.com/shioyama/mobility-ransack) Search attributes translated by Mobility with Ransack.
-- [Ransack UI](https://github.com/ndbroadbent/ransack_ui) Framework for building a search UI with Ransack **_seems abandoned_**
-
-# Blogs
-
-- [Search And Sort In Ruby On Rails 6 With The Ransack Gem](https://deanin.com/blog/ransack/)
-- [Implement Ransack Gem in Ruby on Rails](https://www.botreetechnologies.com/blog/implementing-advanced-search-in-ruby-on-rails-with-ransack/)
-- [Searching and Sorting with Ransack](https://jaspercurry.medium.com/searching-and-sorting-on-rails-with-ransack-560e862e650a)
-- [How to Build Your Own ActiveAdmin Filters with Ransack](https://www.viget.com/articles/how-to-build-your-own-filters-with-ransack/)
-- [Avoid Ransack's N+1 Pitfall!](https://dev.to/husteadrobert/avoid-ransacks-n1-pitfall-33of)
-- [Filter and paging with Kaminari](https://gist.github.com/MyklClason/e4dc96fd0e009b7b3a9c84ddbb1e11d2)
-- [Pagination for Ransack Forms](https://nicholaide.github.io/ransack/2016/11/26/ransack-pagination.html)
-- [AJAX Search, Sort, Paginate with Ransack and Kaminari](https://techbrownbags.wordpress.com/2014/01/17/rails-ajax-search-sort-paginate-with-ransack-kaminari/)
-- [Searching with Ransack in Ruby on Rails](http://blog.magmalabs.io/2019/03/12/searching-with-ransack-in-ruby-on-rails.html)
-- [Role scopes with gem Ransack](https://blog.corsego.com/rolify-scopes)
-- [Searching and Sorting with Ransack](https://www.mintbit.com/blog/searching-and-sorting-with-ransack)
-- [Using custom scopes with Ransack gem in Rails](https://profilehunt.net/blog/using-custom-scopes-with-ransack-in-rails)
-- [Query Date Range With Ransack](https://lingceng.github.io/blog/2015/12/28/query-date-range-with-ransack/)
-- [ransack vs searchkick: Building a search feature in Rails](https://www.cookieshq.co.uk/posts/ransack-vs-searchkick-building-a-search-feature-in-rails)
-- [Using ransack and delegate in Rails](https://huangwenwei.com/blogs/using-ransack-and-delegate-in-rails)
-- [Using Ransack as a Search Engine](https://medium.com/@jelaniwoods/using-ransack-as-a-search-engine-92e002a68da)
-- [Advanced Search with Ransack](https://www.sitepoint.com/advanced-search-ransack/)
-- [Sort a table of records in Rails with Ransack](https://alankydd.wordpress.com/2012/03/12/sort-a-table-of-records-in-rails-with-ransack/)
-- [Ransack: Search with Multiple Checkboxes (Rails)](https://iamjosh.wordpress.com/2014/03/07/ransack-search-with-multiple-checkboxes/)
-- [Rails : Ransack : Sorting data by ratings](https://cbabhusal.wordpress.com/2017/01/03/rails-ransack-sorting-data-by-ratings/)
-- [Setting Up Rails 5 API Only App with ActiveAdmin enabled](https://rrott.com/blog/ror/rails-5-api-with-activeadmin-integration/)
-- [Ransack, the library formerly known as MetaSearch 2.0](https://ernie.io/2011/04/01/ransack-the-library-formerly-known-as-metasearch-2-0/) **_some Ransack history_**
-
-## In French
-
-- [Faciliter les recherches avec Ransack](https://www.synbioz.com/blog/tech/faciliter-les-recherches-avec-ransack)
-
-## In Vietnamese
-
-- [Ransack - công cụ tuyệt vời giúp tìm kiếm và sắp xếp dữ liệu đơn giản hơn
-](https://nddblog.com/posts/ransack-cong-cu-tuyet-voi-giup-tim-kiem-va-sap-xep-du-lieu-don-gian-hon)

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

@@ -1,63 +0,0 @@
----
-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/tree/main/lib/ransack/locale) for more examples):
-
-```yml
-# locales/en.yml
-en:
-  ransack:
-    asc: ascending
-    desc: descending
-    predicates:
-      cont: contains
-      not_cont: not contains
-      start: starts with
-      end: ends with
-      gt: greater than
-      lt: less than
-    attributes:
-      person:
-        name: Full Name
-      article:
-        title: Article Title
-        body: Main Content
-```
-The names of attribute fields may also be changed globally or under activerecord:
-
-```yml
-# locales/en.yml
-en:
-  attributes:
-    model_name:
-      model_field1: field name1
-      model_field2: field name2
-  activerecord:
-    attributes:
-      namespace/article:
-        title: AR Namespaced Title
-      namespace_article:
-        title: Old Ransack Namespaced Title
-```
-
-To limit the predicates in the `predicate_select` form helper in a view template, pass an array of permitted predicates with `only`:
-
-```erb
-<%= f.predicate_select only: %i(cont not_cont eq not_eq blank null) %>
-```
-
-Compound predicates (`_any` & `_all`) may be removed by passing the option `compounds: false`.
-
-```erb
-<%= f.predicate_select compounds: false %>
-```
-
-Searchable attributes versus non-searchable ones may be specified as follows:
-
-```ruby
-def self.ransackable_attributes(auth_object = nil)
-  %w(searchable_attribute_1 searchable_attribute_2 ...) + _ransackers.keys
-end
-```

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

@@ -1,53 +0,0 @@
----
-sidebar_position: 3
-title: i18n
----
-
-# i18n and Ransack
-
-Ransack translation files are available in
-[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/tree/main/lib/ransack/locale) for more examples):
-
-locales/en.yml:
-```yml
-en:
-  ransack:
-    asc: ascending
-    desc: descending
-    predicates:
-      cont: contains
-      not_cont: not contains
-      start: starts with
-      end: ends with
-      gt: greater than
-      lt: less than
-    models:
-      person: Passenger
-    attributes:
-      person:
-        name: Full Name
-      article:
-        title: Article Title
-        body: Main Content
-```
-
-Attribute names may also be changed globally, or under `activerecord`:
-
-```yml
-en:
-  attributes:
-    model_name:
-      model_field1: field name1
-      model_field2: field name2
-  activerecord:
-    attributes:
-      namespace/article:
-        title: AR Namespaced Title
-      namespace_article:
-        title: Old Ransack Namespaced Title
-```

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

@@ -1,41 +0,0 @@
----
-sidebar_position: 5
-title: Merging searches
----
-
-To find records that match multiple searches, it's possible to merge all the ransack search conditions into an ActiveRecord relation to perform a single query. In order to avoid conflicts between joined table names it's necessary to set up a shared context to track table aliases used across all the conditions before initializing the searches:
-
-```ruby
-shared_context = Ransack::Context.for(Person)
-
-search_parents = Person.ransack(
-  { parent_name_eq: "A" }, context: shared_context
-)
-
-search_children = Person.ransack(
-  { children_name_eq: "B" }, context: shared_context
-)
-
-shared_conditions = [search_parents, search_children].map { |search|
-  Ransack::Visitor.new.accept(search.base)
-}
-
-Person.joins(shared_context.join_sources)
-  .where(shared_conditions.reduce(&:or))
-  .to_sql
-```
-Produces:
-```sql
-SELECT "people".*
-FROM "people"
-LEFT OUTER JOIN "people" "parents_people"
-  ON "parents_people"."id" = "people"."parent_id"
-LEFT OUTER JOIN "people" "children_people"
-  ON "children_people"."parent_id" = "people"."id"
-WHERE (
-  ("parents_people"."name" = 'A' OR "children_people"."name" = 'B')
-  )
-ORDER BY "people"."id" DESC
-```
-
-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.)