gmaps-autocomplete-rails 0.1.2.1 → 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 90efee2225603ef14f7dba29ae069649a04e3181
+  data.tar.gz: de4e8faefab4ffb298a31825ce0ede6e29a43ce7
+SHA512:
+  metadata.gz: 2b835b6e9dccda0a073bb22b696498a89279eed95e0a8bf85b0e21135ebd33b79f89eee50af3ff77e6100ea5232812237a7ef78c616549c7b8025d7ed695c0d3
+  data.tar.gz: 207a866bef3c9ae88f103e93f81e1d2ccf2de916368d30dc929fafec7190b6931699f367a72f94fdf042db24ca5914f6ec5b7da2e8f232ceda1c371672a43507

data/README.md

@@ -2,33 +2,57 @@
 
 Extracted from [gmaps-autocomplete](https://github.com/rjshade/gmaps-autocomplete) and improved markedly and then packaged for use with Rails as an asset gem :)
 
-See it in action here: [http://rjshade.com/projects/gmaps-autocomplete/](http://rjshade.com/projects/gmaps-autocomplete/)
+## General info
 
-Some more explanation here: [https://github.com/rjshade/gmaps-autocomplete](https://github.com/rjshade/gmaps-autocomplete)
+The script is now compiled from Coffeescript and allows you to have multiple fields linked to multiple instances of the `GmapsCompleter` class on the same page. 
+
+I recommend that you also check out: [google maps and RoR](http://stackoverflow.com/questions/7466872/google-maps-and-ror-3-1)
+
+## Upgrading
+
+Version 1.3+ now comes only with a Class based GmapsCompleter. The old static GmapsCompleter container, used in version 1.2 (and below) has been deprecated. 
+
+Please upgrade your configuration functionality as demonstrated in the usage/config instructions below.
 
 ## Install
 
+## Update gem dependencies
+
+In your project `Gemfile`
+
+```ruby
+gem 'jquery-rails'
+gem 'jquery-ui-rails'
 gem 'gmaps-autocomplete-rails'
+```
 
-You will also need:
-* gem 'jquery-rails'
-* gem 'jquery-ui-rails'
+Or to always use the most recent version, use `gem 'gmaps-autocomplete-rails', github: "kristianmandrup/gmaps-autocomplete-rails"``
 
-And run `bundle install`;)
+Then run `bundle install`;)
 
 Packed and ready for use with the Asset pipeline :)
 
-Add to javascript manifest file, fx `application.js`
+### Update javascript dependencies
+
+Add to javascript manifest file, fx `app/assets/javascripts/application.js`
 
 ```
 //= require jquery_ujs
-//= require jquery.ui.all
-//= require gmaps-autocomplete
+//= require jquery-ui
+//= require gmaps-auto-complete
 ```
 
-And include the google maps script before `application.js`, fx in your layout file:
+Note: Depending on your setup/needs, including jquery-ui is optional (see customization).
+
+### Update style dependencies (optional)
+
+Add to stylesheets manifest file, fx `app/assets/stylesheets/application.css`
+
+```
+*= require jquery-ui
+```
 
-See [google maps and RoR](http://stackoverflow.com/questions/7466872/google-maps-and-ror-3-1)
+Include the google maps script before `application.js`, fx in your layout file:
 
 *application.html.erb*
 
@@ -37,34 +61,77 @@ See [google maps and RoR](http://stackoverflow.com/questions/7466872/google-maps
 <%= javascript_include_tag "application" %>
 ```
 
-Note also that the autocomplete script depends on jQuery 1.6+.
+Note also that the autocomplete script currently depends on jQuery 1.6+. 
+Please feel free to remove this dependency with a pull request :)
+
+## Customization
+
+If you want to customize the gem to use another autocomplete "engine" than the default (assumed to be *jquery-ui*), then fork the gem and change the following
+in the `gmaps-auto-complete.coffee` script to suit your needs and compile to js.
+
+```
+# around line 237
+    autocompleteOpts = $.extend true, defaultAutocompleteOpts, autocompleteOpts
+
+    $(@inputField).autocomplete(autocompleteOpts)
+
+    # triggered when user presses a key in the address box
+    $(@inputField).bind 'keydown', @keyDownHandler
+    # autocomplete_init
+
+  keyDownHandler: (event) =>
+    if (event.keyCode == 13)
+      @geocodeLookup 'address', $(@inputField).val(), true
+      # ensures dropdown disappears when enter is pressed
+      $(@inputField).autocomplete "disable"
+    else
+      # re-enable if previously disabled above
+      $(@inputField).autocomplete "enable"
+```
+
+PS: I'm not sure if this is the only place that requires changes...
 
 ## Initialize
 
-*application.js*
+Add functionality that is executed after the document (and all scripts) have been fully loaded. Example:
+
+*mypage.js*
 
 ```javascript
-$(document).ready(function() { 
-  GmapsAutoComplete.init();
-  GmapsAutoComplete.autoCompleteInit();
+jQuery(function() {
+  var completer;
+
+  completer = new GmapsCompleter({
+    inputField: '#gmaps-input-address',
+    errorField: '#gmaps-error'
+  });
+
+  completer.autoCompleteInit({
+    country: "us"
+  });
 });
 ```
-or coffeescript
 
-*yourmodel.js.coffee*
+or using Coffeescript
+
+*mypage.js.coffee*
 
 ```
-$ ->
-  GmapsAutoComplete.init()
-  GmapsAutoComplete.autoCompleteInit()
+jQuery ->
+    completer = new GmapsCompleter
+        inputField: '#gmaps-input-address'
+        errorField: '#gmaps-error'
+
+    completer.autoCompleteInit
+        country: "us"
 ```
 
 ### Configuration options
 
-`init()` can take an option hash, using the following defaults:
+The constructor function can take a configuration option hash that can configure the specific workings of the `GmapsCompleter`. It uses the following defaults:
 
 ```javascript
-defaultOptions = {
+{
   mapElem: "#gmaps-canvas", 
   zoomLevel: 2, 
   mapType: google.maps.MapTypeId.ROADMAP,
@@ -75,31 +142,50 @@ defaultOptions = {
 };
 ```
 
-### Advanced Configuration
+The following default methods can be replaced by configuration:
 
-`init()` can take an option hash, using the following defaults:
+* positionOutputter
+* updateUI
+* updateMap
 
-```javascript
-defaultOptions = {
-  mapElem: "#gmaps-canvas", 
-  zoomLevel: 2, 
-  mapType: google.maps.MapTypeId.ROADMAP,
-  pos: [51.751724, -1.255284],
-  inputField: '#gmaps-input-address',
-  errorField: '#gmaps-error',
-  debugOn: false
-};
-```
+These methods are used to control how the gmaps data is used to update the UI on the page, such as the position output and map position update. Customize these needed.
 
-The following default methods can be replaced by configuration:
+The default logic (taken from GmapsCompleterDefaultAssist) is:
 
-```javascript
-  positionOutputter: this.defaultPositionOutputter,
-  updateUI : this.defaultUpdateUI,
-  updateMap : this.defaultUpdateMap
+```coffeescript
+  defaultUpdateMap: (geometry) -> 
+    map     = @map
+    marker  = @marker
+
+    map.fitBounds(geometry.viewport) if map
+    marker.setPosition(geometry.location) if marker
+
+  # fill in the UI elements with new position data
+  defaultUpdateUI: (address, latLng) ->
+    $(@inputField).autocomplete 'close'
+
+    @debug 'country', @country
+
+    updateAdr = address.replace ', ' + @country, ''
+    updateAdr = address
+
+    @debug 'updateAdr', updateAdr
+
+    $(@inputField).val updateAdr
+    @positionOutputter latLng
+
+  defaultPositionOutputter: (latLng) ->
+    $('#gmaps-output-latitude').html latLng.lat()
+    $('#gmaps-output-longitude').html latLng.lng()
 ```
 
-`autoCompleteInit` also takes an option hash, but currently only [region](https://developers.google.com/maps/documentation/geocoding/#RegionCodes) and country can be used.
+The default update UI logic removes the country from the address displayed.
+
+## autoCompleteInit
+
+The function `autoCompleteInit`, called on an instance of GmapsCompleter, can takes an option hash. Currently only [region](https://developers.google.com/maps/documentation/geocoding/#RegionCodes), `country`  and `autocomplete` can be used.
+
+Example:
 
 ```javascript
 autoCompleteInit({region: 'DK', country: 'Denmark'});
@@ -107,7 +193,76 @@ autoCompleteInit({region: 'DK', country: 'Denmark'});
 
 Will make searches in the DK region and remove `', Denmark'` from the result.
 
-## Use with Rails form helpers
+Note: Not sure if this is still useful with the new instance based approach!?
+
+Parameter `autocomplete` allows to configure JQuery autocomplete widget
+
+Example:
+```javascript
+autoCompleteInit({
+  region: 'DK', 
+  country: 'Denmark',
+  autocomplete: {
+    minLength: 4,
+    position: {
+      my: "center top",
+      at: "center bottom"
+    }
+  }
+});
+```
+
+## Assist object
+
+The options hash for the constructor can now take an `assist` object as an argument.
+The `assist` object can be a class or a simple object containing the following:
+
+```coffeescript
+  options:
+    mapElem: '#gmaps-canvas'
+    zoomLevel: 2
+    mapType: google.maps.MapTypeId.ROADMAP
+    pos: [0, 0]
+    inputField: '#gmaps-input-address'
+    errorField: '#gmaps-error'
+    debugOn: true  
+  
+  # update marker and map
+  updateMap: (geometry) ->
+
+  # fill in the UI elements with new position data
+  updateUI: (address, latLng) ->
+
+  # display current position
+  positionOutputter: (latLng) ->
+
+  # optionally also message functions (see below)
+```
+
+If you use a class you can use Coffeescript `extends` (see http://coffeescript.org/#classes) to subclass the default implementation. You can then optionally use `super` to call the base implementation.
+
+Example:
+
+```coffeescript
+class MyCompleterAssist extends GmapsCompleterDefaultAssist
+  updateUI: (address, latLng) ->
+    console.log "Doing my own thang!"
+    // ...
+    
+    super (address, latLng)
+```
+
+Usage (config):
+
+```coffeescript
+    completer = new GmapsCompleter
+        inputField: '#gmaps-my-input-address'
+        assist: MyCompleterAssist
+```
+
+## Usage with Rails form helpers
+
+Simple form example:
 
 ```ruby
 = simple_form_for(@post) do |f|
@@ -116,7 +271,9 @@ Will make searches in the DK region and remove `', Denmark'` from the result.
 
 ## Examples
 
-See `spec/index.html` for an example page using this "plugin". Note that if you set `mapElem`to null or leave out that element on the page, the autocomplete will function without attempting to update the map :)
+See `spec/test-gmaps-auto-coffee.html` for an example page using this "plugin". Note that if you set `mapElem` to null or leave out that element on the page, the autocomplete will function without attempting to update the map :)
+
+This is very useful in scenarios where you want to geolocate the address without displaying on the map.
 
 ## Advanced Customization
 
@@ -148,9 +305,11 @@ updateUi: function( address, latLng ) {
 }
 ```
 
+Note that you can encapsulate this kind of customization using the `assist` option and an Assist object/class as demonstrated above.
+
 ## Customizing messages
 
-For now, directly define your own implementation (override) the following functions directly on GmapsAutoComplete
+The following message functions can be customized, either by passing in the options hash, overriding directly on the GmapsCompleter object or even by using the Assist object/class.
 
 * geocodeErrorMsg: function()
 * invalidAddressMsg: function(value)
@@ -160,11 +319,17 @@ Example:
 
 ```javascript
 
-GmapsAutoComplete.geocodeErrorMsg = function() {
+GmapsCompleter.prototype.geocodeErrorMsg = function() {
   "Geocode error!"
 }
 ```
 
+Here, ensuring that ALL instances of `GmapsCompleter` will use this functionality as the baseline (since overriding the prototype function).
+
+### Localizing messages
+
+For localization/internationalization support, you could customize your Assist object constructor to set the current locale and then have your custom `xMsg` functions use this locale to display the localized message.
+
 ## Formtastic example
 
 For [formtastic](https://github.com/justinfrench/formtastic) something like:
@@ -175,21 +340,71 @@ For [formtastic](https://github.com/justinfrench/formtastic) something like:
   %span#address_error
 ```
 
+Or,
+
+```ruby
+<%= semantic_form_for(@search) do |f| %>
+	<%= f.input :pickupAddress, :as => :string, :label => "House/Apt Number and Street", :input_html => { :id => "gmaps-input-address", :style => "width:350px; font-size:14px", :placeholder => "Start typing an address or location" } %>
+	...
+```
+
 And matching configuration in your javascript:
 
 ```javascript
 $(document).ready(function() { 
-  GmapsAutoComplete.init({inputField: 'form#search #address', errorField: 'form#search #address_error'});
-  GmapsAutoComplete.autoCompleteInit({region: 'DK'});
+  var completer;
+  completer = new GmapsCompleter({inputField: 'form#search #address', errorField: 'form#search #address_error'});
+  completer.autoCompleteInit({region: 'DK'});
 });
 ```
 
+### Tips
+
+To avoid loading google maps script on all pages, either use turbolinks or alternatively conditionally load it depending on whether the page needs it. 
+For this you could use a simple `Page` model, something like this:
+
+```ruby
+class Page
+  include ::ActiveModel::Model
+
+  attr_accessor :name, :type, :mode
+
+  def map?
+    mode && mode.to_s =~ /location/
+  end
+```
+
+Then use the Page in the controller
+
+```ruby
+class PropertiesController < BaseController
+  def show
+    @name = params[:id]
+    @mode = params[:mode] || 'gallery'
+    @page = Page.new name: :property, mode: @mode
+  end
+end
+```
+
+Then use page instance to have fine-grained control over how to display the page!
+
+```erb
+<% if @page.map? %>
+  <script type="text/javascript" src="http://maps.googleapis.com/maps/api/js?sensor=false"></script>
+<% end %>
+<%= javascript_include_tag "application" %>
+```
+
+This could fx be integrated into your page layouts (layout files) or similar.
+
+Alternatively perhaps use RequireJS via the `requirejs-rails` gem, and load it "AMD" style, and then use a HTML data attribute to set if the page should load the google map script or not. There are many ways to achieve this...
+
 Enjoy!
 
 ## TODO
 
-* better Javascript encapsulation
-* translation to Coffeescript using Coffee classes :)
+* even better class based functionality encapsulation
+* possibly remove `autoCompleteInit` ??
 
 Please help out with suggestions and improvements etc!
 

data/gmaps-autocomplete-rails.gemspec

@@ -2,14 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+# stub: gmaps-autocomplete-rails 0.1.3 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "gmaps-autocomplete-rails"
-  s.version = "0.1.2.1"
+  s.version = "0.1.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
   s.authors = ["Kristian Mandrup"]
-  s.date = "2013-03-04"
+  s.date = "2014-08-23"
   s.description = "Easily add autocomplete geo-functionality to your Rails app :)"
   s.email = "kmandrup@gmail.com"
   s.extra_rdoc_files = [
@@ -17,48 +19,21 @@ Gem::Specification.new do |s|
     "README.md"
   ]
   s.files = [
-    ".document",
-    ".rspec",
-    "CHANGELOG",
     "Gemfile",
-    "Gemfile.lock",
     "LICENSE.txt",
     "README.md",
-    "Rakefile",
-    "VERSION",
     "gmaps-autocomplete-rails.gemspec",
     "lib/gmaps-autocomplete-rails.rb",
     "lib/gmaps-autocomplete/view_helper.rb",
-    "spec/index.html",
-    "spec/init.js",
-    "spec/jquery-ui/images/ui-bg_flat_0_aaaaaa_40x100.png",
-    "spec/jquery-ui/images/ui-bg_glass_55_fbf9ee_1x400.png",
-    "spec/jquery-ui/images/ui-bg_glass_65_ffffff_1x400.png",
-    "spec/jquery-ui/images/ui-bg_glass_75_dadada_1x400.png",
-    "spec/jquery-ui/images/ui-bg_glass_75_e6e6e6_1x400.png",
-    "spec/jquery-ui/images/ui-bg_glass_75_ffffff_1x400.png",
-    "spec/jquery-ui/images/ui-bg_highlight-soft_75_cccccc_1x100.png",
-    "spec/jquery-ui/images/ui-bg_inset-soft_95_fef1ec_1x100.png",
-    "spec/jquery-ui/images/ui-icons_222222_256x240.png",
-    "spec/jquery-ui/images/ui-icons_2e83ff_256x240.png",
-    "spec/jquery-ui/images/ui-icons_454545_256x240.png",
-    "spec/jquery-ui/images/ui-icons_888888_256x240.png",
-    "spec/jquery-ui/images/ui-icons_cd0a0a_256x240.png",
-    "spec/jquery-ui/images/ui-icons_f6cf3b_256x240.png",
-    "spec/jquery-ui/jquery-ui-1.8.16.custom.css",
-    "spec/jquery-ui/jquery.ui.1.8.16.ie.css",
-    "spec/main.css",
-    "spec/spec_helper.rb",
-    "vendor/assets/javascripts/gmaps-autocomplete.js"
+    "vendor/assets/javascripts/gmaps-auto-complete.js"
   ]
   s.homepage = "http://github.com/kristianmandrup/gmaps-autocomplete-rails"
   s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.25"
+  s.rubygems_version = "2.2.2"
   s.summary = "Google Maps v3 search with jQuery UI Autocomplete, ready for use with Rails asset pipeline"
 
   if s.respond_to? :specification_version then
-    s.specification_version = 3
+    s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rails>, [">= 3.1.0"])