rwanda-rails 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e9802b47854be9086f22ad21c9a8e2447cd0d17
-  data.tar.gz: 2b7210fe13d6de4e4553b016202d445e3f3945a3
+  metadata.gz: 4481d16542867faa48ecaa8cd9c7e2854275a1da
+  data.tar.gz: c5df052d9bb71ab982f0dbe08c3065f6724aad5b
 SHA512:
-  metadata.gz: 96df5a8f2099813eb27c730fdd5e712f0e03cd28ccd79aa671b8bd9a2dfb80d763557a29d3c25ea519ef766bfa34a67e2cfa2b14d90497b9a1c7c69d97bdb22d
-  data.tar.gz: 55b2403e91718c8c3848651733bf0f3d9894b27e0976a5f2de40d7e310a6b491f7690b8f5649f37aeda70cfc34271a3e0a737f9dbc91d36500e71f48999fff20
+  metadata.gz: 144bb81bbe6771830dcbdf40cecaa7c099ea9203874afac9764067cb9a7910044b0e6814f0a836755e4e793aa6f99e9dd30592db914d35b6856383e63ca516fb
+  data.tar.gz: 9b03149169736299be636f3b094d465cfdf07237472fc686cb00e3ae639fa2c53b5022c6b086038061caf2f34a253b5f0cdc4cd0bfd68ad2a13cbbdfbf6f6a73

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.3
+
+ * Significant corrections and added detail to README
+ * Reference example application at Github
+ 
+## 0.1.2
+
+ * Remmove inadvertent references to tracker models (first testing with an empty application)
+
 ## 0.1.1
 
  * Allow rwanda version to increment

data/README.md

@@ -1,6 +1,6 @@
 # Rwanda::Rails
 
-Access information about geographic divisions in Rwanda from within the Rails framework.
+Add information about geographic location within Rwanda to models in the Rails framework, and update them through a web interface.
 
 ## Installation
 
@@ -12,7 +12,7 @@ gem 'rwanda-rails'
 
 And then execute:
 
-    $ bundle
+    $ bundle install
 
 Or install it yourself as:
 
@@ -20,10 +20,11 @@ Or install it yourself as:
 
 ## Usage
 
-In the view:
+In the view (e.g. in `_form.html.erb` if you generated your model using `rails generate scaffold`):
 
 ```erb
 <%= form_for(@person) %>
+  <% loc = Location.new(@company.district, @company.sector, @company.cell, @company.village) %>
   <%# "force_edit: @force_edit" is necessary in order to be able to edit previously filled-in fields %>
   <%= f.rwanda_location(loc, { force_edit: @force_edit, autosubmit: true }) %>
 <%= f.submit 'Update Location' %>
@@ -33,17 +34,41 @@ In the controller:
 
 ```ruby
 # Can be in its own action instead of edit if you prefer
+# However, you would then have to pass the action in to rwanda_location in the options hash
 def edit
   @force_edit = params[:force_edit]
 end
+
+def update
+  respond_to do |format|
+    if @person.update(person_params)
+      # by rendering edit instead of show, it is possible to quickly enter all levels
+      # one after the other
+      format.html { render :edit, notice: 'Person was successfully updated.' }
+      format.json { render :edit, status: :ok, location: @person }
+    else
+      format.html { render :edit }
+      format.json { render json: @person.errors, status: :unprocessable_entity }
+    end
+  end
+end
 ```
 
 The model to which you're adding a Rwandan location needs attributes `district`, `sector`, `cell` and `village`.
 
 ```
 rails generate migration add_location_to_person district:string sector:string cell:string village:string
+rake db:migrate
 ```
 
+## Edit location in `edit` view, or create a separate view and action?
+
+Entering a full Rwandan location (district, sector, cell and village) requires a page load at each step (CSV data covering all of Rwanda is around 0.75 MB -- a significant download, so instead only that which is needed is provided by the server).  To make this less clunky, `autosubmit: true` can be passed to speed up the process by submitting the form as soon as a district, sector, etc is chosen, reducing the number of clicks.  However, this requires that submission of the `_form` return the user to the `edit` view rather than, as is more traditional, a `show` view.  For these reasons, it might be preferable to use an "Edit Location" link in your edit view to go to a separate edit_location action and view.  Then the original `edit` action can behave as expected, i.e. when submitted it will update the record and forward the user to a `show`.  However, either way works.
+
+## Example application
+
+Take a look at a [minimal Rails application that uses this gem](https://github.com/repent/example-rwanda-rails).
+
 ## Status
 
 [![Gem Version](https://badge.fury.io/rb/rwanda-rails.svg)](http://badge.fury.io/rb/rwanda-rails)

data/lib/rwanda/rails.rb

@@ -10,82 +10,63 @@ class Rwanda
         ActionView::Helpers::FormBuilder.send(:include, FormBuilder)
       end
       
-      def rwanda_location(object_name, location, options={})
-        cleaned_options = { include_blank: 'Unknown' }
-        cleaned_options[:onchange] = "this.form.submit();" if options[:autosubmit]
-        cleaned_options.merge!(options.select {|k,v| [ :force_edit, :table ].include? k })
+      # available options:
+      #  required:
+      #   :force_edit - name of level that has specifically been requested to be changed by the user
+      #  optional:
+      #   :autosubmit - submit the form immediately rather than waiting for the button to be pressed
+      #   :include_blank - string to display if nothing selected, defaults to 'Unknown'
+      #   :table - output in a <table> if true
+      #   #:edit_path - defaults to edit_model_path
+      #   :action - defaults to edit
+      
+      def rwanda_location(object_name, location, raw_options={})
+        # transfer everything from raw_options into config for random access
+        config = { table: true, action: 'edit' }.merge(raw_options)
+        
+        # pick out only those raw_options that will be passed to select_tag
+        select_options = { include_blank: 'Unknown' }.merge(raw_options.select {|k,v| [ :force_edit, :include_blank ].include? k })
+        select_options[:onchange] = "this.form.submit();" if raw_options[:autosubmit]
+        
         # object_name = company
         # location = Struct.new( :division ... )
-        output = cleaned_options[:table] ? "<table border=0>\n".html_safe : ''.html_safe
+        output = config[:table] ? "<table border=0>\n".html_safe : ''.html_safe
         # location is a Location object defined in the rails gem
         location.validate! # get rid of any erroneous data -- no more checks necessary
-        force_edit = options[:force_edit]
+        force_edit = config[:force_edit] ? config[:force_edit].to_sym : nil
+        #binding.pry
+        #cleaned_options[:edit_path] = options[:edit_path] || edit_polymorphic_path(object_name, force_edit: force_edit)
         location.each_pair do |level, div|
-          output << "<tr><td>\n".html_safe if cleaned_options[:table]
+          output << "<tr><td>\n".html_safe if config[:table]
           output << "<div class=\"field\">\n".html_safe
+          #binding.pry
           if force_edit == level || ( location.first_missing == level && !force_edit )
             # editable
             # Want subdivisions of [district] if level is sector
             subdivisions = Rwanda.instance.subdivisions_of(location.top(Location.index_of(level)-1))
             
-            subdivision_options = { selected: div }.merge(cleaned_options)
+            subdivision_options = { selected: div }.merge(select_options)
             output <<
-              select_tag("#{object_name}[#{level}]", options_for_select(subdivisions, div), cleaned_options) <<
-              " #{level.humanize}".html_safe
-            output << "</td><td></td>\n".html_safe if cleaned_options[:table]
+              select_tag("#{object_name}[#{level}]", options_for_select(subdivisions, div), select_options) <<
+              " #{level.to_s.humanize}".html_safe
+            output << "</td><td></td>\n".html_safe if config[:table]
           elsif div
             # display
             output <<
-              "<b>#{div}</b> #{level.humanize}\n&nbsp;#{'</td><td>' if cleaned_options[:table]}".html_safe <<
-              link_to("[Change this]", edit_company_location_path(force_edit: level))
+              "<b>#{div}</b> #{level.to_s.humanize}\n&nbsp;#{'</td><td>' if config[:table]}".html_safe <<
+              link_to("[Change this]", polymorphic_path(object_name, action: config[:action], force_edit: level))
           else
             # greyed out message
-            output << "Enter data above before selecting #{level.humanize}\n"
-            output << "</td><td></td>\n".html_safe if cleaned_options[:table]
+            output << "Enter data above before selecting #{level.to_s.humanize}\n"
+            output << "</td><td></td>\n".html_safe if config[:table]
           end
           output << "</div>\n".html_safe
-          output << "</td></tr>\n".html_safe if cleaned_options[:table]
+          output << "</td></tr>\n".html_safe if config[:table]
         end
-        output << "</table>\n".html_safe if cleaned_options[:table]
+        output << "</table>\n".html_safe if config[:table]
         #location.to_s
         output
       end
-      
-      #private
-      #def division(division, company, force_edit=false)
-      #  #logger.debug "force_edit: #{force_edit} (#{force_edit.class.to_s}); division: #{division} (#{division.class.to_s})"
-      #  force_edit &&= force_edit.to_symbol
-      #  # all higher divisions validate
-      #  if validate_higher(division, company)
-      #    # this division validates
-      #    if validate_this(division, company)
-      #      # user has asked to edit this division
-      #      if force_edit == division
-      #        #> drop-down
-      #        return true
-      #      # user hasn't asked to edit
-      #      else
-      #        #> display as text with link to edit
-      #        return false
-      #      end
-      #    # this division doesn't validate
-      #    else
-      #      # another division has been forced
-      #      if force_edit && force_edit != division
-      #        #> greyed out
-      #        return false
-      #      else
-      #        #> drop-down
-      #        return true
-      #      end
-      #    end
-      #  # at least one higher division doesn't validate
-      #  else
-      #    # greyed out message
-      #    return false
-      #  end
-      #end      
-      #end
     end
     
     module FormBuilder

data/lib/rwanda/rails/version.rb

@@ -1,5 +1,5 @@
 class Rwanda
   module Rails
-    VERSION = "0.1.2"
+    VERSION = "0.1.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rwanda-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Dan Hetherington