GeoTools
========

You have lots of plugin choices if you want to geocode North American addresses, or find all the locations near somewhere.  But few help you with forms and validation.

This plugin does three things:

* Adds +latitude_field+ and +longitude_field+ form helpers to Rails' default form builder.
* Lets your model acts_as_location, to work seamlessly with the form helpers.
* Validates the location data entered on the form and in the database.


Assumptions
===========

* Any model that acts_as_location has latitude and longitude floats defined like this:

  # In your model's migration's self.up method:
  create_table :thingies do |t|
    # Your model's various fields.
    t.string :name
    t.timestamps
    ...

    # Stuff GeoTools needs:
    t.with_options :precision => 15, :scale => 10 do |c|
      c.decimal :latitude
      c.decimal :longitude
    end
  end

* A latitude should be entered on a form like this:

  xx <degree symbol> yy <decimal point> zzz h

  where:

  xx is degrees (0 <= integer <= 90; maximum length of 2 digits)
  yy is minutes (0 <= integer <= 59; maximum length of 2 digits; optional; defaults to 0)
  zzz is milli-minutes (0 <= integer <= 999; maximum length of 3 digits; optional; defaults to 0)
  h is hemisphere ('N' or 'S')

* Similarly, a longitude should be entered on a form like this:

  xxx <degree symbol> yy <decimal point> zzz h

  where:

  xxx is degrees (0 <= integer <= 180; maximum length of 3 digits)
  yy is minutes (0 <= integer <= 59; maximum length of 2 digits; optional; defaults to 0)
  zzz is milli-minutes (0 <= integer <= 999; maximum length of 3 digits; optional; defaults to 0)
  h is hemisphere ('E' or 'W')


Example
=======

# Model
class Treasure < ActiveRecord::Base
  acts_as_location
end

# View
<% form_for @treasure do |f| %>
  <%= f.text_field :spot_marked_by %>
  <%= f.latitude_field :latitude %>
  <%= f.longitude_field :longitude %>
<% end %>

# Controller
# ...same as usual...

You'll get validation on every field (degrees, minutes, milli-minutes, hemisphere) generated by the form helpers, as well as the overall value.  The latter is useful if somebody updates the latitude or longitude directly, as a float, bypassing the form helpers.

Here's an example script/console session:

>> puts Treasure.find(:first).location
12°20.736′N, 012°20.736′W   # N.B. If this looks weird online, set your browser's text encoding to UTF-8.

>> puts Treasure.find(:first).location.latitude
12.3456

>> puts Treasure.find(:first).location.longitude
-12.3456


To Do
=====
Tests/specs :-)
Investigate implementing with ActiveRecord's multiparameter assignment.


Feedback
========
Yes please!  --> boss@airbladesoftware.com


Copyright (c) 2008 Andy Stewart, AirBlade Software Ltd.  Released under the MIT license