effective_addresses 0.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3c2f49eca2125797231243b395e2e1b9c6d7ea2
+  data.tar.gz: d660100feb8bb23c00736de9c854ab0742566b36
+SHA512:
+  metadata.gz: 6743fe38958a99b09216fd1c6578dce108198eaa88b621015b6f37e54b14f3a08a87a423dc12299578f9fdeaf25128097940845eb4dc4b02c230d2aee07b680d
+  data.tar.gz: 0d31cf09f163e7a84b3b0e7425a7bc83c2182226c714af93d9242013c18f4afbacf820e8036737660b3c705e2d38483a0cd70cd812c12903ebc37bd0e7ab6de6

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2013 Code and Effect Inc.
+Copyright 2014 Code and Effect Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,14 +1,16 @@
 # Effective Addresses
 
-Provides helper methods for dealing with a has_many :addresses relationship as a single method.
-Such as @user.billing_address and @user.billing_address=
+Extend any ActiveRecord object to have one or more named addresses. Includes a geographic region-aware custom form input backed by Carmen.
 
-Includes full validations for addresses with multiple categories.
+Creates methods such as `user.billing_address` and `user.billing_address=` for dealing with a has_many :addresses relationship as a single method.
 
-Includes a formtastic helper method to create/update the address of a parent object.
-Uses the Carmen gem so when a Country is selected, an AJAX request populates the State/Province fields as appropriate.
+Adds region-aware validations for provinces/states and postal codes.
 
-Rails >= 3.2.x, Ruby >= 1.9.x.  Has not been tested/developed for Rails4.
+Includes a Formtastic and SimpleForm one-liner method to drop in address fields to any form.
+
+Uses the Carmen gem internally so when a Country is selected, an AJAX request populates the province/state fields as appropriate.
+
+Rails 3.2.x and Rails 4 Support
 
 ## Getting Started
 
@@ -32,7 +34,7 @@ rails generate effective_addresses:install
 
 The generator will install an initializer which describes all configuration options and creates a database migration.
 
-If you want to tweak the table name (to use something other than the default 'addresses'), manually adjust both the configuration file and the migration now.
+If you want to tweak the table name (to use something other than the default `addresses`), manually adjust both the configuration file and the migration now.
 
 Then migrate the database:
 
@@ -40,7 +42,7 @@ Then migrate the database:
 rake db:migrate
 ```
 
-If you'd like to use the form helper method, require the javascript in your application.js
+And require the javascript in your application.js:
 
 ```ruby
 //= require effective_addresses
@@ -51,101 +53,155 @@ If you'd like to use the form helper method, require the javascript in your appl
 
 ### Model
 
-To use without any validations, just add the mixin to your existing model:
+Add the mixin to your existing model and specify the name or names of the addresses it should respond to:
 
 ```ruby
 class User
-  acts_as_addressable
+  acts_as_addressable :billing
 end
 ```
 
-This adds the following getters, along with the setters:
+This adds the following getters and setters:
 
 ```ruby
-@user.address
 @user.billing_address
-@user.shipping_address
-@user.primary_address
-@user.secondary_address
+@user.billing_address=
+@user.billing_addresses
 ```
 
-You can also define validations as follows:
+Calling `user.billing_address` will return a single `Effective::Address` object.  Calling `user.billing_addresses` will return an array of `Effective:Address` objects.
+
+You can also specify a `:presence` validation as follows:
 
 ```ruby
 class User
-  acts_as_addressable :require_billing => true, :require_shipping => true
+  acts_as_addressable :billing => true, :shipping => false
 end
 ```
 
-This means when a User is created, it will not be valid unless a billing_address and shipping_address exist and are valid.
-
-### Multiple Addresses
-
-Everytime an address is changed, an additional address record is created.  The latest address will always be returned by:
+or
 
 ```ruby
-@user.billing_address
+class User
+  acts_as_addressable :billing => {:presence => true, :use_full_name => false}
+end
 ```
 
-You can find all past addresses (including the current one) by:
+or
 
 ```ruby
-@user.billing_addresses
+class User
+  acts_as_addressable :billing
+
+  validates_presence_of :billing_address
+end
 ```
 
-### Form Helper
+This means when a User is created, it will not be valid unless a billing_address exist and is valid.
 
-Use the helper in a formtastic form to quickly create the address fields 'f.inputs'.  This example is in HAML:
 
-```ruby
-= semantic_form_for @user do |f|
-  = f.inputs :name => "Your Information" do
-    = f.input :email
-    = f.input :name
+### Full Name
 
-  = effective_address_fields(f, :category => 'billing') # 'shipping', 'primary', 'secondary'
+Sometimes you want to collect a `full_name` field with your addresses, such as in the case of a mailing address; other times, it's an unnecessary field.
 
-  = f.action :submit
-```
+When you specify the config option `config.use_full_name = true` all `acts_as_addressable` defined addresses will use `use_full_name => true` by default.
 
-Currently only supports Formtastic.
+This can be overridden on a per-address basis when declared in the model.
 
-Assuming the javascript has been properly required (as above), when you select a country from the dropdown
-an AJAX GET request will be made to '/effective/address/subregions/:country_code' and populate the state dropdown with the appropriate states or provinces
+When `use_full_name == true`, any calls to `effective_address_fields` form helper will display the full_name input, and the model will `validate_presence_of :full_name`.
 
 
-## License
+### Address Validations
 
-MIT License.  Copyright Code and Effect Inc. http://www.codeandeffect.com
+Address1, City, Country and Postal/Zip Code are all required fields.
 
-You are not granted rights or licenses to the trademarks of Code and Effect
+If the selected Country has provinces/states (not all countries do), then the province/state field will be required.
 
-## Notes
+If the country is Canada or United States, then the postal/zip code formatting will be enforced.
 
-This is a work in progress gem.  It needs smarter validations, dynamic methods and google maps integration
+This validation on the postal code/zip format can be disabled via the config/initializers `validate_postal_code_format` setting
 
-### Testing
+Canadian postal codes will be automatically upcased and formatted to a consistent format: `T5Z 3A4` (capitalized with a single space).
 
-The test suite for this gem is unfortunately not yet complete.
 
-Run tests by:
+### Multiple Addresses
+
+Everytime an address is changed, an additional address record is created.  The latest address will always be returned by:
 
 ```ruby
-rake spec
+@user.billing_address
 ```
 
+You can find all past addresses (including the current one) by:
 
+```ruby
+@user.billing_addresses
+```
+
+### Strong Parameters
+
+Make your controller aware of the `acts_as_addressable` passed parameters:
+
+```ruby
+def permitted_params
+  params.require(:base_object).permit(
+    :billing_address => EffectiveAddresses.permitted_params,
+    :shipping_address => EffectiveAddresses.permitted_params
+  )
+end
+```
+
+The actual permitted parameters are:
+
+```ruby
+[:full_name, :address1, :address2, :city, :country_code, :state_code, :postal_code]
+```
+
+### Form Helpers
 
+Use the helper in a Formtastic or SimpleForm form to quickly create the address fields.  This example is in HAML:
 
+```ruby
+= semantic_form_for @user do |f|
+  %h3 Billing Address
+  = effective_address_fields(f, :billing_address)
+
+  = f.action :submit
+
+= simple_form_for @user do |f|
+  %h3 Billing Address
+  = effective_address_fields(f, :billing_address)
+
+  = f.submit 'Save'
+```
 
+Currently only supports Formtastic and SimpleForm.
 
+When you select a country from the select input an AJAX GET request will be made to `effective_addresses.address_subregions_path` (`/addresses/subregions/:country_code`) which populates the province/state dropdown with the selected country's states or provinces.
 
 
+## License
+
+MIT License.  Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
 
+Code and Effect is the product arm of [AgileStyle](http://www.agilestyle.com/), an Edmonton-based shop that specializes in building custom web applications with Ruby on Rails.
 
 
+## Testing
 
+The test suite for this gem is unfortunately not yet complete.
 
+Run tests by:
 
+```ruby
+rake spec
+```
 
+## Contributing
 
+1. Fork it
+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. Bonus points for test coverage
+6. Create new Pull Request

data/app/assets/javascripts/effective_addresses/address_fields.js.coffee

@@ -1,13 +1,14 @@
-$(document).on 'change', "select[data-behavior='address-country']", (event) ->
+$(document).on 'change', "select[data-effective-address-country]", (event) ->
   country_code = $(this).val()
+  uuid = $(this).data('effective-address-country')
 
-  url = "/effective/address/subregions/#{country_code}"
-  state_select = $(this).parent().parent().find("li > select[data-behavior='address-state']").first()
+  url = "/addresses/subregions/#{country_code}"
+  state_select = $(this).closest('form').find("select[data-effective-address-state='#{uuid}']").first()
 
   if country_code.length == 0
-    state_select.attr('disabled', 'disabled')
-    state_select.html('<option value="">please select a country</option>')
+    state_select.prop('disabled', true).parent('.form-group').addClass('disabled')
+    state_select.html('<option value="">Please choose a country first</option>')
   else
-    state_select.removeAttr('disabled')
+    state_select.prop('disabled', false).parent('.form-group').removeClass('disabled')
     state_select.find('option').first().text('loading...')
     state_select.load(url)

data/app/controllers/effective/addresses_controller.rb

@@ -4,12 +4,12 @@ module Effective
     respond_to :json
 
     def subregions
-      country_code = params[:country_code]
+      @subregions = Carmen::Country.coded(params[:country_code]).try(:subregions)
 
-      if country_code.present?
-        render :partial => 'effective/addresses/subregions', :locals => {:country_code => country_code}
+      if @subregions.present?
+        render :partial => 'effective/addresses/subregions'
       else
-        render :text => '', :status => :unprocessable_entity
+        render :text => "<option value=''>None Available</option>"
       end
     end
   end

data/app/helpers/effective_addresses_helper.rb

@@ -1,27 +1,45 @@
 require 'carmen-rails'
 
 module EffectiveAddressesHelper
-  def effective_address_fields(form, options = {})
-    opts = {:f => form, :category => 'address', :skip_full_name => false}.merge(options)
-
-    case opts[:category]
-    when 'shipping'
-      opts[:name] = 'Shipping Address'
-      opts[:method] = :shipping_address
-    when 'billing'
-      opts[:name] = 'Billing Address'
-      opts[:method] = :billing_address
-    when 'primary'
-      opts[:name] = 'Primary Address'
-      opts[:method] = :primary_address
-    when 'secondary'
-      opts[:name] = 'Secondary Address'
-      opts[:method] = :secondary_address
+  def effective_address_fields(form, method = 'billing', options = {})
+    method = (method.to_s.include?('_address') ? method.to_s : "#{method}_address")
+
+    required = (form.object._validators[method.to_sym].any? { |v| v.kind_of?(ActiveRecord::Validations::PresenceValidator) && (v.options[:if].blank? || (v.options[:if].respond_to?(:call) ? f.object.instance_exec(&v.options[:if]) : v.options[:if])) } rescue true)
+
+    opts = {:f => form, :method => method, :required => required}.merge(options)
+
+    if form.class.name == 'SimpleForm::FormBuilder'
+      render :partial => 'effective/addresses/address_fields_simple_form', :locals => opts
+    elsif form.class.name == 'Formtastic::FormBuilder'
+      render :partial => 'effective/addresses/address_fields_formtastic', :locals => opts
+    else
+      raise 'Unsupported FormBuilder.  You must use formtastic or simpleform. Sorry.'
+    end
+  end
+
+  def region_options_for_simple_form_select(regions = nil)
+    if regions.present?
+      countries = regions
+    elsif EffectiveAddresses.country_codes == :all
+      countries = Carmen::Country.all
     else
-      opts[:name] = 'Address'
-      opts[:method] = :address
+      countries = Carmen::Country.all.select { |c| (EffectiveAddresses.country_codes || []).include?(c.code) }
     end
 
-    render :partial => 'effective/addresses/address_fields', :locals => opts
+    collection = countries.map { |c| [c.name, c.code] }.sort! { |a, b| a.first <=> b.first }
+
+    if regions.blank? && EffectiveAddresses.country_codes_priority.present?
+      collection.insert(0, ['---------------------', '', :disabled])
+
+      EffectiveAddresses.country_codes_priority.reverse.each do |code|
+        if (country = countries.coded(code))
+          collection.insert(0, [country.name, country.code])
+        end
+      end
+    end
+
+    collection
   end
+
 end
+

data/app/models/concerns/acts_as_addressable.rb

@@ -1,107 +1,85 @@
 # ActsAsAddressable
-#
-# This module creates .billing_address, .shipping_address and .address methods
-# it tricks a has_many relationship into singleton methods
-#
-# Mark your model with 'acts_as_addressable'
-#
-# there are no additional migrations needed for this module to work.
-#
-# By default, addresses are NOT required
-#
-# If you want to validate presence, please mark your model
-# acts_as_addressable :require_billing => true, :require_address => true, :require_shipping => true
-#
-# Please see app/views/admin/users/_form.html.haml for an example of how to use this in a formtastic form
-#
 
 module ActsAsAddressable
   extend ActiveSupport::Concern
 
   module ActiveRecord
-    def acts_as_addressable(options = {})
-      @acts_as_addressable_opts = {:require_shipping => false, :require_billing => false, :require_primary => false, :require_secondary => false, :require_address => false}.merge(options)
+    def acts_as_addressable(*options)
+      @acts_as_addressable_opts = options || []
       include ::ActsAsAddressable
     end
   end
 
   included do
-    has_many :addresses, :as => :addressable, :class_name => "Effective::Address", :dependent => :delete_all
-
-    validates_with BillingAddressValidator if @acts_as_addressable_opts[:require_billing]
+    has_many :addresses, :as => :addressable, :class_name => 'Effective::Address', :dependent => :delete_all
+
+    # Setup validations and methods
+    categories = @acts_as_addressable_opts.try(:flatten) || []
+
+    if categories.first.kind_of?(Hash) # We were passed some validation requirements
+      categories = categories.first
+
+      categories.each do |category, validation| # billing, shipping
+        category = category.to_s.gsub('_address', '')
+
+        self.send(:define_method, "#{category}_address") { effective_address(category) }
+        self.send(:define_method, "#{category}_addresses") { effective_addresses(category) }
+        self.send(:define_method, "#{category}_address=") { |atts| set_effective_address(category, atts) }
+
+        validates "#{category}_address", :effective_address_valid => true
+
+        if validation.kind_of?(Hash)
+          validates "#{category}_address", :presence => validation.fetch(:presence, false)
+          validates "#{category}_address", :effective_address_full_name_presence => validation.fetch(:use_full_name, EffectiveAddresses.use_full_name)
+        elsif validation == true
+          validates "#{category}_address", :presence => true
+          validates "#{category}_address", :effective_address_full_name_presence => EffectiveAddresses.use_full_name
+        end
+      end
+    else # No validation requirements passed
+      categories.each do |category|
+        category = category.to_s.gsub('_address', '')
+
+        self.send(:define_method, "#{category}_address") { effective_address(category) }
+        self.send(:define_method, "#{category}_addresses") { effective_addresses(category) }
+        self.send(:define_method, "#{category}_address=") { |atts| set_effective_address(category, atts) }
+
+        validates "#{category}_address", :effective_address_valid => true
+        validates "#{category}_address", :effective_address_full_name_presence => EffectiveAddresses.use_full_name
+      end
+    end
   end
 
   module ClassMethods
   end
 
-  def single_addresses
-    addresses.select { |address| address.category == 'address' }
-  end
-
-  def address
-    single_addresses.last
-  end
-
-  def address=(address_atts)
-    add = (address_atts.kind_of?(Effective::Address) ? address_atts.dup : Effective::Address.new(address_atts))
-    add.category = 'address'
-    addresses << add if !add.empty? and !(add == address)
-  end
-
-  def shipping_addresses
-    addresses.select { |address| address.category == 'shipping' }
-  end
-
-  def shipping_address
-    shipping_addresses.last
-  end
-
-  def shipping_address=(address_atts)
-    add = (address_atts.kind_of?(Effective::Address) ? address_atts.dup : Effective::Address.new(address_atts))
-    add.category = 'shipping'
-    addresses << add if !add.empty? and !(add == shipping_address)
-  end
-
-  def billing_addresses
-    addresses.select { |address| address.category == 'billing' }
+  def effective_addresses(category)
+    category = category.to_s
+    addresses.select { |address| address.category == category }
   end
 
-  def billing_address
-    billing_addresses.last
+  def effective_address(category)
+    effective_addresses(category).last
   end
 
-  def billing_address=(address_atts)
-    add = (address_atts.kind_of?(Effective::Address) ? address_atts.dup : Effective::Address.new(address_atts))
-    add.category = 'billing'
-    addresses << add if !add.empty? and !(add == billing_address)
-  end
+  def set_effective_address(category, atts)
+    raise ArgumentError.new("Effective::Address #{category}_address= expecting an Effective::Address or Hash of attributes") unless (atts.kind_of?(Effective::Address) || atts.kind_of?(Hash) || atts == nil)
 
-  def primary_addresses
-    addresses.select { |address| address.category == 'primary' }
-  end
+    atts = HashWithIndifferentAccess.new(atts.kind_of?(Effective::Address) ? atts.attributes : atts)
 
-  def primary_address
-    primary_addresses.last
-  end
+    add = Effective::Address.new(
+      :category     => category,
+      :full_name    => atts[:full_name],
+      :address1     => atts[:address1],
+      :address2     => atts[:address2],
+      :city         => atts[:city],
+      :state_code   => atts[:state_code],
+      :country_code => atts[:country_code],
+      :postal_code  => atts[:postal_code]
+    )
 
-  def primary_address=(address_atts)
-    add = (address_atts.kind_of?(Effective::Address) ? address_atts.dup : Effective::Address.new(address_atts))
-    add.category = 'primary'
-    addresses << add if !add.empty? and !(add == primary_address)
+    self.addresses << add unless (add.empty? || add == effective_address(category))
   end
 
-  def secondary_addresses
-    addresses.select { |address| address.category == 'secondary' }
-  end
-
-  def secondary_address
-    secondary_addresses.last
-  end
-
-  def secondary_address=(address_atts)
-    add = (address_atts.kind_of?(Effective::Address) ? address_atts.dup : Effective::Address.new(address_atts))
-    add.category = 'secondary'
-    addresses << add if !add.empty? and !(add == secondary_address)
-  end
 end
 

data/app/models/effective/address.rb

@@ -4,25 +4,45 @@ module Effective
   class Address < ActiveRecord::Base
     self.table_name = EffectiveAddresses.addresses_table_name.to_s
 
+    POSTAL_CODE_CA = /\A[A-Z]{1}\d{1}[A-Z]{1}\ \d{1}[A-Z]{1}\d{1}\z/  # Matches 'T5Z 2B1'
+    POSTAL_CODE_US = /\A\d{5}\z/ # Matches 5 digits
+
     belongs_to :addressable, :polymorphic => true, :touch => true
 
     structure do
-      category        :string, :validates => [:presence, :inclusion => { :in => %w(billing shipping primary secondary address)}]
+      category        :string, :validates => [:presence]
+
+      full_name       :string
 
-      full_name       :string, :validates => [:presence]
       address1        :string, :validates => [:presence]
       address2        :string
+
       city            :string, :validates => [:presence]
-      state_code      :string, :validates => [:presence]
+
+      state_code      :string
       country_code    :string, :validates => [:presence]
+
       postal_code     :string, :validates => [:presence]
+
       timestamps
     end
 
-    default_scope order(:updated_at)
+    validates_presence_of :state_code, :if => Proc.new { |address| address.country_code.blank? || Carmen::Country.coded(address.country_code).try(:subregions).present? }
+
+    validates_format_of :postal_code, :with => POSTAL_CODE_CA,
+      :if => proc { |address| Array(EffectiveAddresses.validate_postal_code_format).include?('CA') && address.country_code == 'CA' },
+      :allow_blank => true,  # We're already checking for presence above
+      :message => 'is an invalid Canadian postal code'
+
+    validates_format_of :postal_code, :with => POSTAL_CODE_US,
+      :if => proc { |address| Array(EffectiveAddresses.validate_postal_code_format).include?('US') && address.country_code == 'US' },
+      :allow_blank => true,  # We're already checking for presence above
+      :message => 'is an invalid United States zip code'
 
-    scope :billing_addresses, -> { where(:category => 'billing') }
-    scope :shipping_addresses, -> { where(:category => 'shipping') }
+    default_scope -> { order(:updated_at) }
+
+    scope :billing, -> { where(:category => 'billing') }
+    scope :shipping, -> { where(:category => 'shipping') }
 
     def first_name
       full_name.split(' ').first rescue full_name
@@ -39,10 +59,7 @@ module Effective
     def state
       Carmen::Country.coded(country_code).subregions.coded(state_code).name rescue ''
     end
-
-    def province
-      Carmen::Country.coded(country_code).subregions.coded(state_code).name rescue ''
-    end
+    alias_method :province, :state
 
     def country=(country_string)
       value = Carmen::Country.named(country_string) || Carmen::Country.coded(country_string.try(:upcase))
@@ -51,23 +68,49 @@ module Effective
 
     def state=(state_string)
       if country.present?
-        value = Carmen::Country.coded(country_code).subregions.named(state_string) || Carmen::Country.coded(country_code).subregions.coded(state_string.try(:upcase))
+        subregions = (Carmen::Country.coded(country_code).subregions rescue nil)
+
+        if subregions.present?
+          value = subregions.named(state_string) || subregions.coded(state_string.try(:upcase))
+        else
+          value = nil
+        end
+
         self.state_code = value.code if value.present?
       else
         Rails.logger.info 'No country set.  Try calling country= before state='
         puts 'No country set.  Try calling country= before state='
       end
     end
+    alias_method :province=, :state=
+
+    # If the country is Canada or US, enforce the correct postal code/zip code format
+    def postal_code=(code)
+      if code.presence.kind_of?(String)
+        if country_code == 'CA'
+          code = code.upcase.gsub(/[^A-Z0-9]/, '')
+          code = code.insert(3, ' ') if code.length == 6
+        elsif country_code == 'US'
+          code = code.gsub(/[^0-9]/, '')
+        end
+      end
+
+      super(code)
+    end
 
     def postal_code_looks_canadian?
-      postal_code.gsub(/ /, '').strip.match(/^\D{1}\d{1}\D{1}\-?\d{1}\D{1}\d{1}$/).present? rescue false # Matches T5T2T1 or T5T-2T1
+      postal_code.to_s.match(POSTAL_CODE_CA).present?
+    end
+
+    def postal_code_looks_american?
+      postal_code.to_s.match(POSTAL_CODE_US).present?
     end
 
     def ==(other_address)
       self_attrs = self.attributes
       other_attrs = other_address.respond_to?(:attributes) ? other_address.attributes : {}
 
-      [self_attrs, other_attrs].each { |attrs| attrs.except!('id', 'created_at', 'updated_at', 'addressable_type', 'addressable_id', 'address2') }
+      [self_attrs, other_attrs].each { |attrs| attrs.except!('id', 'created_at', 'updated_at', 'addressable_type', 'addressable_id') }
 
       self_attrs == other_attrs
     end
@@ -75,15 +118,18 @@ module Effective
     # An address may be set with a category but nothing else
     # This is considered empty
     def empty?
-      !full_name.present? and !address1.present? and !address2.present? and !city.present? and !state_code.present? and !country_code.present? and !postal_code.present?
+      !address1.present? && !address2.present? && !city.present? && !state_code.present? && !country_code.present? && !postal_code.present?
     end
 
     def to_s
-      output = "#{full_name}\n"
-      output += "#{address1}\n"
+      output = ''
+      output += "#{full_name}\n" if full_name.present?
+      output += "#{address1}\n" if address1.present?
       output += "#{address2}\n" if address2.present?
-      output += "#{city}, #{state}\n"
-      output += "#{country}, #{postal_code}"
+      output += [city.presence, state.presence].compact.join(', ')
+      output += '\n' if city.present? || state.present?
+      output += [country.presence, postal_code.presence].compact.join(', ')
+      output
     end
 
     def to_html