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.
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:
| Parameter | Description |
|---|---|
| mapsed (object) | The plug-in calling the method |
| markerType (string) |
The type of marker being added to the map, this can be: *new* - New marker is being added by user (via the "+" button - see allowAdd) *google* - Marker being added was derived from the Google Places API *custom* - Marker being added was derived from the application database, i.e. derived from the showOnLoad array. |
| mapsed (bool) | title attribute of the marker (useful for tracking which marker in an showOnLoad is being drawn). |
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.
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.
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.
findGeoOnLoad (bool)
When the map is first loaded the centre of the map is set to the GEO location position of the device.
If showOnLoad is populated with places, the findGeoOnLoad settings is ignored. This is because the GEO position may be different to where the showOnLoad places are located and the user wouldn't see them.
showHelpOnLoad (bool)
Displays the help instructions when the map is first opened (see getHelpWindowString to discover how to set the content).
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.
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:
| Property | Description | ||||||
|---|---|---|---|---|---|---|---|
| canEdit | Flags this an editable place, i.e. when it's clicked on the map it has an edit button. | ||||||
| lat | Latitude position of the place. | ||||||
| lng | Longitude position of the place. | ||||||
| reference | Unique reference to a place in the Google Places database (this is provided by Google), see also Google Place | ||||||
| userData |
Some unique identifier to link a marker on the map with a database entity (e.g. primary key). For new places this will be empty and should be populated by the onSave callback. A place may have both the userData property and the reference property populated. Typically this would be because you're using the userData field to lookup the google place reference from your database. | ||||||
| markerType |
Specifies what mode the marker for the place is in. Can be:
|
||||||
| name | Name of the place (e.g. City Varieties). | ||||||
| street | Street the place is on. | ||||||
| town | Town the place is in, e.g. Leeds. | ||||||
| area | Area the place is in, e.g. West Yorkshire. | ||||||
| postCode | Postcode/zipcode of the place, e.g. LS1 6LW | ||||||
| telNo | Telephone number of the place. | ||||||
| website | Website address of the place. | ||||||
| url | Google+ page url |
Events / Callbacks
onSelect
Fired when the Select button is clicked in a place window.
Callback method signature:
| Parameter | Description |
|---|---|
| mapsed | Reference to the mapsed object so you can call into the plug-in, e.g. mapsed.showMsg("title", "some message") will show a modal message on the map |
| details | Place details, see Place Model for full details |
onSave
Fired when the Save button is clicked in a place window (after adding or editing a place).
Callback method signature:
| Parameter | Description |
|---|---|
| mapsed | Reference to the mapsed object so you can call into the plug-in, e.g. mapsed.showMsg("title", "some message") will show a modal message on the map |
| details | Place details, see Place Model for full details |
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:
| Parameter | Description |
|---|---|
| mapsed | Reference to the mapsed object so you can call into the plug-in, e.g. mapsed.showMsg("title", "some message") will show a modal message on the map |
| details | Place details, see Place Model for full details |
| Return (bool) |
The onDelete callback expects a boolean value to be returned. If your delete operation is successful return true, otherwise return false.
If your callback returns false the map marker remains on the map - which is what you want :-) |
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).
showAddDialog (method)
Once a new place has been resolved, use showAddDialog to have mapsed show the resulting dialog.
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.
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