ransack 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40b269c3c65d60bdd34562075a2a3aaa1e2c500f
-  data.tar.gz: d2520b91acbc39e7dcbe534d32294e7e0b01f512
+  metadata.gz: d33a76673ff5b03a95d1b2ea72c5fcc552fc24a3
+  data.tar.gz: 061c963998e43b654a28e0b3e7e9501feee14192
 SHA512:
-  metadata.gz: c1152e4bde37b2f1b6dc78f888d51e2438c678ca366f54e54bf6baf9aecf7167e23e0119e24730dd94599c0888d68a2acba2a094093679f68e9c405866d774df
-  data.tar.gz: b7be091d8256745c1feddc3e614432227714ee17b57f40ea9517309837384c486d9619971174966df7f8eafc71521ef7c09c149df639ead8bce4e98c9eab4a6b
+  metadata.gz: aa17a37043b1924961e17631865374576b78584068785c91331c06567b285ce10764b837c78f54f740570696e2ffd620e6681a391600074f2cc33d5d73956a1c
+  data.tar.gz: 7f3253f6d31f941546e0244389dcff4be6ec55e90511954c0eb0151447a27051b2c98a2d1b8e57ed89c279e98c1c608c5ee24a56115f8095aeed2038130ff7cb

data/CHANGELOG.md

@@ -2,6 +2,81 @@
 This change log was started in August 2014. All notable changes to this project
 henceforth should be documented here.
 
+## Version 1.5.0 - 2014-10-26
+### Added
+
+*   Add support for multiple sort fields and default orders in Ransack
+    `sort_link` helpers
+    ([pull request](https://github.com/activerecord-hackery/ransack/pull/438)).
+   
+    *Caleb Land*, *James u007*
+
+*   Add tests for `lteq`, `lt`, `gteq` and `gt` predicates. They are also
+    tested in Arel, but testing them in Ransack has proven useful to detect
+    issues.
+
+    *Jon Atack*
+
+*   Add tests for unknown attribute names.
+    
+    *Joe Yates*
+
+*   Add tests for attribute names containing '_or_' and '_and_'.
+    
+    *Joe Yates*, *Jon Atack*
+
+*   Add tests for attribute names ending with '_start' and '_end'.
+    
+    *Jon Atack*, *Timo Schilling*
+
+*   Add tests for `start`, `not_start`, `end` and `not_end` predicates, with
+    emphasis on cases when attribute names end with `_start` and `_end`.
+
+    *Jon Atack*
+
+### Fixed
+
+*   Fix a regression where form labels for attributes through a `belongs_to`
+    association without a translation for the attribute in the locales file
+    would cause a "no implicit conversion of nil into Hash" crash instead of
+    falling back on the attribute name. Added test coverage.
+
+    *John Dell*, *Jon Atack*, *jasdeepgosal*
+
+*   Fix the `form_helper date_select` spec that was failing with Rails 4.2 and
+    master.
+
+    *Jon Atack*
+
+*   Improve `attribute_method?` parsing for method names containing `_and_` and
+    `_or_`. Attributes named like `foo_and_bar` or `foo_or_bar` are recognized
+    now instead of running failing checks for `foo` and `bar`.
+
+    *Joe Yates*
+
+*   Improve `attribute_method?` parsing for method names ending with a
+    predicate like `_start` and `_end`. For instance, a `life_start` attribute
+    is now recognized instead of raising a NoMethodError.
+
+    *Timo Schilling*, *Jon Atack*
+
+### Changed
+
+*   Reduce object allocations and memory footprint (with a slight speed gain as
+    well) by extracting commonly used strings into top level constants and
+    replacing calls to `#try` methods with simple nil checking.
+
+    *Jon Atack*
+
+
+## Version 1.4.1 - 2014-09-23
+### Fixed
+
+*   Fix README markdown so RubyGems documentation picks up the formatting correctly.
+
+    *Jon Atack*
+
+
 ## Version 1.4.0 - 2014-09-23
 ### Added
 

data/CONTRIBUTING.md

@@ -4,8 +4,8 @@ Ransack is an open source project and we encourage contributions.
 
 When filing an issue on the Ransack project, please provide these details:
 
-* A comprehensive list of steps to reproduce the issue.
-* The version of Ransack *and* the version of Rails and Ruby.
+* A comprehensive list of steps to reproduce the issue, or, _far better_, a failing spec!
+* The version (and branch) of Ransack *and* the versions of Rails and Ruby.
 * Any relevant stack traces ("Full trace" preferred).
 
 In 99% of cases, this information is enough to determine the cause and
@@ -53,17 +53,17 @@ day). We may suggest some changes or improvements or alternatives.
 Some things that will increase the chance that your pull request is accepted,
 taken straight from the Ruby on Rails guide:
 
-* Use Rails idioms and helpers
-* Include tests that fail without your code, and pass with it
-* Update the documentation, the surrounding one, examples elsewhere, guides,
-  whatever is affected by your contribution
+* Use Rails idioms and helpers.
+* Include tests that fail without your code, and pass with it.
+* Update the README, the change log, the wiki documentation... anything that is
+  affected by your contribution.
 
 Syntax:
 
 * Two spaces, no tabs.
 * 80 characters per line.
 * No trailing whitespace. Blank lines should not have any space.
-* Prefer &&/|| over and/or.
+* Prefer `&&`/`||` over `and`/`or`.
 * `MyClass.my_method(my_arg)` not `my_method( my_arg )` or my_method my_arg.
 * `a = b` and not `a=b`.
 * `a_method { |block| ... }` and not `a_method { | block | ... }` or

data/Gemfile

@@ -5,8 +5,15 @@ gem 'rake'
 
 rails = ENV['RAILS'] || 'master'
 
+if rails[0,3] == '4.2' || rails == 'master'
+  gem 'arel', github: 'rails/arel', branch: 'master'
+end
+
 gem 'polyamorous', '~> 1.1'
 
+# Provide timezone information on Windows
+gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw]
+
 case rails
 when /\// # A path
   gem 'activesupport', path: "#{rails}/activesupport"

data/README.md

@@ -42,12 +42,18 @@ gem 'ransack', github: 'activerecord-hackery/ransack'
 
 The other branches (`rails-4`, `rails-4.1`, and `rails-4.2`) were each used for
 developing and running Ransack with the latest upcoming version of Rails at the
-time. They are lighter and somewhat faster-running because they do not have to
+time. They are smaller and possibly slightly faster because they do not have to
 support previous versions of Rails and Active Record. Once support for that
 Rails version is merged from the branch into Ransack master, the branch is no
 longer actively maintained -- unless the open source community submits pull
 requests to maintain them. You are welcome to do so!
 
+To use one of the branches, for example the `rails-4.1` branch:
+
+```ruby
+gem 'ransack', github: 'activerecord-hackery/ransack', branch: 'rails-4.1'
+```
+
 ## Usage
 
 Ransack can be used in one of two modes, simple or advanced.
@@ -110,7 +116,7 @@ The two primary Ransack view helpers are `search_form_for` and `sort_link`,
 which are defined in
 [Ransack::Helpers::FormHelper](lib/ransack/helpers/form_helper.rb).
 
-#####1. Ransack's `search_form_for` helper replaces `form_for` for creating the view search form:
+#####Ransack's `search_form_for` helper replaces `form_for` for creating the view search form:
 
 ```erb
 <%= search_form_for @q do |f| %>
@@ -145,18 +151,39 @@ The `search_form_for` answer format can be set like this:
 <%= search_form_for(@q, format: :json) do |f| %>
 ```
 
-#####2. Ransack's `sort_link` helper creates table headers that are sortable links:
+#####Ransack's `sort_link` helper creates table headers that are sortable links:
 
 ```erb
-<%= content_tag :th, sort_link(@q, :name) %>
+<%= sort_link(@q, :name) %>
 ```
 Additional options can be passed after the column attribute, like a different
 column title or a default sort order:
 
 ```erb
-<%= content_tag :th, sort_link(@q, :name, 'Last Name', default_order: :desc) %>
+<%= sort_link(@q, :name, 'Last Name', default_order: :desc) %>
 ```
 
+You can also sort on multiple fields by specifying an ordered array:
+
+```erb
+<%= sort_link(@q, :last_name, [:last_name, 'first_name asc'], 'Last Name') %>
+```
+
+In the example above, clicking the link will sort by `last_name` and then
+`first_name`. Specifying the sort direction on a field in the array tells
+Ransack to _always_ sort that particular field in the specified direction.
+
+Multiple `default_order` fields may also be specified with a hash:
+
+```erb
+<%= sort_link(@q, :last_name, %i(last_name first_name),
+  default_order: { last_name: 'asc', first_name: 'desc' }) %>
+```
+
+This example toggles the sort directions of both fields, by default
+initially sorting the `last_name` field by ascending order, and the
+`first_name` field by descending order.
+
 ### Advanced Mode
 
 "Advanced" searches (ab)use Rails' nested attributes functionality in order to
@@ -291,29 +318,37 @@ class methods in your models to apply selective authorization:
 Here is how these four methods are implemented in Ransack:
 
 ```ruby
-def ransackable_attributes(auth_object = nil)
-  # By default returns all column names and any defined ransackers as an array
-  # of strings. For overriding with a whitelist array of strings.
-  column_names + _ransackers.keys
-end
+  # Ransackable_attributes, by default, returns all column names
+  # and any defined ransackers as an array of strings.
+  # For overriding with a whitelist array of strings.
+  #
+  def ransackable_attributes(auth_object = nil)
+    column_names + _ransackers.keys
+  end
 
-def ransackable_associations(auth_object = nil)
-  # By default returns the names of all associations as an array of strings.
+  # Ransackable_associations, by default, returns the names
+  # of all associations as an array of strings.
   # For overriding with a whitelist array of strings.
-  reflect_on_all_associations.map { |a| a.name.to_s }
-end
+  #
+  def ransackable_associations(auth_object = nil)
+    reflect_on_all_associations.map { |a| a.name.to_s }
+  end
 
-def ransortable_attributes(auth_object = nil)
-  # By default returns the names of all attributes for sorting as an array of
-  # strings. For overriding with a whitelist array of strings.
-  ransackable_attributes(auth_object)
-end
+  # Ransortable_attributes, by default, returns the names
+  # of all attributes available for sorting as an array of strings.
+  # For overriding with a whitelist array of strings.
+  #
+  def ransortable_attributes(auth_object = nil)
+    ransackable_attributes(auth_object)
+  end
 
-def ransackable_scopes(auth_object = nil)
-  # By default returns an empty array, i.e. no class methods/scopes
-  # are authorized. For overriding with a whitelist array of *symbols*.
-  []
-end
+  # Ransackable_scopes, by default, returns an empty array
+  # i.e. no class methods/scopes are authorized.
+  # For overriding with a whitelist array of *symbols*.
+  #
+  def ransackable_scopes(auth_object = nil)
+    []
+  end
 ```
 
 Any values not returned from these methods will be ignored by Ransack, i.e.
@@ -329,6 +364,7 @@ Here is an example that puts all this together, adapted from
 (http://erniemiller.org/2012/05/11/why-your-ruby-class-macros-might-suck-mine-did/).
 In an `Article` model, add the following `ransackable_attributes` class method
 (preferably private):
+
 ```ruby
 class Article < ActiveRecord::Base
 
@@ -345,7 +381,9 @@ class Article < ActiveRecord::Base
   end
 end
 ```
+
 Here is example code for the `articles_controller`:
+
 ```ruby
 class ArticlesController < ApplicationController
 
@@ -361,7 +399,9 @@ class ArticlesController < ApplicationController
   end
 end
 ```
+
 Trying it out in `rails console`:
+
 ```ruby
 > Article
 => Article(id: integer, person_id: integer, title: string, body: text) 
@@ -381,6 +421,7 @@ Trying it out in `rails console`:
 > Article.search({ id_eq: 1 }, { auth_object: :admin }).result.to_sql
 => SELECT "articles".* FROM "articles"  WHERE "articles"."id" = 1
 ```
+
 That's it! Now you know how to whitelist/blacklist various elements in Ransack.
 
 ### Using Scopes/Class Methods
@@ -393,7 +434,7 @@ scope accepts a value:
 
 ```ruby
 class Employee < ActiveRecord::Base
-  scope :active, ->(boolean = true) { (where active: boolean) }
+  scope :active, ->(boolean = true) { where(active: boolean) }
   scope :salary_gt, ->(amount) { where('salary > ?', amount) }
 
   # Scopes are just syntactical sugar for class methods, which may also be used:
@@ -420,6 +461,19 @@ Employee.search({ active: true, hired_since: '2013-01-01' })
 Employee.search({ salary_gt: 100_000 }, { auth_object: current_user })
 ```
 
+Scopes are a recent addition to Ransack and currently have a few caveats:
+First, a scope involving child associations needs to be defined in the parent
+table model, not in the child model. Second, scopes with an array as an
+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
+where feasible. Finally, there is also
+[this issue](https://github.com/activerecord-hackery/ransack/issues/403)
+to be aware of. Pull requests with solutions and tests are welcome!
+
 ### Grouping queries by OR instead of AND
 
 The default `AND` grouping can be changed to `OR` by adding `m: 'or'` to the
@@ -479,16 +533,14 @@ artists.result.to_sql
 
 ### Using SimpleForm
 
-If you want to combine form builders of ransack and SimpleForm, just set the
-RANSACK_FORM_BUILDER environment variable before Rails started, e.g. in
-``config/application.rb`` before ``require 'rails/all'`` and of course use
-``gem 'simple_form'`` in your ``Gemfile``:
+If you would like to combine the Ransack and SimpleForm form builders, set the
+`RANSACK_FORM_BUILDER` environment variable before Rails boots up, e.g. in
+`config/application.rb` before `require 'rails/all'` as shown below (and add
+`gem 'simple_form'` in your Gemfile).
 
 ```ruby
 require File.expand_path('../boot', __FILE__)
-
 ENV['RANSACK_FORM_BUILDER'] = '::SimpleForm::FormBuilder'
-
 require 'rails/all'
 ```
 
@@ -499,14 +551,67 @@ Ransack translation files are available in
 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](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
+    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
+```
+
+## 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`.
+
 ## Contributions
 
 To support the project:
 
 * Use Ransack in your apps, and let us know if you encounter anything that's
-broken or missing. A failing spec is awesome. A pull request with tests that
-pass is even better! Before filing an issue or pull request, be sure to read
-the [Contributing Guide](CONTRIBUTING.md).
+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](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!

data/lib/ransack/adapters/active_record/3.0/compat.rb

@@ -135,16 +135,16 @@ module Arel
         "#{
           o.name
           }(#{
-          o.distinct ? 'DISTINCT ' : ''
+          o.distinct ? Ransack::Constants::DISTINCT : Ransack::Constants::EMPTY
           }#{
-          o.expressions.map { |x| visit x }.join(', ')
+          o.expressions.map { |x| visit x }.join(Ransack::Constants::COMMA_SPACE)
           })#{
-          o.alias ? " AS #{visit o.alias}" : ''
+          o.alias ? " AS #{visit o.alias}" : Ransack::Constants::EMPTY
           }"
       end
 
       def visit_Arel_Nodes_And o
-        o.children.map { |x| visit x }.join ' AND '
+        o.children.map { |x| visit x }.join(' AND '.freeze)
       end
 
       def visit_Arel_Nodes_Not o
@@ -161,7 +161,7 @@ module Arel
             quote(value, attr && column_for(attr))
           end
         }
-        .join ', '
+        .join(Ransack::Constants::COMMA_SPACE)
         })"
       end
     end