LeafletHelper

For those of us who don't want to get our hands dirty writing JavaScript (shutter) this library is for you. Actually, its for me, but you can use it if you like. It is a Ruby-wrapper around some basic leaflet.js functions. It uses either Open Street Map or your account on mapbox.com. It handles markers on maps and the clustering of those markers. It supports multiple maps per web page.

This gem has a simple Sinatra-based web application that demonstrates its use.

Launch the example web-app using a bash-based terminal like this:

lh=`gem which leaflet_helper`
pushd `dirname $lh`/../example
bundle install
./start
# open your web browser to http://localhost:4567
# control-C to stop the example
# popd to return to your current directory

Recent Changes

This is it for a while. Its doing all I wanted it to do. There is at least 1 outstanding issue which prevents good multi-map support. When I fix it, I will bump the version to 0.7.7 to reflect the version of the leaflet.js library that this thing uses.

v0.0.9 - released

  • added support for cluster_marker to defaults hash on init.

v0.0.8 - released

  • Added basic clusters using the leaflet plugin markercluster
  • refactored some code

v0.0.7 - released

  • Added StringTemplate class Reused the regex from @redpist easy_template gem

  • Fixed typo in ManageMarkers#remove - fat fingered a p[ when all I wanted was a [

Installation

Add this line to your application's Gemfile:

gem 'leaflet_helper'

And then execute:

$ bundle

Or install it yourself as:

$ gem install leaflet_helper

Usage

Here is another example of how to use LeafletHelper with multiple maps on a webpage [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:

  %html
    %head
      = LeafletHelper::L.init(options)

options

The 'options' is a hash. It defaults to:

    {
      openstreetmap:  true,       # either Open Street Maps or
      mapbox:         false,      # Mapbox.com is used as the map tile provider; not both
      markers:        false,      # set to true to make use of markers on top of maps
      cluster:        false,      # set to true to load the markercluster plugin
      latitude:       AREA51.latitude,  # default map center
      longitude:      AREA51.longitude, # default map center
      zoom:           9,
      min_zoom:       2,
      max_zoom:       22
    }

There is also a cluster_marker default used to create markers for clusters. The default function is maintained in the file cluster_icon_create_function.js.erb.

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:

o = {
  style: "width: 1200px; height: 400px"
}.merge(options)

Of course you could just use some CSS to add anything you want. But if you are an inline kinda UI/UX newbie 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 ready 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:

        o = @@defaults.merge({
                    id:         id,
                    map_name:   get_map_name(id),
                    route:      "#{id}/markers"
                  }.merge(options))

System Environment Variables

If you are going to use mapbox.com as a map tile provider you will need an account on that service.

The following system environment variables are used in loading your sceen from mapbox.com:

  • MAPBOX_URL
  • MAPBOX_USER
  • MAPBOX_STYLE_ID
  • MAPBOX_ACCESS_TOKEN

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.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Of course if that doesn't work try something else. I'm not any good a javascript; if you are, send me some pull requests to improve my naive notions.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/MadBomber/leaflet_helper.

License

You want it? Its yours!