Documentation and formatting follow-up to PR #726

CHANGELOG.md

@@ -4,7 +4,9 @@
 
 ### Added
 
-*   Add config option to customize up and down arrows used for direction indicators in the FormHelper. PR [#726](https://github.com/activerecord-hackery/ransack/pull/726)
+*   Add a config option to customize the up and down arrows used for direction
+    indicators in Ransack sort links.
+    PR [#726](https://github.com/activerecord-hackery/ransack/pull/726).
 
     *Garett Arrowood*
 

README.md

@@ -206,14 +206,10 @@ 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.
 
-The sort link may be displayed without the order indicator arrow by passing
-`hide_indicator: true`:
 
-```erb
-<%= sort_link(@q, :name, hide_indicator: true) %>
-```
-
-These indicator arrows may also be customized by setting them in an initializer file like `config/initializers/ransack.rb`:
+The sort link order indicator arrows may be globally customized by setting a
+`custom_arrows` option in an initializer file like
+`config/initializers/ransack.rb`:
 
 ```ruby
 Ransack.configure do |c|
@@ -224,7 +220,9 @@ Ransack.configure do |c|
 end
 ```
 
-Alternatively, all sort links may be displayed without the order indicator arrows:
+All sort links may be displayed without the order indicator
+arrows by setting `hide_sort_order_indicators` to true in the initializer file.
+Note that this hides the arrows even if they were customized:
 
 ```ruby
 Ransack.configure do |c|
@@ -232,6 +230,13 @@ Ransack.configure do |c|
 end
 ```
 
+Without setting it globally, individual sort links may be displayed without
+the order indicator arrow by passing `hide_indicator: true` in the sort link:
+
+```erb
+<%= sort_link(@q, :name, hide_indicator: true) %>
+```
+
 ####Ransack's `sort_url` helper is like a `sort_link` but returns only the url
 
 `sort_url` has the same API as `sort_link`:

lib/ransack/configuration.rb

@@ -77,15 +77,18 @@ module Ransack
       self.options[:ignore_unknown_conditions] = boolean
     end
 
-    # Ransack's default indicator arrows are html-code snippets. These
-    # arrows may be replaced by anything wrapped in quotation marks. Both
-    # or just one arrow may be globally overridden in an initializer file
+    # By default, Ransack displays sort order indicator arrows with HTML codes:
+    #
+    #   up_arrow:   '▼'
+    #   down_arrow: '▲'
+    #
+    # One or both defaults may be globally overridden in an initializer file
     # like `config/initializers/ransack.rb` as follows:
     #
     # Ransack.configure do |config|
-    #   # Set the up_arrow as an icon, set the down arrow as unicode
+    #   # Globally set the up arrow to an icon and the down arrow to unicode.
     #   config.custom_arrows = {
-    #     up_arrow: '<i class="fa fa-long-arrow-up"></i>',
+    #     up_arrow:   '<i class="fa fa-long-arrow-up"></i>',
     #     down_arrow: 'U+02193'
     #   }
     # end

spec/mongoid/configuration_spec.rb

@@ -65,7 +65,8 @@ module Ransack
         }
       end
 
-      expect(Ransack.options[:up_arrow]).to eq '<i class="fa fa-long-arrow-up"></i>'.freeze
+      expect(Ransack.options[:up_arrow])
+      .to eq '<i class="fa fa-long-arrow-up"></i>'.freeze
       expect(Ransack.options[:down_arrow]).to eq 'U+02193'.freeze
 
       # restore original state so we don't break other tests
@@ -99,8 +100,10 @@ module Ransack
           )
         end
 
-        expect(Ransack.predicates['test_in_predicate'].wants_array).to eq true
-        expect(Ransack.predicates['test_not_in_predicate'].wants_array).to eq true
+        expect(Ransack.predicates['test_in_predicate'].wants_array)
+        .to eq true
+        expect(Ransack.predicates['test_not_in_predicate'].wants_array)
+        .to eq true
       end
 
       it 'explicitly does not want array for in/not_in predicates' do
@@ -117,8 +120,10 @@ module Ransack
           )
         end
 
-        expect(Ransack.predicates['test_in_predicate_no_array'].wants_array).to eq false
-        expect(Ransack.predicates['test_not_in_predicate_no_array'].wants_array).to eq false
+        expect(Ransack.predicates['test_in_predicate_no_array'].wants_array)
+        .to eq false
+        expect(Ransack.predicates['test_not_in_predicate_no_array'].wants_array)
+        .to eq false
       end
     end
   end

spec/ransack/configuration_spec.rb

@@ -67,7 +67,8 @@ module Ransack
         }
       end
 
-      expect(Ransack.options[:up_arrow]).to eq '<i class="fa fa-long-arrow-up"></i>'.freeze
+      expect(Ransack.options[:up_arrow])
+      .to eq '<i class="fa fa-long-arrow-up"></i>'.freeze
       expect(Ransack.options[:down_arrow]).to eq 'U+02193'.freeze
 
       # restore original state so we don't break other tests
@@ -101,8 +102,10 @@ module Ransack
           )
         end
 
-        expect(Ransack.predicates['test_in_predicate'].wants_array).to eq true
-        expect(Ransack.predicates['test_not_in_predicate'].wants_array).to eq true
+        expect(Ransack.predicates['test_in_predicate'].wants_array)
+        .to eq true
+        expect(Ransack.predicates['test_not_in_predicate'].wants_array)
+        .to eq true
       end
 
       it 'explicitly does not want array for in/not_in predicates' do
@@ -119,8 +122,10 @@ module Ransack
           )
         end
 
-        expect(Ransack.predicates['test_in_predicate_no_array'].wants_array).to eq false
-        expect(Ransack.predicates['test_not_in_predicate_no_array'].wants_array).to eq false
+        expect(Ransack.predicates['test_in_predicate_no_array'].wants_array)
+        .to eq false
+        expect(Ransack.predicates['test_not_in_predicate_no_array'].wants_array)
+        .to eq false
       end
     end
   end