url_params_manager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 20007cb9733a6548af2f7fb5dbb1c3e1bf4cf4c1
+  data.tar.gz: fd0c71ec50dd016dd88291ab42118c05a139dcbd
+SHA512:
+  metadata.gz: f255f9748eef06fb3f09fc28b13cd5d092ddaecfe9ead9d9d11375cd0fc86539f24c222b194d0cce83ee77d9220f43c4d9a72a843c2c2b86edbbbfc06b8d11e6
+  data.tar.gz: 64f773adecfad17d95a6d29aedf715c866ace65113d366b5cb0a48e42251d04d17c7e890a4c5b46eeb2220bef9dab75fa51bb46c21b1682879cca35aa7d26ba0

data/.gitignore

@@ -0,0 +1,10 @@
+/.idea
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+cache: bundler
+
+addons:
+  code_climate:
+    repo_token: 0af3f52c81bbe7c92359d70d648edc9fae739e6555719fa2164c8d76dd71a314
+
+rvm:
+  - 2.1.6
+  - 2.2.2
+
+script: 'bundle exec rake spec'
+
+notifications:
+  email:
+    recipients:
+      - eturino@eturino.com
+    on_failure: change
+    on_success: never

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in feature_toggle_service.gemspec
+gemspec
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/README.md

@@ -0,0 +1,206 @@
+# UrlParamsManager
+
+[![Gem Version](https://badge.fury.io/rb/url_params_manager.svg)](http://badge.fury.io/rb/url_params_manager)
+[![Build Status](https://travis-ci.org/artirix/url_params_manager.svg?branch=master)](https://travis-ci.org/artirix/url_params_manager)
+[![Code Climate](https://codeclimate.com/github/artirix/url_params_manager/badges/gpa.svg)](https://codeclimate.com/github/artirix/url_params_manager)
+[![Test Coverage](https://codeclimate.com/github/artirix/url_params_manager/badges/coverage.svg)](https://codeclimate.com/github/artirix/url_params_manager/coverage)
+
+Allows SEO Friendly urls for search pages to be built easily.
+ 
+The urls will look like: `example.org/my-search/color-black/color-red/size-big/page-3` and will end up in this params: `{ color: ['black', 'red'], size: 'big', page: '3' }`.
+
+## Usage
+
+With this gem you can specify what parameters will be in the path and what will be added to the querystring. 
+
+By default all parameters will be in the querystring, unless specified otherwise. Those are the *indexed params*.
+
+The indexed params follow these rules:
+
+1. they will be added in a `"#{param_prefix}-#{value}` pairs.
+2. the order of the pairs in the URL is determined by the priority of the params in the config
+3. in case of multivalued, multiple param-value pairs will be added, following value's alphabetical order
+
+### Param name vs Param Prefix
+
+We use this to "translate" the params from how they're known in the app to what they're known in the URLs. With this, we can change how the param is named in the URLs without changing it in the app. This will help us with white-labels config, multi-language configs, or SEO/UX related changes.
+
+The "Param Name" or "Param name in the App" is how the param is known in the app, how it'll be accessed in Rails' params.
+The "Param Prefix" or "Param alias in the URL" is how the param will be shown in the URL, either in the path or in the querystring.
+
+The "prefix -> name" map are set on the config of the UrlParamsManager.
+
+By default, if the config does not say otherwise, the prefix and the name are the same.
+
+important: if the param is an indexed param (it's shown in the path not in the querystring), then we have to add it to this hash, even with the same name:
+ie: 
+
+```ruby
+map = {
+  prefix:    :real_name,
+  same_name: :same_name,
+  page:      :page,
+}
+```
+
+### Indexed vs non Indexed params
+
+Indexed params appear in the path, ordered (following a priority order set in the config of the UrlParamsManager).
+
+Non Indexed params are every other param, and they appear in the querystring.
+
+note: We specify the indexed params using the Param Prefix (aka Param alias in the URL)
+
+note: Indexed Params may have multiple values but those will be *UNORDERED*. (See the example for reasoning).
+
+### Default Values
+
+The config can specify default values for specific params. That means that:
+
+- if the param does not appear in the URL, we'll give the param the default value in the app.
+- if the param is given the default app, the resulting URL will not have the param: if the param has the default value it is ignored when building the URL.
+
+The default value can be a list.
+
+note: We specify the default values using the Param Name. 
+
+## Example of use and Config
+
+### UrlParamsManager object
+
+```ruby
+# List of Params Prefixes to be considered as indexed params (in the path, not in the querystring)
+indexed_url_params_order = [
+  :feat,
+  :cap,
+  :ndef,
+  # ALWAYS LAST
+  :page
+]
+
+# Param Prefix => Param name in the app
+url_to_filter_params = {
+  feat: :feature, # indexed => in URL
+  cap:  :capacity, # indexed => in URL
+  some: :something, # not indexed => in querystring
+  ndef: :non_default, # value with default
+  page: :page,
+}
+
+# Default values for the params
+default_params = {
+  something:          99,
+  non_default:        'paco',
+  with_default_value: 2,
+  with_default_list:  [1, 2],
+}
+
+# UrlParamsManager object
+@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
+                            app_url_helpers:          Rails.application.routes.url_helpers, # Object to receive the URL's Path calls (usually Rails URL Helpers)
+                            default_params:           default_params # Default Params map
+```
+
+### Building URLs
+ 
+```ruby
+pars = {
+  capacity:           ['25+'],
+  page:               2,
+  feature:            ['swimming-pool', 'helipad'],
+  something:          ['other', 'another'],
+  with_default_value: 2,
+  with_default_list:  [2, 1],
+  non_default:        'ohmy',
+}
+
+expected_path = @upm.my_search_path(pars) 
+  # => '/search/feat-helipad/feat-swimming-pool/cap-25+/ndef-ohmy/page-2?some%5B%5D=another&some%5B%5D=other'
+
+# capacity => indexed with prefix 'cap'
+# page => indexed with prefix 'page'
+# feature => indexed with prefix 'feat'. Both values are shown, alpha-ordered.
+# something => not indexed, using prefix (or 'Param Alias in URL') as key and the values alpha-ordered.
+# with_default_value => since it has the default value, it does not appear
+# with_default_list => since it has the default value, it does not appear. Note that we gave it the same values but in different order
+# non_default => indexed with prefix 'ndef'
+
+```
+
+### Rails config for interpreting the URL
+
+routes.rb file:
+```ruby
+
+Rails.application.routes.draw do
+  
+  get 'search(/*filters)', to: 'articles#index', as: :articles_search
+end
+```
+
+With that routes config, we'll have in `params` in the controller the indexed params plus a param "filters" with the string of all the indexed params.
+
+We'll use the UrlParamsManager defined before to convert that into a hash of params that we can use internally.
+
+This will put together the indexed params in the path with the non indexed params in the querystring, and it will translate the param names back to the Param name to use in the app.
+
+```ruby
+class ArticlesController < ApplicationController
+
+  SEARCH_IGNORE_PARAMS = ['controller', 'action'].map &:freeze
+
+  def index
+    @articles = Article.search(search_params)
+  end
+
+  private
+  def search_params
+    @upm.filters_from_url_params params.reject { |k, _| SEARCH_IGNORE_PARAMS.include? k }
+  end
+end
+```
+
+With a URL like we built before: `'/search/feat-helipad/feat-swimming-pool/cap-25+/ndef-ohmy/page-2?some%5B%5D=another&some%5B%5D=other'` and this config, `Article.search` will receive a hash with:
+
+```ruby
+{
+  capacity:           ['25+'],
+  page:               2,
+  feature:            ['helipad', 'swimming-pool'],
+  something:          ['another', 'other'],
+  with_default_value: 2,
+  with_default_list:  [1, 2],
+  non_default:        'ohmy',
+}
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'url_params_manager'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install url_params_manager
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/artirix/url_params_manager/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+# Default directory to look in is `/specs`
+# Run with `rake spec`
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color']
+end
+
+task default: :spec
+

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "url_params_manager"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/url_params_manager.rb

@@ -0,0 +1,13 @@
+require 'active_support/all'
+require 'url_params_manager/unrecognised_prefix_error'
+require 'url_params_manager/service'
+require 'url_params_manager/version'
+
+module UrlParamsManager
+  def self.for(url_to_filter_params: nil, indexed_url_params_order: nil, app_url_helpers: nil, default_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
+  end
+end

data/lib/url_params_manager/service.rb

@@ -0,0 +1,128 @@
+module UrlParamsManager
+  class Service
+    attr_reader :app_url_helpers, :url_to_filter_params, :indexed_url_params_order, :filter_to_url_params, :default_params
+
+    def initialize(url_to_filter_params: nil, indexed_url_params_order: nil, app_url_helpers: nil, default_params: {})
+      @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
+    end
+
+    # for url/path methods from filter args
+    def method_missing(method, args)
+      path_method method, args
+    end
+
+    # for filters from url/path params
+    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.merge querystring_to_filters(params)
+    end
+
+    def querystring_to_filters(querystring_params)
+      querystring_params.inject({}) do |h, (k, v)|
+        new_key    = url_to_filter_params[k] || k
+        h[new_key] = v
+        h
+      end
+    end
+
+    private
+    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)
+      valid_filter_args = remove_defaults(filter_args)
+      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 }
+
+      # sorting indexed part
+      sorted_uri_args   = sort_uri_filters(in_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)
+        end
+      ]
+
+      Hash[
+        keys_sorted.map do |k, v|
+          sorted_v = v.respond_to?(:sort) ? v.sort : v
+          [k, sorted_v]
+        end
+      ]
+
+    end
+
+    def translate_filter_keys(filter_args)
+      Hash[
+        filter_args.map do |k, v|
+          [
+            filter_to_url_params[k] || k, # new key -> translated one, or the original if no translation available
+            v
+          ]
+        end
+      ]
+    end
+
+    def generate_uri_part(in_uri_args)
+      in_uri_args.inject([]) do |uri, (key, value)|
+        Array(value).each do |v|
+          uri << "#{key}-#{v}"
+        end
+        uri
+      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
+  end
+end

data/lib/url_params_manager/unrecognised_prefix_error.rb

@@ -0,0 +1,4 @@
+module UrlParamsManager
+  class UnrecognisedPrefixError < StandardError
+  end
+end

data/lib/url_params_manager/version.rb

@@ -0,0 +1,3 @@
+module UrlParamsManager
+  VERSION = "0.1.0"
+end

data/url_params_manager.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'url_params_manager/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'url_params_manager'
+  spec.version       = UrlParamsManager::VERSION
+  spec.authors       = ['Eduardo Turiño', 'Reuben Sutton']
+  spec.email         = ['eturino@eturino.com', 'reuben.sutton@gmail.com']
+
+  spec.summary       = %q{Allows SEO Friendly urls for search pages to be built easily. Intended to be used with Rails.}
+  # spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = 'https://github.com/artirix/url_params_manager'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com' to prevent pushes to rubygems.org, or delete to allow pushes to any server."
+  # end
+
+  spec.add_dependency 'activesupport', '~> 4'
+
+  spec.add_development_dependency 'bundler', '~> 1.9'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rspec-given'
+  spec.add_development_dependency 'rspec-nc'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'pry-nav'
+  spec.add_development_dependency 'pry-rescue'
+  spec.add_development_dependency 'pry-stack_explorer'
+  spec.add_development_dependency 'pry-doc'
+end

metadata

@@ -0,0 +1,214 @@
+--- !ruby/object:Gem::Specification
+name: url_params_manager
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eduardo Turiño
+- Reuben Sutton
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-05-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-given
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-nc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-rescue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-stack_explorer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-doc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- eturino@eturino.com
+- reuben.sutton@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/url_params_manager.rb
+- lib/url_params_manager/service.rb
+- lib/url_params_manager/unrecognised_prefix_error.rb
+- lib/url_params_manager/version.rb
+- url_params_manager.gemspec
+homepage: https://github.com/artirix/url_params_manager
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Allows SEO Friendly urls for search pages to be built easily. Intended to
+  be used with Rails.
+test_files: []
+has_rdoc: