rails_view_adapters 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 271a96685da34e2fef21042413b046c05bd3b48a
+  data.tar.gz: 9dcb4018a390cec96a55c604435ddbde14ccd023
+SHA512:
+  metadata.gz: 141a9618d9417e8fe45d72863d7c532489d16227ea51ec290657a52f4bdec96d3951356e09af831b0b8fe93ebbf6e3d694545c03c6468565d4d040fb7e61d0db
+  data.tar.gz: b0d4a193b1e85d9d8d563a7dbb999e14a2d8a78b9f82dd503174622ad555c285f2cc6da6d5153ca0eb33943aaecf78b2d286a8f923140c987b6150b913067796

data/.gitignore

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

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,181 @@
+# Copyright (c) 2015 The Regents of the University of Michigan.
+# All Rights Reserved.
+# Licensed according to the terms of the Revised BSD License
+# See LICENSE.md for details.
+
+AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 2.3
+
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Metrics/LineLength:
+  Max: 100
+  AllowHeredoc: true
+  AllowURI: true
+  URISchemes:
+    - http
+    - https
+
+Style/FirstParameterIndentation:
+  EnforcedStyle: consistent
+
+Style/AlignParameters:
+  # Alignment of parameters in multi-line method calls.
+  #
+  # The `with_first_parameter` style aligns the following lines along the same
+  # column as the first parameter.
+  #
+  #     method_call(a,
+  #                 b)
+  #
+  # The `with_fixed_indentation` style aligns the following lines with one
+  # level of indentation relative to the start of the line with the method call.
+  #
+  #     method_call(a,
+  #       b)
+  EnforcedStyle: with_fixed_indentation
+
+# Indentation of `when`.
+Style/CaseIndentation:
+  IndentWhenRelativeTo: end
+
+# This usually but not always does what we want; disable in individual places
+# where it gets it wrong
+Style/ClassAndModuleChildren:
+  EnforcedStyle: nested
+
+# Checks formatting of special comments
+Style/CommentAnnotation:
+  Enabled: false
+
+Style/Copyright:
+  Enabled: false
+
+Style/EmptyLineBetweenDefs:
+  # If true, this parameter means that single line method definitions don't
+  # need an empty line between them.
+  AllowAdjacentOneLineDefs: true
+
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Style/FileName:
+  # When true, requires that each source file should define a class or module
+  # with a name which matches the file name (converted to ... case).
+  # It further expects it to be nested inside modules which match the names
+  # of subdirectories in its path.
+  ExpectMatchingDefinition: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  MaxLineLength: 100
+
+# Checks the indentation of the first element in an array literal.
+Style/IndentArray:
+  # The value `special_inside_parentheses` means that array literals with
+  # brackets that have their opening bracket on the same line as a surrounding
+  # opening round parenthesis, shall have their first element indented relative
+  # to the first position inside the parenthesis.
+  #
+  # The value `consistent` means that the indentation of the first element shall
+  # always be relative to the first position of the line where the opening
+  # bracket is.
+  #
+  # The value `align_brackets` means that the indentation of the first element
+  # shall always be relative to the position of the opening bracket.
+  EnforcedStyle: consistent
+
+# Checks the indentation of the first key in a hash literal.
+Style/IndentHash:
+  # The value `special_inside_parentheses` means that hash literals with braces
+  # that have their opening brace on the same line as a surrounding opening
+  # round parenthesis, shall have their first key indented relative to the
+  # first position inside the parenthesis.
+  #
+  # The value `consistent` means that the indentation of the first key shall
+  # always be relative to the first position of the line where the opening
+  # brace is.
+  #
+  # The value `align_braces` means that the indentation of the first key shall
+  # always be relative to the position of the opening brace.
+  EnforcedStyle: consistent
+
+
+Style/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/MultilineOperationIndentation:
+  EnforcedStyle: indented
+
+Style/Next:
+  Enabled: false
+
+Style/RedundantReturn:
+  # When true allows code like `return x, y`.
+  AllowMultipleReturnValues: true
+
+# Use / or %r around regular expressions.
+Style/RegexpLiteral:
+  # If false, the cop will always recommend using %r if one or more slashes
+  # are found in the regexp string.
+  AllowInnerSlashes: true
+
+Style/Semicolon:
+  # Allow ; to separate several expressions on the same line.
+  AllowAsExpressionSeparator: true
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/SpaceInsideBlockBraces:
+  SpaceBeforeBlockParameters: false
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/WhileUntilModifier:
+  MaxLineLength: 100
+
+# checks whether the end keywords are aligned properly for `do` `end` blocks.
+Lint/BlockAlignment:
+  # The value `start_of_block` means that the `end` should be aligned with line
+  # where the `do` keyword appears.
+  # The value `start_of_line` means it should be aligned with the whole
+  # expression's starting line.
+  # The value `either` means both are allowed.
+  AlignWith: start_of_line
+
+# Align ends correctly.
+Lint/EndAlignment:
+  # The value `keyword` means that `end` should be aligned with the matching
+  # keyword (if, while, etc.).
+  # The value `variable` means that in assignments, `end` should be aligned
+  # with the start of the variable on the left hand side of `=`. In all other
+  # situations, `end` should still be aligned with the keyword.
+  # The value `start_of_line` means that `end` should be aligned with the start
+  # of the line which the matching keyword appears on.
+  AlignWith: start_of_line
+
+Lint/DefEndAlignment:
+  # The value `def` means that `end` should be aligned with the def keyword.
+  # The value `start_of_line` means that `end` should be aligned with method
+  # calls like `private`, `public`, etc, if present in front of the `def`
+  # keyword on the same line.
+  AlignWith: def
+
+Performance/RedundantMerge:
+  Enabled: false
+
+Style/WordArray:
+  EnforcedStyle: brackets

data/.travis.yml

@@ -0,0 +1,7 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+  - 2.2.1
+  
+before_install: gem install bundler -v 1.13.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rails_view_adapters.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2015, The Regents of the University of Michigan.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+* Neither the name of the The University of Michigan nor the
+  names of its contributors may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS OF THE UNIVERSITY OF MICHIGAN AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OF THE
+UNIVERSITY OF MICHIGAN BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO,PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,88 @@
+# Rails View Adapters
+
+This gem provides a 
+[DSL](http://www.rubydoc.info/github/mlibrary/rails_view_adapters/master/RailsViewAdapters/DefinitionProxy)
+for defining adapters that map your model's 
+representations to those of your views, and vice versa.  
+
+### Adapters are presenters
+
+The adapters can be used to convert a model to its public representation,
+including associated models, as well as support for arbitrary operations.
+
+```ruby
+FooAdapter.from_model(Foo.find(id)).to_public_hash
+```
+
+### Adapters wrap input parameters
+
+The adapters also understand how to "undo" the presentation logic,
+converting the public representation back to the model or models 
+that (may have) generated it.
+
+```ruby
+Bar.new(BarAdapter.from_public(params).to_params_hash)
+```
+
+## Usage
+
+### Basics 
+
+Define your adapter using the DSL.
+
+```ruby
+# lib/adapters/team_member_adapter.rb
+require "rails_view_adapters"
+RailsViewAdapters::Adapter.define(:team_member_adapter) do
+  map_simple :name, :author
+  map_date :join_date, :member_since, date_format
+  map_date :created_at, :created_at, date_format
+  map_date :updated_at, :updated_at, date_format
+  map_bool :admin, :super_user
+  hidden_field :secret
+  map_from_public :secret do |token|
+    { secret: token }
+  end
+  map_belongs_to :team, :favorite_team, model_class: Team
+  map_has_many :posts, :all_posts, sub_method: :body
+end
+```
+
+Then require and use it like you would any other class.
+
+```ruby
+require "lib/adapters/team_member_adapter"
+TeamMemberAdapter.from_model(TeamMember.find(params[:id])).to_public_hash
+```
+
+### Rails
+
+I've found it convenient to create a concern that gets invoked in a controller
+`before_action` to automatically grab the right adapter, instantiate it, and use
+it to modify the params hash.  Something like this:
+
+```ruby
+module Adaptation
+  extend ActiveSupport::Concern
+
+  included do
+    append_before_action :adapt_params
+  end
+
+  private
+  def adapt_params
+    adapter = "#{controller_path.classify.gsub("Controller", "")}Adapter".constantize
+    params.merge!(adapter.from_public(params).to_params_hash) {|key,lhs,rhs| rhs}
+  end
+end
+```
+
+### Testing Adapters
+
+Individual needs will vary, but for a reasonable integration test take a look at 
+`spec/integration/an_adapter_spec.rb`
+
+Do note that the above relies on your controllers and adapters being named predictably.
+
+## Documentation
+http://www.rubydoc.info/github/mlibrary/rails_view_adapters/

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/rails_view_adapters/adapter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+require "rails_view_adapters/definition_proxy"
+require "rails_view_adapters/map"
+require "rails_view_adapters/adapter_base"
+
+module RailsViewAdapters
+
+  # Top level namespace for defining the adapters.
+  module Adapter
+
+    FIELDS = [
+      :model_fields, :public_fields,
+      :to_maps, :from_maps, :simple_maps
+    ].freeze
+
+    def self.define(name, &block)
+      proxy = DefinitionProxy.new(Map.new)
+      proxy.instance_eval(&block)
+      Object.const_set(name.to_s.classify, adapter_from_map(proxy.map))
+    end
+
+    def self.adapter_from_map(map)
+      Class.new(AdapterBase) do
+        FIELDS.each do |method|
+          define_singleton_method method do
+            map.send(method)
+          end
+        end
+      end
+    end
+
+  end
+
+end

data/lib/rails_view_adapters/adapter_base.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+# Copyright (c) 2015 The Regents of the University of Michigan.
+# All Rights Reserved.
+# Licensed according to the terms of the Revised BSD License
+# See LICENSE.md for details.
+
+require "active_support/core_ext/hash"
+
+module RailsViewAdapters
+
+  # Base class on which adapters are defined.
+  class AdapterBase
+    # Create an instance from an ActiveRecord model.
+    # @param [ActiveRecord::AdapterBase] model
+    # @return the adapter
+    def self.from_model(model)
+      internals = {}
+      model_fields.each do |field|
+        internals[field] = model.send(field)
+      end
+      new(internals, {})
+    end
+
+    # Create an instance from a public representation.
+    # @param [ActionController::Parameters] public
+    # @return the adapter
+    def self.from_public(public)
+      internals = {}
+      simple_maps.each do |model_field, public_field|
+        internals[model_field] = public[public_field]
+      end
+
+      extras = {}
+      (public.keys.map(&:to_sym) - public_fields).each do |extra_key|
+        extras[extra_key] = public[extra_key]
+      end
+
+      from_maps.each do |public_field, process|
+        internals.merge!(process.call(public[public_field]))
+      end
+
+      new(internals, extras)
+    end
+
+    def initialize(internals, extras)
+      @internals = internals
+      @extras = extras
+      @public_hash = nil
+      @params_hash = nil
+    end
+
+    def to_params_hash
+      @params_hash ||= to_model_hash.merge(@extras.symbolize_keys) {|_key, lhs, _rhs| lhs }
+    end
+
+    def to_json(options = {})
+      to_public_hash.to_json(options)
+    end
+
+    def to_model_hash
+      @internals
+    end
+
+    def to_public_hash
+      unless @public_hash
+        @public_hash = {}
+        simple_maps.each do |model_field, public_field|
+          @public_hash[public_field] = @internals[model_field]
+        end
+        to_maps.each do |model_field, process|
+          @public_hash.merge!(process.call(@internals[model_field])) do |k, l, r|
+            merge_strategy.call(k, l, r)
+          end
+        end
+      end
+      @public_hash
+    end
+
+    private
+
+    # Define an instance method for each of the class methods
+    # we want to access, otherwise we have to prepend
+    # "self.class." each time.
+    [:simple_maps, :to_maps].each do |method_name|
+      define_method(method_name) do
+        self.class.send(method_name)
+      end
+    end
+
+    def merge_strategy
+      @merge_strategy ||= proc do |_key, lhs, rhs|
+        if lhs.respond_to?(:merge) && rhs.respond_to?(:merge)
+          lhs.merge(rhs)
+        else
+          rhs
+        end
+      end
+    end
+
+  end
+end

data/lib/rails_view_adapters/definition_proxy.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+module RailsViewAdapters
+
+  # Defines the DSL methods that are used to modify the underlying
+  # map.  This class is only used to evaluate the DSL calls, thereby
+  # modifying the Map.
+  class DefinitionProxy
+    attr_accessor :map
+    def initialize(adapter_map)
+      @map = adapter_map
+    end
+
+    # Register a simple one-to-one mapping.
+    # @param [Symbol] model_field
+    # @param [Symbol] public_field
+    def map_simple(model_field, public_field)
+      map.add_simple_map(model_field, public_field)
+    end
+
+    # Register a mapping from a model field to the public representation.
+    # @param [Symbol] model_field
+    # @param [Array<Symbol>] extra_public_fields Used to tell the adapter about
+    #   extra public fields created by this mapping.
+    # @yield [model_value] Given the value of the model's model_field, return
+    #   a hash of key:values pairs to merge into the public representation.
+    def map_to_public(model_field, extra_public_fields = [], &block)
+      map.add_to_map(model_field, &block)
+      extra_public_fields.each do |public_field|
+        map.add_public_field(public_field)
+      end
+    end
+
+    # Register a mapping from a public field to the model representation.
+    # @param [Symbol] public_field
+    # @yield [public_value] Given the value of public representation's
+    #   public_field, return a hash of key:value pairs to merge into
+    #   the internal model representation.
+    def map_from_public(public_field, &block)
+      map.add_from_map(public_field, &block)
+    end
+
+    # Register a hidden field, i.e. a field not present in public representations.
+    # @param [Symbol] model_field
+    def hidden_field(model_field)
+      map.add_model_field(model_field)
+    end
+
+    # Register a one-to-one mapping of a date field.
+    # @param [Symbol] model_field
+    # @param [Symbol] public_field
+    # @param [String] date_format The Date format to use.
+    def map_date(model_field, public_field, date_format)
+      raise ArgumentError if date_format.nil?
+      map_from_public public_field do |value|
+        { model_field => time_from_public(value) }
+      end
+      map_to_public model_field do |value|
+        { public_field => value.utc.strftime(date_format) }
+      end
+    end
+
+    # Register a one-to-one mapping of a boolean field
+    # @param [Symbol] model_field
+    # @param [Symbol] public_field
+    def map_bool(model_field, public_field)
+      map_from_public public_field do |value|
+        { model_field => to_bool(value) }
+      end
+
+      map_to_public model_field do |value|
+        { public_field => value }
+      end
+    end
+
+    # Register a mapping of a belongs_to association.
+    # @param [Symbol] model_field  The field on the model that holds the association,
+    #   usually the association's name.
+    # @param [Symbol] public_field The public field.
+    # @param [Hash] options
+    # @option options [Class] :model_class The class of the associated model,
+    #   if it cannot be inferred from the model_field.
+    # @option options [Symbol] :sub_method The method of the association model
+    #   that holds the desired data.  Default is :id.
+    # @option options [Symbol] :only Only create the to_map or the from_map, as
+    #   directed by setting this to :to or :from, respectively.
+    def map_belongs_to(model_field, public_field, options = {})
+      model_class = options[:model_class] || model_field.to_s.classify.constantize
+      sub_method = options[:sub_method] || :id
+      model_field_id = :"#{model_field.to_s.sub(/(_id|)\Z/, "_id")}"
+
+      unless options[:only] == :to
+        map_from_public public_field do |value|
+          record = model_class.send(:"find_by_#{sub_method}", value)
+          { model_field_id => record ? record.id : nil }
+        end
+      end
+
+      unless options[:only] == :from
+        map_to_public model_field_id do |id|
+          { public_field => model_class.find_by(id: id).send(sub_method) }
+        end
+      end
+    end
+
+    # Register a mapping of a has_many association.
+    # @param [Symbol] model_field  The field on the model that holds the association,
+    #   usually the association's name.
+    # @param [Symbol] public_field The public field.
+    # @param [Hash] options
+    # @option options [Class] :model_class The class of the model, if it cannot
+    #   be inferred from the model_field.
+    # @option options [Symbol] :sub_method The method of the association model
+    #   that holds the desired data.  If this isn't provided, it's assumed
+    #   to be the same as public_field.
+    def map_has_many(model_field, public_field, options = {})
+      model_class = options[:model_class] || model_field.to_s.classify.constantize
+      sub_method = options[:sub_method] || public_field
+
+      unless options[:only] == :to
+        map_from_public public_field do |value|
+          result = { model_field => model_class.where(sub_method => value) }
+          public_field_size = value.respond_to?(:size) ? value.size : 0
+          result[model_field] = result[model_field]
+            .to_a
+            .fill(nil, result[model_field].size, public_field_size - result[model_field].size)
+          result
+        end
+      end
+
+      unless options[:only] == :from
+        map_to_public model_field do |records|
+          { public_field => records.map(&sub_method.to_sym) }
+        end
+      end
+    end
+
+    private
+
+    def time_from_public(time)
+      if time.is_a? String
+        Time.zone.parse(time)
+      else
+        time
+      end
+    end
+
+    def to_bool(value)
+      return nil if value.nil? || value =~ /^(null|nil)$/i
+      return true if value == true || value =~ /^(true|t|yes|y|1)$/i
+      return false if value == false || value =~ /^(false|f|no|n|0)$/i
+      raise ArgumentError, "invalid value for boolean: \"#{value}\""
+    end
+
+  end
+end

data/lib/rails_view_adapters/map.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+module RailsViewAdapters
+
+  # Contains the information needed by the adapters
+  # to convert from one form to another.
+  class Map
+    attr_accessor :model_fields, :public_fields
+    attr_accessor :simple_maps, :to_maps, :from_maps
+    def initialize
+      @simple_maps = []
+      @model_fields = []
+      @public_fields = []
+      @to_maps = []
+      @from_maps = []
+    end
+
+    def add_model_field(model_field)
+      model_fields << model_field
+      self
+    end
+
+    def add_public_field(public_field)
+      public_fields << public_field
+      self
+    end
+
+    def add_simple_map(model_field, public_field)
+      simple_maps << [model_field, public_field]
+      add_model_field(model_field)
+      add_public_field(public_field)
+      self
+    end
+
+    def add_to_map(model_field, &block)
+      to_maps << [model_field, block]
+      add_model_field(model_field)
+      self
+    end
+
+    def add_from_map(public_field, &block)
+      from_maps << [public_field, block]
+      add_public_field(public_field)
+      self
+    end
+  end
+end

data/lib/rails_view_adapters/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module RailsViewAdapters
+  VERSION = "0.2.1"
+end