File: README — Documentation for ransack

Ransack Abbreviator

===================

Ransack is a gem that gives you the ability to create powerful search forms. Unfortunately though, the more fields you add to your form, the longer the URL gets, which usually forces you to use the HTTP POST method instead of GET, which can get annoying pretty quickly.

Ransack Abbreviator uses defined abbreviations for columns and associations to shorten your query params and thus the URL generated by your search form. Hopefully, it allows you to avoid that POST.

Getting Started

In your Gemfile:

gem 'ransack_abbreviator'

How to Use

The abbreviator should cause absolutely no problems if you decide to not use abbreviations. It only kicks in when an abbreviation is detected in the params. That said, here's how to use it:

Define Abbreviations

First, define some abbreviations for columns and associations. One way to do that is to create a ransack_abbreviator.yml file in your config directory in a structure like this:

ransack_abbreviations:
  columns:
    name: "nm"
    title: "tl"
  associations:
    articles: "ars"
    people: "ppl"

If you don't want to use a YAML file, define an initializer and add your abbreviations there.

RansackAbbreviator.configure do |config|
  config.add_column_abbreviation(:name, :nm)
  config.add_column_abbreviation(:title, :tl)
  config.add_assoc_abbreviation(:articles, :ars)
  config.add_assoc_abbreviation(:people, :ppl)
end

Use the Abbreviated Attribute in your Form

In your form, simply add an 'abbr_' prefix to each form element:

<%= search_form_for @q do |f| %>
  <%= f.abbr_label :name_cont, "Name Contains" %>
  <%= f.abbr_text_field :name_cont %>
  <%= f.abbr_label :articles_title_start, "Title of article starts with" %>
  <%= f.abbr_text_field :articles_title_start %>
  <%= f.submit %>
<% end %>

When the above form is submitted, what would have normally been a URL param of 'name_cont' is now 'nm_cont'. 'articles_title_start' is now 'ars.tl_start'. View the source of the generated form to see for yourself!

If you're using Ransack's 'attribute_select', simply change it to 'abbr_attribute_select' to utilize abbreviations over the full attribute name.

See the Ransack documentation for more info on the language Ransack uses and how to reference associations, columns, and predicates.

Remove those POST hacks!

Hopefully, the URL is now at least half the size it could have been before and you can remove all the POST hacks you did to get pagination and whatnot to work correctly!

Some Notes

The code works by abbreviating what it can and leaving what it cannot alone. For example, if you forgot to abbreviate 'articles', then <%= f.abbr_text_field :articles_title_start %> would return 'articles.tl_start' as the ID and param of the text field.

To Do

Support abbreviation of 'ransacker' attributes