mapsed.js

On my website I needed to be able to select places on a map.

I couldn't find anything that fully did what I was after so I built mapsed (besides I need the JavaScript practice!).

In short it provides the following:

• UI for users to "select" a place (you get a callback detailing what they picked)
• UI for adding "custom" places
• Support for firing a map up full-window (without having to create a DIV on the page)
• Add searching to the map
• Add/Edit and update your own "custom places" (i.e. not those in the Google Places API doesn't know about, but you do)
• Works with multiple maps on the same page

Demos

Demos at https://mapsed.apphb.com

Settings

showOnLoad (array)

An array of JSON objects that define a set of markers to display when the map is first loaded.

Each element of the array details a place that should be loaded. An element can either be a Custom place or a Google place.

Note that showOnLoad will also accept just one place object, rather than an array (useful if you only want to show one place on your map).

Custom Place

A custom place is a place only your system knows about. You know the address details, lat/lng coordinates, etc. So you have to tell mapsed.js what they are. The following is a custom example:

// Random made up CUSTOM place {   userData: 99,   lat: 53.79,   lng:-1.5426760000000286,   name: "Somewhere",   street: "Over the rainbow, Up high way" }

Google Place

A Google place is one derived from the Google Places database. Google returns (and mapsed.js in turn tells you) a unique reference for a place. The following is a Google place example:

{   lat: 53.798823,   lng:-1.5426760000000286,   reference: "CoQBfAAAAPw-5BTCS53grSLDwX8rwo5BnWnEWnA72lmOjxdgWg2ODGfC5lLjGyoz428IEaln1vJ6rq1jI96Npzlm-N-wmPH2jdJMGfOLxno_rmgnajAnMPzNzuI8UjexIOdHVZPBPvQGloC-tRhudGeKkbdTT-IWNP5hp4DIl4XOLWuYFOVYEhBxNPxaXZdW9uhKIETXf60hGhTc9yKchnS6oO-6z5XZJkK2ekewYQ" }

mapsed.js uses the reference token to ask Google for the details (so rather than storing the full info in your database, you just store the reference).

The lat/lng coordinates still need to be given to the plugin as it only asks Google for details when a marker is clicked upon (i.e. it queries as required) so it needs to know where the marker should be placed on the map.

See custom places example

getMarkerImage (function)

The getMarkerImage callback is fired when a marker is added to the map. It expects a Google Icon object to be returned (see https://developers.google.com/maps/documentation/javascript/reference#Icon).

The method signature for the callback is getMarkerImage(mapsed, markerType, title), where:

See full-window example

mapOptions (object)

This object is passed onto the Google Maps initialisation, thereby allowing the map to be initialised with further parameters.

disablePoi (bool)

On a map, Google adds places of interest hotspots that can be clicked. These might point to a local park or a cinema and bring up details about that place.

Ordinarily this is quite useful, however if it's outside the concern of your audience you may not wish to distract them. For instance our audience is concerned with football venues, so cinemas aren't of interest to them at that time.

The disablePoi setting turns off these point of interest hotspots. However POI cannot be turned off with styled maps.

allowAdd (bool)

Places an "add place" icon (+) in the top-right of the map which allows the user to add additional places to your map.

The onSave callback (see below) must be implemented to capture the place being added so it can be saved.

See add places example

searchOptions (object)

searchOptions is a JavaScript object (i.e. a child object) for defining how search functionality should be added to the map:

enabled (bool)

Must be true to turn on searching - this adds a search textbox onto the map.

placeholder (string)

Placeholder text to be added to the search textbox.

initSearch (string)

A search string to pre-populate the search textbox with. This is executed when the map is loaded and shows the results straight away.

geoSearch (string)

Specifies a search to be made when location is based on geo-location position. This can be when the map is first loaded (#findGeoOnLoad-bool) or when the geo-location button is clicked (#allowgeo-bool).

This search is executed instead of the (#initsearch-string). Rational being the geo-search needs to be relative to the lat/lng co-ordinates. For example setting the geoSearch string to "Business near {POSITION}" the {POSITION} wildcard is replaced with the lat/lng co-ordinates of the user.

See search places example

allowGeo (bool)

Adds a find geo position button to the top left of the map, which when clicked moves the location of the map to the GEO position of the device.

See full-window example

findGeoOnLoad (bool)

When the map is first loaded the centre of the map is set to the GEO location position of the device.

showHelpOnLoad (bool)

Displays the help instructions when the map is first opened (see getHelpWindowString to discover how to set the content).

See full-window example

confirmDelete (bool)

Flags that when a user deletes a place (activated by the onDelete callback) they are asked to confirm the action before the onDelete callback is issued.

See delete places example

Place Model

When a given action occurs (when a place is selected for example) a callback is fired so your application can deal with the event.

As part of the callback mapsed typically passes the data for the place the event was fired for. For convenience we'll call this the model and it will look like this:

<i>A place may have both the <strong>userData</strong> property and the <strong>reference</strong> property populated.  Typically this would be because you're using the <strong>userData</strong> field to lookup the <a href="#google-place"><strong>google place</strong></a> <strong>reference</strong> from your database.</i> 

Events / Callbacks

onSelect

Fired when the Select button is clicked in a place window.

Callback method signature:

See place picker example

onSave

Fired when the Save button is clicked in a place window (after adding or editing a place).

Callback method signature:

See add places example

onDelete

Fired when the Delete button is clicked in a place window. If confirmDelete is enabled the user is prompted for confirmation first.

Callback method signature:

See delete places example

onAdd

Custom method called when the user clicks the "add place" icon (+). Allows the place details to be populated if required.

Once your code has resolved the place details the showAddDialog method must be called for the dialog to be shown on the map (this is necessary as you'll need to do an ajax lookup to find your address details, this allows execution to continue in mapsed).

See full-window example

showAddDialog (method)

Once a new place has been resolved, use showAddDialog to have mapsed show the resulting dialog.

See full-window example

getHelpWindow (string)

If the getHelpWindow method is specified, it should return a string of HTML with the help content to display.

The act of coding the method will add the help icon (?) to the controls buttons in the top-right of the map.

See full-window example

Dependencies

jQuery (10.2 used in development) Google Maps library (v3) Google Places library (v3)

Source code

The source code is knocked up to satisfy a need. I'm not advertising it as best practice, but if you think it will benefit you, please feel free to use it. mapsed.js is released under a ''do what you like with it'' license :-)

Change Log

• 0.0.2 (Planned) Nothing planned.

• 0.0.1 Initial release