url_params_manager 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ebb47a5d6d6197871e1283d76419797d8926ac5b
-  data.tar.gz: d2db61a2aae5eb6eb74dcd4e17c088b2573cf15b
+  metadata.gz: bf37bee0652052fef68a8af38060681bbb126918
+  data.tar.gz: 7324ae64c1d098a22f95f0cd036eeabccf1cf694
 SHA512:
-  metadata.gz: f45fc8c47d9272c81731f44ccb795e7a40e780a2b0a1cee7fe36c29db5179131424a5778edd85dab2f065e8a65ab30557f9dae6ccf426a002c43f004bd422ad6
-  data.tar.gz: 8e47b4f4eb4a004835206bba032d636b5bfdbaba1c7012ab10f26a162179d354d933313ba8e9b4669835846d15a6c727bd52d4e2d90120c42e74b9fac3d2f56a
+  metadata.gz: d5cfbb60aef90c0f51730ce0a00b2f7ec4fb5542930ab1158abb235e04e5e2294a870cddbae126f016bafef55c7614f4f9c43646ee9a2a2fc22573977b156938
+  data.tar.gz: 7928e4654ce2ef213de734269972a6ae87d09a9d5c6a70af1d04e3056c564068dc75ae1cd867a31c42cc38e3ef3f266e0ae0838386d16eb61dc1837054fe3ad1

data/README.md

@@ -84,7 +84,7 @@ url_to_filter_params = {
   cap:  :capacity, # indexed => in URL
   some: :something, # not indexed => in querystring
   ndef: :non_default, # value with default
-  page: :page,
+  # page: :page, # if it is the same and it is present in `indexed_url_params_order`, we don't need to pass it.
 }
 
 # Default values for the params
@@ -108,6 +108,14 @@ default_params = {
 The `filter_params` will be passed to that callable object before returning on `filters_from_url_params` calls
 as well as at the beginning of `url_args_from_filters` calls.
 
+### `always_lists_fields`
+
+`UrlParamsManager` object can receive a `always_lists_fields` option with:
+
+- a list of fields to be converted to Array (ie: `[:multi, :another_multi]`)
+- a hash having the fields as keys and values either `true` (convert to Array) or a regex or string to use to `split`): (ie: `{ multi: true, another_multi: ',' }`)
+
+
 ### Building URLs
  
 ```ruby
@@ -181,6 +189,73 @@ With a URL like we built before: `'/search/feat-helipad/feat-swimming-pool/cap-2
 }
 ```
 
+## With Position-Defined params
+
+Sometimes we want the first url parts to have a preassigned meaning. For example, we may want something like 
+`/search/my-location/my-category/page-3`, where the first 2 params will be interpreted as `params[:locations]` and `params[:categories]`.
+
+With the `position_defined_url_params` option we can pass a hash with the config for these kind of params. 
+
+Important observations:
+
+- the position-defined params hash is **ordered**. The position will be determined by the order of the keys of the config hash.
+- all position defined param needs a **placeholder**. This will be:
+  - ignored when translating from url to filter
+  - added to the url in its place if a posterior param is present, so we can respect the position order.
+- when the param has multiple values, instead of adding them in separate parts, we'll concatenate them using a separator:
+  - it can be passed as `multiple_separator` option
+  - if not passed, it will use a default separator `--`.
+- when recognising params from the url, we'll **stop looking for position defined params when we first recognise a prefix of a normal param**
+
+The last part is important because it allows us to combine normal indexed params with position based params. 
+
+Example:
+
+```ruby
+url_to_filter_params = {}
+indexed_url_params_order = [:by_prefix, :page]
+position_defined_url_params = {
+  locations:  { placeholder: 'all-locations', multiple_separator: '--' },
+  categories: { placeholder: 'all-categories', multiple_separator: '_AND_' },
+  themes:     { placeholder: 'all-themes', multiple_separator: '--' },
+  offers:     { placeholder: 'all-offers' } # uses default separator
+}
+
+@upm = UrlParamsManager.for url_to_filter_params:       url_to_filter_params, # Param Name Map
+                            indexed_url_params_order:   indexed_url_params_order, # Indexed Params list
+                            position_defined_url_params: position_defined_url_params, # Position Defined params config
+                            app_url_helpers:            Rails.application.routes.url_helpers, # Object to receive the URL's Path calls (usually Rails URL Helpers)
+
+# FILTERS -> URL
+pars = {
+  categories:       ['my-cat', 'second-cat'],
+  offers:           'my-offer',
+  by_prefix_filter: ['hey', 'you'],
+  some:             ['other', 'another'],
+  page:             '2'
+}
+
+# it adds the needed placeholders
+expected_path = @upm.my_search_path(pars) 
+  # => '/search/all-locations/my-cat_AND_second-cat/all-themes/my-offer/by_prefix-hey/by_prefix-you/page-2?some%5B%5D=another&some%5B%5D=other'
+
+
+# example with less position based because we encounter one normal arg (page)
+url_params = {
+  filters: 'all-locations/my-cat_AND_second-cat/one-theme--second-theme/page-2'
+}
+expected_params = filters_from_url_params(url_params)
+ # => { 
+        categories:   ['my-cat', 'second-cat'],
+        themes:       ['one-theme', 'second-theme'],
+        page:         '2'
+      }
+
+# `all-locations`, being `locations` placeholder, is ignored
+# `page-2` is recognised as `page`, not as `offers`.
+```
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -216,3 +291,12 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ### v.0.2.0
 
 - added `filter_params_treatment` option.
+
+### v.0.3.0: YANKED!
+
+- added `position_defined_url_params` option.
+
+
+### v.0.4.0
+- fixed typo in `position_defined_url_params` (it was position_defined_url_parms)
+- added `always_lists_fields` option.

data/lib/url_params_manager.rb

@@ -8,12 +8,17 @@ module UrlParamsManager
     indexed_url_params_order: nil,
     app_url_helpers: nil,
     default_params: {},
+    always_lists_fields: {},
+    position_defined_url_params: nil,
     filter_params_treatment: ->(filter_params) { filter_params }
   )
-    Service.new url_to_filter_params:     url_to_filter_params,
-                indexed_url_params_order: indexed_url_params_order,
-                app_url_helpers:          app_url_helpers,
-                default_params:           default_params,
-                filter_params_treatment:  filter_params_treatment
+    Service.new url_to_filter_params:        url_to_filter_params,
+                indexed_url_params_order:    indexed_url_params_order,
+                app_url_helpers:             app_url_helpers,
+                default_params:              default_params,
+                filter_params_treatment:     filter_params_treatment,
+                position_defined_url_params: position_defined_url_params,
+                always_lists_fields:         always_lists_fields
+
   end
 end

data/lib/url_params_manager/service.rb

@@ -1,24 +1,36 @@
 module UrlParamsManager
   class Service
+    EMPTY_STRING                            = ''.freeze
+    PREFIX_SEPARATOR                        = '-'.freeze
+    DEFAULT_PLACEHOLDER                     = '_'.freeze
+    DEFAULT_MULTIPLE_SEPARATOR_FOR_POSITION = '--'.freeze
+    DEFAULT_FILTER_PARAMS_TREATMENT         = ->(filter_params) { filter_params }
+
     attr_reader :app_url_helpers,
                 :url_to_filter_params,
                 :indexed_url_params_order,
                 :filter_to_url_params,
                 :default_params,
-                :filter_params_treatment
+                :position_defined_url_params,
+                :filter_params_treatment,
+                :always_lists_fields
 
     def initialize(url_to_filter_params: nil,
                    indexed_url_params_order: nil,
                    app_url_helpers: nil,
                    default_params: {},
-                   filter_params_treatment: ->(filter_params) { filter_params }
+                   always_lists_fields: {},
+                   position_defined_url_params: nil,
+                   filter_params_treatment: DEFAULT_FILTER_PARAMS_TREATMENT
     )
-      @url_to_filter_params     = url_to_filter_params
-      @filter_to_url_params     = url_to_filter_params.invert
-      @indexed_url_params_order = indexed_url_params_order
-      @app_url_helpers          = app_url_helpers
-      @default_params           = default_params
-      @filter_params_treatment  = filter_params_treatment
+      @url_to_filter_params        = url_to_filter_params
+      @filter_to_url_params        = url_to_filter_params.invert
+      @indexed_url_params_order    = indexed_url_params_order.map &:to_s
+      @app_url_helpers             = app_url_helpers
+      @default_params              = default_params
+      @position_defined_url_params = position_defined_url_params.presence || {}
+      @filter_params_treatment     = filter_params_treatment
+      @always_lists_fields         = prepare_always_lists_fields(always_lists_fields)
     end
 
     # for url/path methods from filter args
@@ -30,21 +42,11 @@ module UrlParamsManager
     def filters_from_url_params(params)
       params = params.to_h.symbolize_keys
 
-      filters = {}.merge default_params
-
-      params.delete(:filters).to_s.split('/').each do |part|
-        filter, value = recognise_prefix(part)
-        if filters.has_key? filter
-          filters[filter] = Array(filters[filter])
-          filters[filter] << value
-        else
-          filters[filter] = value
-        end
-      end
+      filters = unfold_filters(params)
 
       pars = filters.merge querystring_to_filters(params)
 
-      filter_params_treatment.call pars
+      filter_params(pars)
     end
 
     def querystring_to_filters(querystring_params)
@@ -56,58 +58,67 @@ module UrlParamsManager
     end
 
     private
+
+    #################
+    # FILTER -> URL #
+    #################
+
     def path_method(method, filter_args)
       url_args = url_args_from_filters(filter_args)
       app_url_helpers.send(method, url_args)
     end
 
-    EMPTY_STRING = ''.freeze
-
-    def recognise_prefix(url_part)
-      url_to_filter_params.each do |url_prefix, filter|
-        pref = "#{url_prefix}-"
-        if url_part.start_with? pref
-          return [filter, url_part.sub(pref, EMPTY_STRING)]
-        end
-      end
-
-      raise UnrecognisedPrefixError, "url part: #{url_part}"
-    end
 
     def url_args_from_filters(filter_args)
-      filter_pars       = filter_params_treatment.call filter_args
+      filter_pars       = filter_params(filter_args)
       valid_filter_args = remove_defaults(filter_pars)
-      bare_args         = translate_filter_keys(valid_filter_args)
 
-      in_uri_args       = bare_args.select { |(k, _)| indexed_url_params_order.include? k }
-      query_string_args = bare_args.reject { |(k, _)| indexed_url_params_order.include? k }
+      bare_args = translate_filter_keys(valid_filter_args)
+
+      in_uri_args       = bare_args.select { |(url_param, _)| url_param_in_path?(url_param) }
+      query_string_args = bare_args.reject { |(url_param, _)| url_param_in_path?(url_param) }
+
+      # adding placeholders
+      with_placeholders = add_placeholders in_uri_args
 
       # sorting indexed part
-      sorted_uri_args   = sort_uri_filters(in_uri_args)
+      sorted_uri_args   = sort_uri_filters with_placeholders
 
-      #converting into string
-      filters_uri_part  = generate_uri_part(sorted_uri_args)
+      # converting into string
+      filters_uri_part  = generate_uri_part sorted_uri_args
 
       # query string args + filter param for the urlpath helper methods
       query_string_args.merge filters: filters_uri_part.join('/')
     end
 
-    def sort_uri_filters(in_uri_args)
-      keys_sorted = Hash[
-        in_uri_args.to_a.sort_by do |k, _|
-          @indexed_url_params_order.index(k)
+    def add_placeholders(sorted_uri_args)
+      position_based_keys = position_defined_url_params.keys.reverse
+      need_placeholder    = false
+
+      position_based_keys.inject(sorted_uri_args) do |args, key|
+        options          = position_defined_url_params[key] || {}
+        need_placeholder = need_placeholder || args[key].present?
+
+        if need_placeholder && args[key].blank?
+          args[key] = options[:placeholder] || DEFAULT_PLACEHOLDER
         end
-      ]
 
-      Hash[
-        keys_sorted.map do |k, v|
-          sorted_v = v.respond_to?(:sort) ? v.sort : v
-          [k, sorted_v]
+        args
+      end
+    end
+
+    def remove_defaults(filter_args)
+      default_params.each do |k, v|
+        next unless filter_args.key?(k) && filter_args[k].present?
+        if filter_args[k] == v || Array(filter_args[k]).sort == Array(v).sort
+          filter_args.delete k
         end
-      ]
+      end
 
+      filter_args
     end
 
+
     def translate_filter_keys(filter_args)
       Hash[
         filter_args.map do |k, v|
@@ -119,8 +130,64 @@ module UrlParamsManager
       ]
     end
 
+    def url_param_in_path?(url_param)
+      indexed_url_params_order.include?(url_param.to_s) || position_defined_url_params.key?(url_param)
+    end
+
+    def sort_uri_filters(in_uri_args)
+      position_uri_args = in_uri_args.select { |k, _| position_defined_url_params.key? k }
+      prefix_uri_args   = in_uri_args.reject { |k, _| position_defined_url_params.key? k }
+
+      final_list = []
+
+      final_list = final_list.concat sort_uri_filters_by_position(position_uri_args)
+      final_list = final_list.concat sort_uri_filters_by_prefix(prefix_uri_args)
+
+      final_list.map do |k, v|
+        sorted_v = v.respond_to?(:sort) ? v.sort : v
+        [k, sorted_v]
+      end.to_h
+    end
+
+    def sort_uri_filters_by_position(position_uri_args)
+      position_keys = position_defined_url_params.keys
+      position_uri_args.to_a.sort_by do |k, _|
+        position_keys.index(k)
+      end
+    end
+
+    def sort_uri_filters_by_prefix(prefix_uri_args)
+      prefix_uri_args.to_a.sort_by do |k, _|
+        indexed_url_params_order.index(k.to_s)
+      end
+    end
+
     def generate_uri_part(in_uri_args)
-      in_uri_args.inject([]) do |uri, (key, value)|
+      position_uri_args = in_uri_args.select { |k, _| position_defined_url_params.key? k }
+      prefix_uri_args   = in_uri_args.reject { |k, _| position_defined_url_params.key? k }
+
+      generate_uri_parts_by_position(position_uri_args).concat generate_uri_parts_by_prefix(prefix_uri_args)
+    end
+
+    def generate_uri_parts_by_position(position_uri_args)
+      position_uri_args.inject([]) do |uri, (key, value)|
+        options = position_defined_url_params[key]
+
+        prefix     = options[:prefix].present? ? "#{options[:prefix]}-" : EMPTY_STRING
+        uri_values = []
+        Array(value).each do |v|
+          uri_values << "#{prefix}#{v}"
+        end
+
+        separator = get_separator_from_position_options(options)
+        uri << uri_values.join(separator)
+
+        uri
+      end
+    end
+
+    def generate_uri_parts_by_prefix(prefix_uri_args)
+      prefix_uri_args.inject([]) do |uri, (key, value)|
         Array(value).each do |v|
           uri << "#{key}-#{v}"
         end
@@ -128,15 +195,127 @@ module UrlParamsManager
       end
     end
 
-    def remove_defaults(filter_args)
-      default_params.each do |k, v|
-        next unless filter_args.key?(k) && filter_args[k].present?
-        if filter_args[k] == v || Array(filter_args[k]).sort == Array(v).sort
-          filter_args.delete k
+
+    #################
+    # URL -> FILTER #
+    #################
+
+
+    def unfold_filters(params)
+      filters = {}.merge default_params
+
+      raw = params.delete(:filters).to_s.split('/')
+
+      used_positions = unfold_filters_by_position(filters, raw)
+      unfold_filters_by_prefix(filters, raw.drop(used_positions))
+
+      filters
+    end
+
+    def unfold_filters_by_position(filters, raw)
+
+      # the moment we recognise one param with a prefix based, we assume that the position based have stopped
+      prefix_based_recognised = false
+      position_defined_raw    = raw.inject([]) do |list, url_part|
+        prefix_based_recognised ||= recognised_prefix? url_part
+        list << url_part unless prefix_based_recognised
+        list
+      end
+
+      available_position_params = position_defined_url_params.to_a.take(position_defined_raw.size)
+      used_positions            = 0
+
+      available_position_params.each_with_index do |(key, options), index|
+        used_positions += 1
+        value          = raw[index]
+
+        next if value == options[:placeholder]
+
+        separator = get_separator_from_position_options(options)
+        values    = value.split(separator)
+
+        filters[key] = values.size > 1 ? values : values.first
+      end
+
+      used_positions
+    end
+
+    def unfold_filters_by_prefix(filters, raw)
+      raw.each do |part|
+        filter, value = recognise_prefix(part)
+        if filters.has_key? filter
+          filters[filter] = Array(filters[filter])
+          filters[filter] << value
+        else
+          filters[filter] = value
         end
       end
+    end
 
-      filter_args
+    def recognised_prefix?(url_part)
+      recognise_prefix(url_part, raise_if_unrecognised: false).present?
     end
+
+    def recognise_prefix(url_part, raise_if_unrecognised: true)
+      url_to_filter_params.each do |url_prefix, filter|
+        pref = "#{url_prefix}#{PREFIX_SEPARATOR}"
+        if url_part.start_with? pref
+          return [filter, url_part.sub(pref, EMPTY_STRING)]
+        end
+      end
+
+      # check if it's the same prefix -> if it is in the indexed parts
+      url_part_divided = url_part.split(PREFIX_SEPARATOR)
+      param            = url_part_divided.first
+      if indexed_url_params_order.include?(param.to_s)
+        return [param.to_sym, url_part_divided.drop(1).join(PREFIX_SEPARATOR)]
+      end
+
+      if raise_if_unrecognised
+        raise UnrecognisedPrefixError, "url part: #{url_part}"
+      else
+        nil
+      end
+    end
+
+
+    ##########
+    # COMMON #
+    ##########
+
+    def get_separator_from_position_options(options)
+      options[:multiple_separator].presence || DEFAULT_MULTIPLE_SEPARATOR_FOR_POSITION
+    end
+
+    def filter_params(filter_args)
+      filter_args = filter_args.deep_dup
+      convert_to_lists(filter_args)
+      filter_params_treatment.call filter_args
+    end
+
+    def convert_to_lists(filter_args)
+      always_lists_fields.each do |field, config|
+        if filter_args.key? field
+          case config
+          when String, Regexp
+            filter_args[field] = filter_args[field].to_s.split(config)
+          else
+            filter_args[field] = Array(filter_args[field])
+          end
+        end
+      end
+    end
+
+    def prepare_always_lists_fields(given)
+      case given
+      when Array
+        given.map { |a| [a, true] }.to_h
+      when Hash
+        given
+      else
+        { given.to_sym => true }
+      end
+    end
+
   end
 end

data/lib/url_params_manager/version.rb

@@ -1,3 +1,3 @@
 module UrlParamsManager
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: url_params_manager
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eduardo Turiño
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-09 00:00:00.000000000 Z
+date: 2015-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport