carmen-rails 1.0.0.beta2 → 1.0.0.beta3

data/README.md

@@ -9,7 +9,7 @@ carmen-rails is a Rails 3 plugin that supplies two new form helper methods:
 Just add carmen-rails to your Gemfile:
 
 ```ruby
-gem 'carmen-rails', '1.0.0.pre'
+gem 'carmen-rails', '~> 1.0.0.beta3'
 ```
 
 ## Usage
@@ -18,14 +18,35 @@ gem 'carmen-rails', '1.0.0.pre'
 <%= form_for(@order) do |f| %>
   <div class="field">
     <%= f.label :country_code %><br />
-    <%= f.country_select :country_code, priority: %w(US CA), prompt: 'Please select a country' %>
+    <%= f.country_select :country_code, {priority: %w(US CA)}, prompt: 'Please select a country' %>
   </div>
 <% end %>
 ```
 
-More docs coming soon.
+## How do I only display a subset of countries/regions?
+
+Carmen had a concept of excluded countries in the old days, where you could
+specify certain countries or regions to not include in a select.
+
+The new (and much more flexible) way to handle this is to write a helper method
+that returns the subset of regions you want to provide:
+
+``` ruby
+def only_us_and_canada
+  Carmen::Country.all.select{|c| %w{US CA}.include?(c.code)}
+end
+```
+
+And then in your form something like this:
+
+``` erb
+<%= f.select :country, region_options_for_select(only_us_and_canada) %>
+```
+
+More docs coming soon. In the meantime, all of the public methods in
+carmen-rails [have been thoroughly TomDoc'ed](https://github.com/jim/carmen-rails/blob/master/lib/carmen/rails/action_view/form_helper.rb).
 
 ### Demo app
 
 There is a [live demo app](http://carmen-rails-demo.herokuapp.com) that shows
-carmen-rails in action.
+carmen-rails in action, and includes a [step-by-step setup guide](https://github.com/jim/carmen-demo-app#readme).

data/lib/carmen/rails/action_view/form_helper.rb

@@ -2,28 +2,80 @@ module ActionView
   module Helpers
     module FormOptionsHelper
 
-      # Return select and subregion option tags for the given object and method.
+      # Generate select and subregion option tags for the given object and method. A
+      # common use of this would be to allow users to select a state subregion within
+      # a given country.
+      #
+      # object       - The model object to generate the select for
+      # method       - The attribute on the object
+      # parent_region_or_code - An instance of Carmen::Region or a 2-character
+      #                         country code.
+      # options      - Other options pertaining to option tag generation. See
+      #                `region_options_for_select`.
+      # html_options - Options to use when generating the select tag- class,
+      #                id, etc.
       #
       # Uses region_options_or_select to generate the list of option tags.
+      #
+      # Example:
+      #
+      #   subregion_select(@object, :region, {priority: ['US', 'CA']}, class: 'region')
+      #
+      # Returns an `html_safe` string containing the HTML for a select element.
       def subregion_select(object, method, parent_region_or_code, options={}, html_options={})
         parent_region = determine_parent(parent_region_or_code)
         tag = InstanceTag.new(object, method, self, options.delete(:object))
         tag.to_region_select_tag(parent_region, options, html_options)
       end
 
-      # Return select and country option tags for the given object and method.
+      # Generate select and country option tags for the given object and method. A
+      # common use of this would be to allow users to select a state subregion within
+      # a given country.
+      #
+      # object       - The model object to generate the select for
+      # method       - The attribute on the object
+      # options      - Other options pertaining to option tag generation. See
+      #                `region_options_for_select`.
+      # html_options - Options to use when generating the select tag- class,
+      #                id, etc.
       #
       # Uses region_options_or_select to generate the list of option tags.
-      def country_select(object, method, options={}, html_options = {})
-        InstanceTag.new(object, method, self, options.delete(:object)).to_region_select_tag(Carmen::World.instance, options, html_options)
+      #
+      # Example:
+      #
+      #   country_select(@object, :region, {priority: ['US', 'CA']}, class: 'region')
+      #
+      # Returns an `html_safe` string containing the HTML for a select element.
+      def country_select(object, method, options={}, html_options={})
+        tag = InstanceTag.new(object, method, self, options.delete(:object))
+        tag.to_region_select_tag(Carmen::World.instance, options, html_options)
       end
 
-      def region_options_for_select(parent_region, selected = nil, priority_region_codes)
+      # Generate option tags for a collection of regions.
+      #
+      # regions  - An array or Carmen::RegionCollection containing Carmen::Regions
+      # selected - the code of the region that should be selected
+      # options  - The hash of options used to customize the output (default: {}):
+      #
+      # To use priority regions (which are included in a special section at the
+      # top of the list), provide an array of region codes at the :priority
+      # option:
+      #
+      #   region_options_for_select(@region.subregions, 'US', priority: ['US', 'CA'])
+      #
+      # Returns an `html_safe` string containing option tags.
+      def region_options_for_select(regions, selected=nil, options={})
+        options.stringify_keys!
+        priority_region_codes = options['priority'] || []
         region_options = ""
 
         unless priority_region_codes.empty?
+          unless regions.respond_to?(:coded)
+            regions = Carmen::RegionCollection.new(regions)
+          end
+
           priority_regions = priority_region_codes.map do |code|
-            region = parent_region.subregions.coded(code)
+            region = regions.coded(code)
             [region.name, region.code] if region
           end.compact
           unless priority_regions.empty?
@@ -32,28 +84,57 @@ module ActionView
           end
         end
 
-        main_options = parent_region.subregions.map { |r| [r.name, r.code] }
+        main_options = regions.map { |r| [r.name, r.code] }
+        main_options.sort!{|a, b| a.first.unpack('U').to_s <=> b.first.unpack('U').to_s}
         region_options += options_for_select(main_options, selected)
         region_options.html_safe
       end
 
-      # Return select tag with the name provided containing country option
-      # tags.
+      # Generate select and country option tags with the provided name. A
+      # common use of this would be to allow users to select a country name
+      # inside a web form.
+      #
+      # name         - The name attribute for the select element.
+      # options      - Other options pertaining to option tag generation. See
+      #                `region_options_for_select`.
+      # html_options - Options to use when generating the select tag- class,
+      #                id, etc.
       #
       # Uses region_options_or_select to generate the list of option tags.
+      #
+      # Example:
+      #
+      #   country_select_tag('country_code', {priority: ['US', 'CA']}, class: 'region')
+      #
+      # Returns an `html_safe` string containing the HTML for a select element.
       def country_select_tag(name, value, options={})
         subregion_select_tag(name, value, Carmen::World.instance, options)
       end
+
+      # Generate select and subregion option tags for the given object and method. A
+      # common use of this would be to allow users to select a state subregion within
+      # a given country.
       #
-      # Return select tag with the name provided containing subregion option
-      # tags.
+      # name         - The name attribute for the select element.
+      # parent_region_or_code - An instance of Carmen::Region or a 2-character
+      #                         country code.
+      # options      - Other options pertaining to option tag generation. See
+      #                `region_options_for_select`.
+      # html_options - Options to use when generating the select tag- class,
+      #                id, etc.
       #
       # Uses region_options_or_select to generate the list of option tags.
-      def subregion_select_tag(name, value, parent_region_or_code, options = {})
+      #
+      # Example:
+      #
+      #   subregion_select_tag('state_code', 'US', {priority: ['US', 'CA']}, class: 'region')
+      #
+      # Returns an `html_safe` string containing the HTML for a select element.
+      def subregion_select_tag(name, value, parent_region_or_code, options = {}, html_options = {})
         options.stringify_keys!
         parent_region = determine_parent(parent_region_or_code)
         priority_regions = options.delete(:priority) || []
-        opts = region_options_for_select(parent_region, value, priority_regions)
+        opts = region_options_for_select(parent_region.subregions, value, :priority => priority_regions)
         html_options = {"name" => name,
                         "id" => sanitize_to_id(name)}.update(options.stringify_keys)
         content_tag(:select, opts, html_options)
@@ -81,17 +162,27 @@ module ActionView
         add_default_name_and_id(html_options)
         priority_regions = options[:priority] || []
         value = value(object)
-        opts = add_options(region_options_for_select(parent_region, value, priority_regions), options, value)
+        opts = add_options(region_options_for_select(parent_region.subregions, value, :priority => priority_regions), options, value)
         content_tag("select", opts, html_options)
       end
     end
 
     class FormBuilder
+      # Generate select and country option tags with the provided name. A
+      # common use of this would be to allow users to select a country name inside a
+      # web form.
+      #
+      # See `FormOptionsHelper::country_select` for more information.
       def country_select(method, options = {}, html_options = {})
         @template.country_select(@object_name, method,
                                  options.merge(:object => @object), html_options)
       end
 
+      # Generate select and subregion option tags with the provided name. A
+      # common use of this would be to allow users to select a state subregion within
+      # a given country.
+      #
+      # See `FormOptionsHelper::subregion_select` for more information.
       def subregion_select(method, parent_region_or_code, options={}, html_options={})
         @template.subregion_select(@object_name, method, parent_region_or_code,
                                    options.merge(:object => @object), html_options)

data/lib/carmen/rails/version.rb

@@ -1,5 +1,5 @@
 module Carmen
   module Rails
-    VERSION = "1.0.0.beta2"
+    VERSION = "1.0.0.beta3"
   end
 end

data/spec/carmen/action_view/helpers/form_helper_spec.rb

@@ -18,9 +18,9 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
     html = country_select(@object, :country_code)
     expected = <<-HTML
       <select id="object_country_code" name="object[country_code]">
-        <option value="OC">Oceania</option>
-        <option value="EU">Eurasia</option>
         <option value="ES">Eastasia</option>
+        <option value="EU">Eurasia</option>
+        <option value="OC">Oceania</option>
       </select>
     HTML
 
@@ -37,9 +37,9 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
     html = country_select_tag('attribute_name', nil)
     expected = <<-HTML
       <select id="attribute_name" name="attribute_name">
-        <option value="OC">Oceania</option>
-        <option value="EU">Eurasia</option>
         <option value="ES">Eastasia</option>
+        <option value="EU">Eurasia</option>
+        <option value="OC">Oceania</option>
       </select>
     HTML
 
@@ -52,14 +52,14 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
   end
 
   def test_priority_country_select
-    html = country_select(@object, :country_code, {priority: ['ES']})
+    html = country_select(@object, :country_code, {:priority => ['ES']})
     expected = <<-HTML
       <select id="object_country_code" name="object[country_code]">
         <option value="ES">Eastasia</option>
         <option disabled>-------------</option>
-        <option value="OC">Oceania</option>
-        <option value="EU">Eurasia</option>
         <option value="ES">Eastasia</option>
+        <option value="EU">Eurasia</option>
+        <option value="OC">Oceania</option>
       </select>
     HTML
 
@@ -69,7 +69,9 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
   def test_basic_subregion_select
     oceania = Carmen::Country.coded('OC')
     expected = <<-HTML
-      <select id="object_subregion_code" name="object[subregion_code]"><option value="AO">Airstrip One</option></select>
+      <select id="object_subregion_code" name="object[subregion_code]">
+        <option value="AO">Airstrip One</option>
+      </select>
     HTML
 
     html = subregion_select(@object, :subregion_code, oceania)
@@ -79,7 +81,9 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
 
   def test_subregion_select_using_parent_code
     expected = <<-HTML
-      <select id="object_subregion_code" name="object[subregion_code]"><option value="AO">Airstrip One</option></select>
+      <select id="object_subregion_code" name="object[subregion_code]">
+        <option value="AO">Airstrip One</option>
+      </select>
     HTML
 
     html = subregion_select(@object, :subregion_code, 'OC')
@@ -89,7 +93,9 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
 
   def test_subregion_select_using_parent_code_array
     expected = <<-HTML
-      <select id="object_subregion_code" name="object[subregion_code]"><option value="LO">London</option></select>
+      <select id="object_subregion_code" name="object[subregion_code]">
+        <option value="LO">London</option>
+      </select>
     HTML
 
     html = subregion_select(@object, :subregion_code, ['OC', 'AO'])
@@ -109,7 +115,9 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
   def test_basic_subregion_select
     oceania = Carmen::Country.coded('OC')
     expected = <<-HTML
-      <select id="subregion_code" name="subregion_code"><option value="AO">Airstrip One</option></select>
+      <select id="subregion_code" name="subregion_code">
+        <option value="AO">Airstrip One</option>
+      </select>
     HTML
 
     html = subregion_select_tag(:subregion_code, nil, oceania)
@@ -117,6 +125,31 @@ class CarmenViewHelperTest < MiniTest::Unit::TestCase
     assert_equal_markup(expected, html)
   end
 
+  def test_region_options_for_select
+    regions = Carmen::Country.all
+    expected = <<-HTML
+      <option value="ES">Eastasia</option>
+      <option value="EU">Eurasia</option>
+      <option value="OC" selected="selected">Oceania</option>
+    HTML
+    html = region_options_for_select(regions, 'OC')
+
+    assert_equal_markup(expected, html)
+  end
+
+  def test_region_options_for_select_with_array_of_regions_and_priority
+    regions = [Carmen::Country.coded('ES'), Carmen::Country.coded('EU')]
+    expected = <<-HTML
+      <option value="ES">Eastasia</option>
+      <option disabled>-------------</option>
+      <option value="ES">Eastasia</option>
+      <option value="EU">Eurasia</option>
+    HTML
+    html = region_options_for_select(regions, nil, :priority => ['ES'])
+
+    assert_equal_markup(expected, html)
+  end
+
   def method_missing(method, *args)
     fail "method_missing #{method}"
   end

data/spec/spec_helper.rb

@@ -7,13 +7,9 @@ require 'minitest/autorun'
 require 'action_view/test_case'
 
 require 'rails'
-require 'carmen'
 require 'carmen-rails'
 require 'ostruct'
 
-require 'yaml'
-YAML::ENGINE.yamler = 'syck'
-
 MiniTest::Spec.register_spec_type(/.*/, ActionView::TestCase)
 
 Carmen.clear_data_paths

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carmen-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta2
+  version: 1.0.0.beta3
   prerelease: 6
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-09 00:00:00.000000000Z
+date: 2012-05-21 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70301067158160 !ruby/object:Gem::Requirement
+  requirement: &70153544790280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70301067158160
+  version_requirements: *70153544790280
 - !ruby/object:Gem::Dependency
   name: carmen
-  requirement: &70301067142400 !ruby/object:Gem::Requirement
+  requirement: &70153544786740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.0.0.beta2
   type: :runtime
   prerelease: false
-  version_requirements: *70301067142400
+  version_requirements: *70153544786740
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70301067141240 !ruby/object:Gem::Requirement
+  requirement: &70153544785780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70301067141240
+  version_requirements: *70153544785780
 description: Provides country_select and subregion_select form helpers.
 email:
 - jim@autonomousmachine.com