Model Customization

Declaration in model

Basic

The easiest way to declare gmaps4rails in your model is:

acts_as_gmappable

The following default config will be assumed:

• :process_geocoding => true : the geocode will be performed each time the model is run through a validate method

• :validation => true : if the position of the address provided isn't found by google, an error will be displayed

• :lat => "latitude", :lng => "longitude" : latitude and longitude will be saved in the columns latitude and longitude

• :check_process => true, :checker => "gmaps" : the status of the geocode, will be checked in a method or in db column boolean called gmaps. Note: If :check_process is set to false then lat & long will be updated when the model is updated.

If you have a boolean field gmaps (assuming you use the defaults above), and set it false before saving your model, your address will be geocoded and the boolean will be reset to true. In other words, set it false before updating your model if the address as dirty (needs to be geocoded), and it will automatically be reset to true after the geocoding is complete.

• :address =>"gmaps4rails_address": will look for the default gmaps4rails_address

Custom

All or part of these default behaviors can be customized with the following arguments:

• :lat : string

• :lng : string

• :process_geocoding : true/false/Proc/String/symbol

These are only used if process_geocoding returns true:

• :check_process : Either a Boolean (most obvious case), Symbol (in this case, it should refer to an instance method's name), or Proc. This is not taken into account when process_geocoding is a Proc or a method name.

• :checker : string (only if check_process is true), could be a method or a db column boolean. This is not taken into account when process_geocoding is a Proc or a method name.

• :validation : Either a Boolean (most obvious case), Symbol (in this case, it should refer to an instance method's name), or Proc.

• :msg : string, to customize the error message in validation (if activated)

• :address : string it could be a method or even a db column name.

• normalized_address : string, you can retrieve directly the address matched by google. Set here in which db column you want it to be saved.

• language : string, the language in which the results will be returned (Useful in combination with normalized_adress).

• protocol : string, "http" by default

• callback : string, if set, this will be called with the most specific result as a parameter. You can then do whatever you want with it. For example:

acts_as_gmappable :callback => :save_country
def save_country(data)
  data["address_components"].each do |c|
    if c["types"].include? "country"
      self.country = c["long_name"]
    end
  end
end

Example

You could do the following:

acts_as_gmappable :process_geocoding => false

Another example related to the gmaps boolean

Suppose foo is an instance of your model which has has fields gmaps and address and longitude and latitude and the model definition includes:

acts_as_gmappable

def gmaps4rails_address
  self.address
end

foo.update_attribute :gmaps, true # the 'do nothing' state for gmaps

this changes the address, but does NOT geocode it (eg, does not change the latitude and longitude values) foo.update_attribute :address, "100 wall street, new york, ny 10005"

this changes the address AND geocodes the new address (sets longitude & latitude): foo.update_attributes :address => "90 Water St, New York, NY 10005", :gmaps => false

foo.gmaps is true (it gets reset after the geocoding is done)