Add/Pick/Search Places On Google Maps - mapsed.js

mapsed.js is a jQuery plugin for Google Maps that allows the user to select, search places and add/remove custom places on a Google Map. Requires Google Maps Places API.

More Features:

• Shows place info once the map has finished loading.
• Allows the user to edit the content of selected places.
• Displays the details of a place.
• Centers the map based on your GEO.
• Supports custom themes.
• Custom marker images.
• Help window showing additional instructions to the user.
• Callback functions.

How to use it:

1. Load the necessary jQuery library and Google Maps Places API in the document. Don't forget to replace the API key with your owns.

<script src="https://maps.googleapis.com/maps/api/js?libraries=places&key=API KEY"></script>
<script src="/path/to/cdn/jquery.min.js"></script>

2. Download and load the mapsed.js plugin after jQuery.

<script src="mapsed.js"></script>

3. Create an element that serves as the container for the Google map.

<div id="myMap"></div>

4. Initialize the Google map and add a custom place to the map.

$("#myMap").mapsed({
  showOnLoad: [
    // City Varieties
    {
      // flag that this place should have the tooltip shown when the map is first loaded
      autoShow: true,
      // flags the user can edit this place
      canEdit: false,
      lat: 53.798823,
      lng:-1.5426760000000286,
      place_id: "ChIJQd3IwBtceUgRha6laiANoro"
    },
    // Random made up CUSTOM place
    {
      // flag that this place should have the tooltip shown when the map is first loaded
      autoShow: true,
      lat: 53.79,
      lng:-1.5426760000000286,
      name: "Somewhere",
      street: "Over the rainbow, Up high way",
      userData: 99
    }

  ]
});

5. Create a Place Picker that allows you to get the place info using the onSelect callback.

$("#myMap").mapsed({
  // allow user to select somewhere
  onSelect: function(m, details) {
    var msg = 
      "Name: " + details.name + 
      "<br/>Address: " + 
        details.street + ", " + 
        details.town + ", " + 
        details.area + ", " + 
        details.postCode +
      "<br/>website: " + details.website +
      "<br/>g+: " + details.url +
      "<br/>Tel: " + details.telNo            
    ;
    if (details.place_id) {
      msg += "<br/>Place_id: " + details.place_id
    }
    m.showMsg("Place selected!", msg);
    
    // indicate tip should be closed
    return true;
  },
  
  showOnLoad: 
    // City Varieties
    {
      // flag that this place should have the tooltip shown when the map is first loaded
      autoShow: true,
      lat: 53.798823,
      lng:-1.5426760000000286,
      place_id: "ChIJQd3IwBtceUgRha6laiANoro"
    }
  
});

6. This example shows how to add a custom place on the Google map.

$("#myMap").mapsed({

  // Adds the "+" button to the control bar at the top right of the map
  allowAdd: true,
  
  // Enables edit of custom places (to your web application, not Google Maps!)
  // ... again the presence of the callback enables the functionality
  onSave: function(m, newPlace) {
    var missing = [];
    
    // detect errors starting at bottom
    // ... we only have space for one error at a time, so this way we'll report 
    // ... from the top down
    if (newPlace.postCode === "") missing.push("postcode");
    if (newPlace.street === "")   missing.push("street");
    if (newPlace.name === "")     missing.push("name");
    
    // anything missing?
    if (missing.length > 0) {
      // return the error message so the callback doesn't progress
      return "Required: " + missing.join();
    }
    
    if (newPlace) {
      if (newPlace.markerType == "new") {
        // simulate a primary key being save to a db
        newPlace.userData = parseInt(Math.random() * 100000);
      }

      var title = "";
      var msg = 
        "userData: " + newPlace.userData + 
        "<br/>name: " + newPlace.name +
        "<br/>street: " + newPlace.street + ", " + 
          newPlace.area + ", " + 
          newPlace.town + ", " + newPlace.postCode + 
        "<br/>telNo: " + newPlace.telNo + 
        "<br/>website: " + newPlace.website + 
        "<br/>g+: " + newPlace.url
      ;
      if (newPlace.place_id) {
        msg += "<br/>Place_id: " + details.place_id
      }
      if (newPlace.markerType == "new") {
        title = "New place added!";
      } else {
        title = "Place saved!";
      }
      m.showMsg(title, msg);
    }
  
    // indicate form was OK and saved
    return "";
  }
});

7. The plugin also allows you to delte a custom place from the Google map.

$("#myMap").mapsed({
  showOnLoad: [
    // City Varieties
    {
      autoShow: true,
      canEdit: true,
      lat: 53.798823,
      lng:-1.5426760000000286,
      name: "CITY Varieties Music Hall",
      url: "https://plus.google.com/103655993956272197223/about?hl=en-GB",
      website: "http://www.cityvarieties.co.uk/",
      telNo: "0845 644 1881",
      street: "Swan Street,",
      town: "Leeds",
      area: "West Yorkshire",
      postCode: "LS1 6LW",
      userData: 99
    }
  ],
  
  // Allows the user to delete a "custom" place they've previously 
  // ... added
  onDelete: function(m, placeToDelete) {
    m.showMsg(
      "YOUR DELETE CODE HERE",
      "<strong>" + placeToDelete.name + "(" + placeToDelete.userData + ")</strong> has been removed."
    );
    
    // here would be code your application to do the actual delete
    
    // return true to confirm it was deleted OK and remove marker from the map
    // return false if the delete failed
    return true;
  },
  
  // Flag that we want the user to confirm the delete before we actually do it
  confirmDelete: true
      
});

8. Allows the user to search a place.

$("#myMap").mapsed({
  // Adds a predictive search box
  searchOptions: {
    enabled: true,
    //initSearch: "Football in Leeds",
    geoSearch: "Hotels near {POSITION}",
    placeholder: "Search ..."
  },
  
  // Turn on geo location button
  allowGeo: true,
  findGeoOnLoad: true,

  // allow user to select somewhere
  onSelect: function(m, details) {
    var msg = 
      "name: " + details.name +
      "<br/>street: " + details.street + ", " + 
        details.area + ", " + 
        details.town + ", " + details.postCode + 
      "<br/>telNo: " + details.telNo + 
      "<br/>website: " + details.website + 
      "<br/>g+: " + details.url
    ;
    if (details.place_id) {
      msg += "<br/>Place_id: " + details.place_id
    }
    m.showMsg("You selected ...", msg);
    // indicate tip should be closed
    return true;
  },
  
  // shows additional instructions to the user  
  getHelpWindow: function(m) {
    var html = 
      "<div class='mapsed-help'>" +
        "<h3>Find a venue</h3>" +
        "<ol>" +
          "<li>Simply use the <strong>search</strong> box to find a venue in your area.</li>" +
          "<li>On the pop-up, click <strong>Select</strong> to pick a pitch.</li>" + 
        "</ol>" +
        "<h3>New venues</h3>" +
        "<ol>" +
          "<li>Your venue isn't displayed?  Simply click on the map where your pitch is.</li>" +
          "<li>Fill in the details in the dialog.</li>" + 
          "<li>You can drag the marker around to pinpoint the right location.</li>" + 
          "<li>Once you're happy, click the <strong>OK</strong> button</li>" + 
        "</ol>" +
      "</div>"
    ;

    return html;
  }
  
})

9. Full plugin options and callback functions.

// Array of places to show on the map initially
// (see accompanying examples for illustration)
showOnLoad: null,

// Specifies the buttons and tooltips added to the map toolbar
ToolbarButtons: {
  Go: "Go",
  More: "More|There are more results available ...",
  AddPlace: "+|Add a place",
  CloseMap: "×|Close map",
  Geo: "⊗|Centre map based on your location",
  Help: "?|Show help"
},

// Species the text of the buttons used the dialog templates
ActionButtons: {
  Select: "Select",
  Edit: "Edit",
  Delete: "Delete",
  Save: "Save"
},

// Options for drawing the map.  This is the same object
// that is passed to the Google Maps API when creating the map.
// If you need something custom supported by the Google Maps API
// you should be able to add in your own initialisation code 
// to this object.
mapOptions: {
  // Initial zoom level (initially not set)
  // ... be cautious when setting a zoom level _and_ defining custom places as you may set the
  // ... level to such a level that your places aren't visible
  // ... by default the map will expand to show all custom places, you can change this with the "forceCenter" option
  zoom: DEFAULT_ZOOM,

  // Default to the best theatre ever :-)
  center: DEFAULT_CENTER,

  // Type of map to show initially
  mapTypeId: google.maps.MapTypeId.ROADMAP
},

// template options
templateOptions: {
  custom: {
    view: {
      header: "<center>custom view header</center>",
      footer: "<center>custom view footer</center>",
    },
    edit: {
      header: "<center>custom edit header</center>",
      footer: "<center>custom edit footer</center>"
    }
  }
},

// Flags whether Google Maps should still display other points-of-interest
// By default POI is enabled because the POIs can't be turned off when using custom styled maps
// (well without significant hacks!)
// If you require custom maps, you need "disablePoi" set to false
disablePoi: false,

// Flags that the user can add new places (as well as edit/delete), an "+" icon appears
// at the top right of the map
allowAdd: false,

searchOptions: {
  // Flags that the user can search for places themselves
  // ... adds a search box to the map
  enabled: false,

  // Placeholder text for the search box
  placeholder: "e.g. Hotels in Leeds",

  // Initialises the place search with a given text search
  // ... (i.e. once the map has been created, the results for this string are also shown)
  initSearch: "Hotels in Leeds",

  // Performs a search when geo-location is activated.  This can be either 
  // on load (see "findGeoOnLoad" option) or when the Geo location button is clicked
  // {POSITION} is replaced with the detected Geo location position
  // "geoSearch" supersedes any "initSearch" specified (if the user enables Geo location for the map)
  geoSearch: "5aside football near {POSITION}"
},

// Event when user clicks the "Select" button
// prototype: function(mapsed, details)
onSelect: null,

// Allows new places to be edited
// prototype: function(mapsed, newPlace)
//   return a error message string if you're not happy with what's been entered
//   return an empty string to confirm it's been saved
onSave: null,

// Allows the user to delete a "custom" map they've previously added
// prototype: function(mapsed, details)
//  return true to confirm delete, false abandons the delete
onDelete: null,

// Flags that the user is asked for confirmation if they try and
// delete a place
confirmDelete: false,

// Event fires when user clicks the "X" button (only in full window mode)
// prototype: function(mapsed)
//  return true to close the map, false keeps it open
onClose: null,

// Callback for getting the [image] URL to use for a marker
// Parameter "markerType" is passed, indicating the type of marker, this can be
// prototype: function(mapsed, markerType, title)
// Parameters:
//   mapsed: Reference to the mapsed plugin
//   markerType: The type of marker being added to the map:
//      "new" = Marker created using the "+" button to add a new place
//      "google" = Marker is being added from a Google Places place
//      "custom" = Marker is being added from application database (via "showOnLoad" array)
//   title: Title attribute of the marker
// Returns:
//   Google Icon object (see https://developers.google.com/maps/documentation/javascript/reference#Icon)
getMarkerImage: null,

// Adds a help button to give further instructions to the end user
// prototype: function()
getHelpWindow: null,

// show the help dialog when the map is loaded
showHelpOnLoad: false,

// Adds a GEO location button onto the map which is used to set the 
// centre of the map according to the user's GEO location position
allowGeo: false,

// Flags that mapsed should place the centre of the map where the user's
// GEO location position is.
// Note: This is ignored if "showOnLoad" property is populated as there is 
//       a risk the places won't be shown on the map
findGeoOnLoad: false,

// When adding custom places, mapsed will expand the map to show all places
// Usually this is what you'd want, but sometimes you may want to focus on a particular area
// "forceCenter" will override the default behaviour and centre where specified in the options
forceCenter: false

Changelog:

v2.1.0 (2024-03-24)

• update

v2.0.0 (2024-03-13)

• allow template customisation hooks
• ability to add markers to the current map boundary
• marker pagination
• bugfixes

v1.2.0 (2024-02-23)

• allow template customisation hooks
• ability to add markers to the current map boundary
• marker pagination
• bugfixes

v1.1.0 (2024-02-20)

• Bugfixes

---

This awesome jQuery plugin is developed by toepoke. For more Advanced Usages, please check the demo page or visit the official website.