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 at https://blog.toepoke.co.uk/mapsed/
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).
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"
}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,
place_id: "ChIJQd3IwBtceUgRha6laiANoro"
}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). In Google terms this is the place_id.
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.
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 onAddSave) *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). |
This object is passed onto the Google Maps initialisation, thereby allowing the map to be initialised with further parameters.
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.
searchOptions is a JavaScript object (i.e. a child object) for defining how search functionality should be added to the map:
Must be true to turn on searching - this adds a search textbox onto the map.
Placeholder text to be added to the search textbox.
A search string to pre-populate the search textbox with. This is executed when the map is loaded and shows the results straight away.
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.
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.
When the map is first loaded the centre of the map is set to the GEO location position of the device.
If [showOnLoad](#showonload-array) is populated with places, the findGeoOnLoad settings is ignored. This is because the GEO position may be different to where the [showOnLoad](#showonload-array) places are located and the user wouldn't see them.Displays the help instructions when the map is first opened (see getHelpWindowString to discover how to set the content).
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.
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. | ||||||
| canDelete | Flags this a deletable place, i.e. when it's clicked on the map it has an delete button. | ||||||
| lat | Latitude position of the place. | ||||||
| lng | Longitude position of the place. | ||||||
| place_id | 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. | ||||||
| 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 | More info url |
Allows custom text/html to be injected as a header and/or footer to the tooltip window which appears when the end-user selects or adds a new place.
// Defines header and footers to be applied to the
// ... select/edit/delete tooltips shown to the user
getHeaderTemplate: function(marker, isEditing) {
// You can have a different header for
// each "markerType". Supported customisations are:
// "custom" - Where your user has previously added a marker
// "add" - Where your user has click "add" to create a new marker
// "google" - Where your user has clicked on a marker found via Google Places APi
var markerType = marker.markerType;
var mode = (isEditing ? "edit" : "view");
return `<center>${markerType} ${mode} header</center>`.toUpperCase();
}The above customisation will show a header and footer to the map tooltip when and end-user selects a custom place.
Custom headers & footers can be set for:
- Custom places as above
- New places (when your end-user clicks the + button
- Google places where a map marker is derived from Google Places API
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 |
Fired when the Save button is clicked in a place window.
- For new places (added via the + toolbar icon) the onAddSave event is fired.
- For existing places the onSave event is fired.
The presence of the onAddSave event enables the + icon on the toolbar allowing the user to add a new 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 |
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 :-) |
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).
[async] Method called when maps Idle event fires (e.g. when the user has finished panning or zooming).
This gives you the opportunity to query your back-end database for any places that are located within the NSEW boundary.
Once a new place has been resolved, use showAddDialog to have mapsed show the resulting dialog.
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.
jQuery (10.2 used in development) Google Maps library (v3) Google Places library (v3)
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 :-)
Read how to work locally to play around and maybe contribute.
-
1.1.0 Bug fix
-
0.0.1 Initial release