leaflet_helper 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6f0a6f20aeb1a990f29061044ced274fae566267
-  data.tar.gz: 538a63485b9c432f7d8d0374f3bd7250e25d199d
+  metadata.gz: 8c6c2bfb061ed25ac3ffdf96fef9e873cac10ff3
+  data.tar.gz: d23001011f855ba51e1b97ae012ea53e2cc57c25
 SHA512:
-  metadata.gz: 400b40208c8f2219f6b921a93c4b9183bd6b8d5728c4b61f1dfee65efc50300677e5e02ae1657e42a97799d08c6ecc9a387921008fa8a35349ced75d3dffb4d9
-  data.tar.gz: 4ae029f4525beed6e476fe921131be854d6dfd8c72f3904d0faddf5ac2a6f47ce715124fad53ed5b1b56ddd9e6b342bf91a299b477bf0be11a5354226cbf427b
+  metadata.gz: eb415d972d817fb45f1238c9364dc573b6673516b81982719bb01e6815645b2221c11dc8eb4240b966be9dc9b7e943a744b490b058db3d30ac062245488c28dd
+  data.tar.gz: d90dcb14eb057a44ebe7b6c6ccf276f4f13d48cf44e881e694c0c4c52c94563b8e0f42fbc102de094a0406f092969b2e0f70c5532bb7e51f89626a5714bf9476

data/README.md

@@ -7,7 +7,7 @@ Look at my experiments/maps repo to see how leafelet_helpers is used with a sina
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application's `Gemfile`:
 
 ```ruby
 gem 'leaflet_helper'
@@ -23,12 +23,260 @@ Or install it yourself as:
 
 ## Usage
 
-Look at https://github.com/MadBomber/experiments/tree/master/maps
+Look at [https://github.com/MadBomber/experiments/tree/master/maps]
 
 The views/layout.haml and views/index.haml show how to use the leaflet_helper.  Of course you
 have to require the gem in the main app.rb file in order for it to be available in the views.  This
 sinatra app also shows how to use markers on top of the main map layers.
 
+Just about all of the methods in this library emit javascript source code.
+
+### LeafletHelper::L.init(options={})
+
+The 'init' method is used to insert the leaflet.js script and leaflet.css stylesheet.
+It is used in the 'head' part of a webpage.  For example if you are use Sinatra and haml then
+the 'layout.haml' file might look like this:
+
+
+```ruby
+  %html
+    %head
+      = LeafletHelper::L.init
+```
+
+#### options
+
+The 'options' is a hash.  It is unused.
+
+
+### LeafletHelper::L.place_map_here(id='map', options={})
+
+The 'place_map_here' method is used to insert the HTML "<div>" tag into the
+body of a webpage.  This is the HTML container which will host the map image
+managed by the LeafletJS library.  If is possible to have several map images
+displayed on the same webpage; HOWEVER, each map image MUST have a different
+id ... because they MUST be unique ... because they MUST BE DIFFERENT thats why.
+
+#### id
+
+Yep, its a string that uniquely identifies the HTML `<div>` component
+that holds the generated map graphic managed by the LeafletJS javascript
+library.
+
+#### options
+
+Defaults:
+
+```ruby
+o = {
+  style: "width: 800px; height: 400px"
+}.merge(options)
+```
+
+Of course you could just use some CSS to add anything you want.  But if you
+are an inline kinda programmer then the options are for you.
+
+### LeafletHelper::L.show_map(id="map", options={})
+
+This method is used at the end of the body component of the HTML webpage.  Why? you
+ask.  Because thats how we did it in the old days to make sure that the entire webpage
+was loaded before doing stuff on it.  You hotshot javascripters know how its done
+the "right" way.  I'm sure you have a pull-request already to go to help out us
+old back-end geezers.
+
+This method generates javascript source code that also includes the same javascript that
+is generated by the LeafletHelper::L.set_view method.  That may change.
+
+#### id
+
+Yep, its a string that uniquely identifies the HTML `<div>` component
+that holds the generated map graphic managed by the LeafletJS javascript
+library.
+
+#### options
+
+Defaults:
+
+```ruby
+o = {
+    latitude:   AREA51.latitude,
+    longitude:  AREA51.longitude,
+    zoom:       9,
+    min_zoom:   2,
+    max_zoom:   22
+  }.merge(options)
+```
+
+These options are primarily for the 'setView' LeafletJS method.  That method
+establishes the location (latitude, longitude) at which the map is cenered.  It
+also establishs the current 'zoom' value and the minimum and maximum values for
+which the zoom value can take.
+
+
+### LeafletHelper::L.set_view(id='map', options={})
+
+The javascript source code that this method generates moves an existing map
+image to be centered at a specific latitude and longitude with a given zoom level.
+
+#### id
+
+Yep, its a string that uniquely identifies the HTML `<div>` component
+that holds the generated map graphic managed by the LeafletJS javascript
+library.
+
+#### options
+
+Defaults:
+
+```ruby
+o = {
+    latitude:   AREA51.latitude,
+    longitude:  AREA51.longitude,
+    zoom:       9
+  }.merge(options)
+```
+
+### LeafletHelper::L.add_openstreetmap_layer(id="map", options={})
+
+The LeafletJS library by itself has no dataset - no roads, streets features etc.  In
+order to see that kind of stuff a "tile" layer - a zoomable set of images - needs to be
+added.  The most common and easiest to use free open source creative commons licensed
+dataset is from the Open Street Map project.
+
+This method adds the Open Street Map dataset tiles as a layer on the LeafletJS-managed
+map image.
+
+Other tile datasets are available such as those from the mapbox.com project.  (See bolow)
+
+#### id
+
+Yep, its a string that uniquely identifies the HTML `<div>` component
+that holds the generated map graphic managed by the LeafletJS javascript
+library.
+
+#### options
+
+Defaults:
+
+```ruby
+o = {
+    latitude:   AREA51.latitude,
+    longitude:  AREA51.longitude,
+    zoom:       9,
+    min_zoom:   2,
+    max_zoom:   22 
+  }.merge(options)
+```
+
+
+### LeafletHelper::L.add_mapbox_layer(id="map", options={})
+
+As mentioned above in the discussion about Open Street Map, LeafletJS does not come
+with image tiles.  These must be provided from somewhere else.  The Open Street Map has a
+good set of vector-oriented images of streets and areas.  It has no actual images
+such as provided by satilites.  These kinds of images can be obtained via the
+Mapbox.com project.
+
+In order to use Mapbox images you must have an account on mapbox.com.  There is a nice
+developer friendly zero dollar plan.  Other plans for commerical use are reasoniblity priced.
+
+With an account on mapbox.com you have access to their image tiles for use with the LeafletJS
+library.
+
+The following system environment variables can be used with this capability:
+
+```
+MAPBOX_URL
+MAPBOX_USER
+MAPBOX_STYLE_ID
+MAPBOX_ACCESS_TOKEN
+```
+
+You can either provide the full URL for you mapbox project's images or you can
+provide just the pieces that make up the URL - the user, style_id and access_token.
+
+#### id
+
+Yep, its a string that uniquely identifies the HTML `<div>` component
+that holds the generated map graphic managed by the LeafletJS javascript
+library.
+
+#### options
+
+Defaults:
+
+```ruby
+o = {            
+    url:          ENV['MAPBOX_URL']           || "https://api.mapbox.com/styles/v1/{mbUser}/{id}/tiles/{z}/{x}/{y}?access_token={accessToken}",
+    mapbox_user:  ENV['MAPBOX_USER']          || "your.mapbox.user.account",
+    style_id:     ENV['MAPBOX_STYLE_ID']      || "your.mapbox.project.id",
+    access_token: ENV['MAPBOX_ACCESS_TOKEN']  || "your.mapbox.access.token",
+    attribution:  'Map data &copy; <a href="http://openstreetmap.org">OpenStreetMap</a> contributors, <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>, Imagery © <a href="http://mapbox.com">Mapbox</a>',
+    zoom:          9,
+    min_zoom:      2,
+    max_zoom:      22 
+  }.merge(options)
+```
+
+
+### LeafletHelper::L.add_support_for_markers(id="map", options={})
+
+While being able to show a map image on a webpage, zoom it and move it around (called panning),
+it is much more fun if you can put actionable markers on top of the map.  That is what this
+method does.  It injects the javascript code that makes the callback to get the "markers"
+for display upon the map.  The callback is generated everytime the map image changes either by
+zoom or by pan.
+
+The markers are provided as a JSON object.  The object is an array of hashes.  Each hash defines one marker.
+
+
+
+#### id
+
+Yep, its a string that uniquely identifies the HTML `<div>` component
+that holds the generated map graphic managed by the LeafletJS javascript
+library.
+
+The only option that is necessary is the 'route' - the place to do an HTTP GET
+to receive a JSON string of markers.
+
+#### options
+
+Defaults:
+
+```ruby
+o = {
+    route:     "#{id}/markers"
+  }.merge(options)
+```
+
+Note that the 'route' default is setup to easily match a Sinatra block like:
+
+```ruby
+get '/:map_id/markers' do |map_id|
+  content-type :json
+  $array_of_marker_hashes[map_id].to_json
+end
+```
+
+For now a marker hash looks like this:
+
+```ruby
+{
+  "name":     "Area 51",
+  "lon":      AREA51.longitude,
+  "lat":      AREA51.latitude,
+  "details":  "A good place to buy used flying saucers."
+}
+```
+
+The marker when clicked shows a popup window on the map image.  The "name" component is at
+the top of the popup in an `<h3>` wrapper.  The "lat" and "lon" elements allow LeafletJS to
+place the marker at the correct location on the map image.
+
+The "details" component can be any combination of HTML that you want.  In one applicaton I have
+that makes use of the LeafletHelper library I show thumbnails of images as part of the popup.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -39,7 +287,7 @@ Of course if that doesn't work try something else.  I'm not any good a javascrip
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/leaflet_helper.
+Bug reports and pull requests are welcome on GitHub at https://github.com/MadBomber/leaflet_helper.
 
 
 ## License

data/leaflet_helper.gemspec

@@ -5,7 +5,7 @@ require 'leaflet_helper/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "leaflet_helper"
-  spec.version       = '0.0.4'
+  spec.version       = '0.0.5'
   spec.authors       = ["Dewayne VanHoozer"]
   spec.email         = ["dvanhoozer@gmail.com"]
 

data/lib/leaflet_helper.rb

@@ -1,12 +1,35 @@
 # leaflet_helper.rb
+#
+# If you are a front-end developer and a Javascript guru this will 
+# make you laught.  If you are a back-end big-data AI do-er of amazing
+# things then this library might be of some use to you.  I allows you 
+# to but maps onto a web-page using simple frameworks.  No more NodeJS
+# or Rails.  Use some simple sinatra-based haml pages and voila you got maps.
+#
+# Makes use of these system environment variables when using
+# using the method add_mapbox_layer:
+#
+#   MAPBOX_URL
+#   MAPBOX_USER
+#   MAPBOX_STYLE_ID
+#   MAPBOX_ACCESS_TOKEN
+
+# TODO: refactor
+
+# Just as good a default as any other ...
+AREA51 = Struct.new('Location', :latitude, :longitude).new
+AREA51.latitude   = 37.235
+AREA51.longitude  = -115.811111
 
 module LeafletHelper
   class L
-    VERSION         = '0.7.3'       # of leaflet.js
+    VERSION   = '0.7.7'       # of leaflet.js
+    JS        = "http://cdn.leafletjs.com/leaflet/v#{VERSION}/leaflet.js"
+    CSS       = "http://cdn.leafletjs.com/leaflet/v#{VERSION}/leaflet.css"
 
     # TODO: Why are these desired?
-    @@map_ids       = []            # the div ids of all of the maps
-    @@markers       = Hash.new([])  # An array of markers for each map id
+    @@map_ids   = []            # the div ids of all of the maps
+    @@markers   = Hash.new([])  # An array of markers for each map id
 
     class << self
 
@@ -17,29 +40,9 @@ module LeafletHelper
             }.merge(options)
 
         leaflet_script = <<~EOS
-          <script type="text/javascript" src="//cdn.leafletjs.com/leaflet-#{VERSION}/leaflet.js"></script>
-          <link rel="stylesheet" href="//cdn.leafletjs.com/leaflet-#{VERSION}/leaflet.css">
-        
-          // SMELL: I'm not sure this script section is needed.
-          <script>
-
-            // set up AJAX request
-            ajaxRequest = getXmlHttpObject();
-
-            if (ajaxRequest == null) {
-              alert ("This browser does not support HTTP Request");
-              // return;
-            }
-
-            // SMELL: this function is not map specific
-            function getXmlHttpObject() {
-              if (window.XMLHttpRequest) { return new XMLHttpRequest(); }
-              if (window.ActiveXObject)  { return new ActiveXObject("Microsoft.XMLHTTP"); }
-              return null;
-            }
-
-          </script>
-
+          <!-- Leaflet -->
+          <script src="#{JS}"></script>
+          <link rel="stylesheet" href="#{CSS}">
         EOS
 
         return leaflet_script
@@ -50,15 +53,18 @@ module LeafletHelper
       # can support multiple maps on a page; each
       # map must have a unique id
       def place_map_here(id='map', options={})
-        # SMELL: This may happen every time the page is refreshed
-        @@map_ids << id
+        @@map_ids << id unless @@map_ids.include?(id)
+
         o = {
           style: "width: 800px; height: 400px"
         }.merge(options)
+
         div_options = ""
+
         o.each_pair do |k,v|
           div_options += " #{k.to_s}=" + '"' + v + '"'
         end
+
         return <<~EOS
           <div id="#{id}"#{div_options}></div>
         EOS
@@ -68,8 +74,8 @@ module LeafletHelper
       # Intended for the body at the bottom
       def show_map(id="map", options={})
         o = {
-            latitude:   37.235,
-            longitude:  -115.811111,
+            latitude:   AREA51.latitude,
+            longitude:  AREA51.longitude,
             zoom:       9,
             min_zoom:   2,
             max_zoom:   22
@@ -81,13 +87,17 @@ module LeafletHelper
           <script>
 
             var #{var_name};
-            var ajaxRequest; // SMELL: not map specific
+
+            // SMELL: These 3 vars are only used with markers so why are they here?
+            var ajaxRequestFor#{id}; 
             var plotlistFor#{id};
             var plotlayersFor#{id} = [];
 
             // set up the map
             #{var_name} = new L.Map('#{id}');
 
+            // SMELL: Maybe the app is not ready to set the view.  There is
+            //        a ruby method #set_view that does this.
             // start the map at a given location and zoom level
             #{var_name}.setView(new L.LatLng(#{o[:latitude]}, #{o[:longitude]}), #{o[:zoom]});
           
@@ -98,11 +108,35 @@ module LeafletHelper
       end # def show_map(id="map", options={})
 
 
+      # Center an existing map to a specific location
+      def set_view(id='map', options={})
+        o = {
+            latitude:   AREA51.latitude,
+            longitude:  AREA51.longitude,
+            zoom:       9
+          }.merge(options)
+
+        var_name = get_var_name(id)
+
+        leaflet_script = <<~EOS
+          <script>
+            // center the map to a given location and zoom level
+            #{var_name}.setView(new L.LatLng(#{o[:latitude]}, #{o[:longitude]}), #{o[:zoom]});
+          </script>
+        EOS
+
+        return leaflet_script
+
+      end # def set_view(id='map', options={})
+
+
       # Intended for the body at the bottom
+      # SMELL: why the bottom?  Because that's they way we did it in the old days
+      #        so that the entire web page would have been loaded by then.
       def add_openstreetmap_layer(id="map", options={})
         o = {
-            latitude:   37.235,
-            longitude:  -115.811111,
+            latitude:   AREA51.latitude,
+            longitude:  AREA51.longitude,
             zoom:       9,
             min_zoom:   2,
             max_zoom:   22 
@@ -118,7 +152,7 @@ module LeafletHelper
             var osmAttrib ='Map data © <a href="http://openstreetmap.org">OpenStreetMap</a> contributors';
             var osm       = new L.TileLayer(osmUrl, {minZoom: #{o[:min_zoom]}, maxZoom: #{o[:max_zoom]}, attribution: osmAttrib});   
             
-            #{var_name}.addLayer(osm);
+            osm.addTo(#{var_name});
 
           </script>
         EOS
@@ -127,6 +161,42 @@ module LeafletHelper
       end # def add_openstreetmap_layer(id="map", options={})
 
 
+      # Intended for the body at the bottom
+      # To use mapbox you must have an account
+      def add_mapbox_layer(id="map", options={})
+        o = {            
+            url:          ENV['MAPBOX_URL']           || "https://api.mapbox.com/styles/v1/{mbUser}/{id}/tiles/{z}/{x}/{y}?access_token={accessToken}",
+            mapbox_user:  ENV['MAPBOX_USER']          || "your.mapbox.user.account",
+            style_id:     ENV['MAPBOX_STYLE_ID']      || "your.mapbox.project.id",
+            access_token: ENV['MAPBOX_ACCESS_TOKEN']  || "your.mapbox.access.token",
+            attribution:  'Map data &copy; <a href="http://openstreetmap.org">OpenStreetMap</a> contributors, <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>, Imagery © <a href="http://mapbox.com">Mapbox</a>',
+            zoom:          9,
+            min_zoom:      2,
+            max_zoom:      22 
+          }.merge(options)
+
+        var_name = get_var_name(id)
+
+        leaflet_script = <<~EOS
+          <script>
+
+            // create the tile layer with correct attribution
+            L.tileLayer('#{o[:url]}', {
+                mbUser:       '#{o[:mapbox_user]}',
+                attribution:  '#{o[:attribution]}',
+                minZoom:      #{o[:min_zoom]},
+                maxZoom:      #{o[:max_zoom]},
+                id:           '#{o[:style_id]}',
+                accessToken:  '#{o[:access_token]}'
+            }).addTo(#{var_name});
+
+          </script>
+        EOS
+
+        return leaflet_script
+      end # def add_mapbox_layer(id="map", options={})
+
+
       # Allows for the generation of markers on top of the map
       def add_support_for_markers(id="map", options={})
         o = {
@@ -138,14 +208,29 @@ module LeafletHelper
         leaflet_script = <<~EOS
           <script>
 
-            getMarkersFor#{id}(); // askForPlots();
+            // set up AJAX request
+            ajaxRequestFor#{id} = getXmlHttpObjectFor#{id}();
+
+            if (ajaxRequestFor#{id} == null) {
+              alert ("This browser does not support HTTP Request - can not show markers");
+              // return;
+            }
+
+            function getXmlHttpObjectFor#{id}() {
+              if (window.XMLHttpRequest) { return new XMLHttpRequest(); }
+              if (window.ActiveXObject)  { return new ActiveXObject("Microsoft.XMLHTTP"); }
+              return null;
+            }
+
+
+            getMarkersFor#{id}();
             #{var_name}.on('moveend', on#{id}Move);
 
             function on#{id}Move(e) { getMarkersFor#{id}(); }
 
 
             // request the marker info for the current bounds
-            function getMarkersFor#{id}() { // was: askForPlots
+            function getMarkersFor#{id}() {
 
               // TODO: Currently the displayed map bounds is not being used
               //       to get the new set of markers.  This could be ugly for
@@ -157,9 +242,9 @@ module LeafletHelper
               // this is the place from which the markers JSON array is obtained
               var route = '#{o[:route]}';
 
-              ajaxRequest.onreadystatechange =  stateChangedFor#{id};
-              ajaxRequest.open('GET', route, true);
-              ajaxRequest.send(null);
+              ajaxRequestFor#{id}.onreadystatechange =  stateChangedFor#{id};
+              ajaxRequestFor#{id}.open('GET', route, true);
+              ajaxRequestFor#{id}.send(null);
             }
 
 
@@ -167,11 +252,11 @@ module LeafletHelper
             function stateChangedFor#{id}() {
 
               // if AJAX returned a list of markers, add them to the map
-              if (ajaxRequest.readyState == 4) {
+              if (ajaxRequestFor#{id}.readyState == 4) {
 
                 // use the info here that was returned
-                if (ajaxRequest.status == 200) {
-                  plotlist = eval("(" + ajaxRequest.responseText + ")");
+                if (ajaxRequestFor#{id}.status == 200) {
+                  plotlist = eval("(" + ajaxRequestFor#{id}.responseText + ")");
                   removeMarkersFrom#{id}();
 
                   for (i=0; i<plotlist.length; i++) {
@@ -184,9 +269,9 @@ module LeafletHelper
                     plotlayersFor#{id}.push(plotmark);
                   } // for
 
-                } // if (ajaxRequest.status == 200)
+                } // if (ajaxRequestFor#{id}.status == 200)
 
-              } // if (ajaxRequest.readyState == 4)
+              } // if (ajaxRequestFor#{id}.readyState == 4)
 
             } // function stateChangedFor#{id}()
 
@@ -206,6 +291,20 @@ module LeafletHelper
       end # def add_support_for_markers(map_id, map_options) 
 
 
+      # The "var name" is the Javascript container that has the map
+      def get_var_name(id="map")
+        return "lh_#{id}"
+      end
+
+
+      def comment(a_string='####################################################')
+        return "<!-- #{a_string}  -->"
+      end
+
+
+      # TODO: Marker management is something that could be abstracted into
+      #       its own class.
+
       # Can't think of a way to use add_marker and delete_marker.
       # They may not be necessary.
       def add_marker(marker={}, map_id='map')
@@ -213,22 +312,17 @@ module LeafletHelper
       end
 
 
+      # delete/remove a specific marker from a given map id
       def delete_marker(marker={}, map_id='map')
         # TODO: delete_marker
       end
 
 
-      # The "var name" is the Javascript container that has the map
-      def get_var_name(id="map")
-        return "lh_#{id}"
-      end
-
-
-      def comment(a_string='####################################################')
-        return "<!-- #{a_string}  -->"
+      # clear/remove all markers for a given map id
+      def clear_markers(map_id='map')
+        @@markers[map_id] = []
       end
 
-
     end # class << self
   end # class L
 end # module LeafletHelper
@@ -241,8 +335,8 @@ A JSON marker array with one entry looks like this:
 [
   {
     "name":"Tunbridge Wells, Langton Road, Burnt Cottage",
-    "lon":"0.213102",
-    "lat":"51.1429",
+    "lon":"0.213102", // SMELL: a string? really?
+    "lat":"51.1429",  // SMELL: ditto
     "details":"A Grade II listed five bedroom wing in need of renovation."
   }
 ]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leaflet_helper
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-08 00:00:00.000000000 Z
+date: 2016-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler