Maplace.js: markers and a control menu for Google Maps

One object in front of the Maps API

Maplace.js is described as a Google Maps Javascript plugin for jQuery, and the heading in the README is blunt about its status: currently unmaintained. The last tagged release is v0.2.10 from 2014-08-12, and the package manifest still carries that version, though the repository was pushed to as recently as 2026-10-19.

The library is a convenience layer over the Google Maps JavaScript API v3. Its pitch is that it helps you embed Google Maps into your website and quickly create markers and a controls menu for the locations on the map, without writing the API calls yourself.

The setup is three pieces. You include the Google Maps API v3 along with jQuery, you add two elements to the page, and you construct a Maplace with a locations array and a configuration object:

new Maplace({
	locations: data,
	controls_type: 'list',
	controls_on_map: false
}).Load();

The HTML side is a container for the controls and a container for the map:

<div id="controls"></div>
<div id="gmap" style="with:300px;height:250px;"></div>

The Load method at the end is the whole lifecycle, which is what makes the library small enough to read in one sitting. There is no init, no render, no destroy.

The demo site is at maplacejs.com, which is also the homepage.

The locations array, and the per-location overrides

The locations array is where the data goes, and each entry is a plain object with a documented set of fields:

var data = [{
	    lat: 45.9,
	    lon: 10.9,
	    title: 'Title A1',
	    html: '<h3>Content A1</h3>',
	    zoom: 8,
	    icon: 'http://www.google.com/mapfiles/markerA.png'
	},{
	    lat: 44.8,
	    lon: 1.7,
	    title: 'Title B1',
	    html: '<h3>Content B1</h3>',
	    show_infowindow: false
	}
];

So latitude and longitude are required in practice, and everything else is optional per location. The title and the html pair are what appear in the info window, the zoom sets the map level when that marker is selected, the icon replaces the default pin, and show_infowindow false suppresses the popup for a particular marker while leaving it visible on the map.

That last field is the one worth noticing. The global options include show_infowindows, a boolean defaulting to true, and the per-location version lets you opt out for one marker. A map of 200 branch offices where only the regional hubs should open a popup is a normal requirement, and having it per location rather than only globally is a small design decision that saves awkward workarounds.

The icon field takes a URL, which in the example points at a marker image on Google's mapfiles host. The html field is inserted as markup rather than treated as text, which is what lets you put a heading in the popup, and also means the value is only as safe as the data you put in it.

The control menu, and the options that have to agree

The controls menu is the feature that distinguishes Maplace from a bare marker loop, and its configuration is where the library is most opinionated.

The controls_div option is the element the menu is written into, defaulting to #controls. The entry is explicit about the conditions: generate_controls must be true, controls_on_map must be false, and there must be at least more than one location on the map. That is a three-way dependency, and it is the single most likely reason a menu does not appear in a new installation.

generate_controls, defaulting to true, decides whether the menu is generated at all. controls_type chooses between dropdown and list, with dropdown as the default. controls_on_map, defaulting to true, decides where the menu lives: if false, it is generated into the element defined by controls_div, and if true it is placed on the map. controls_position, defaulting to RIGHT_TOP, positions the controls on the right, below the top-right elements of the map.

Then the presentation options. controls_title adds a header text to the menu. controls_cssclass adds a custom class to the menu element, which is how you restyle it without patching the library. And controls_applycss, defaulting to true, decides whether the default styles are applied; set it to false and the menu comes out unstyled, which is the hook for using your own stylesheet instead.

Two more options round it off. view_all, defaulting to true, controls whether the view all link is created, and view_all_text sets its text, with View All as the default. And start, an integer defaulting to 0, sets the first location to show, where 0 stands for view all.

The pattern across all of these is the same: a boolean that switches the library's own behaviour off, and a separate option for the content, so you can replace the styling without replacing the behaviour.

Five map types and the option objects behind them

The type option decides what is drawn, and it takes five values: marker, polyline, polygon, directions and fusion, with marker as the default. The other four change what the locations array means, and each brings its own options object that is passed straight through to Google.

map_options is the map options object as defined by Google, defaulting to a ROADMAP type and a zoom of 1. The entry includes an important caveat: the center property will be ignored, and it points at the Install page to see how to center the map with only one location. styles holds the style options as defined by Google, and stroke_options holds the stroke options object used in the Polyline, Polygon, Directions and Fusion map types. directions_options is the directions options object, with the travelMode, unitSystem, optimizeWaypoints, provideRouteAlternatives, avoidHighways and avoidTolls fields shown in the table. And fusion_options holds the Fusion tables options.

Directions has one extra option of its own. directions_panel takes the ID or class of the div in which to display the directions steps, and it defaults to null.

The remaining global options round out the map behaviour. show_markers and show_infowindows, both defaulting to true, switch off the markers and the info windows independently. infowindow_type defaults to bubble, and the entry is blunt that only bubble is supported. The commons option is an object that overwrites every location with a set of common properties, which is how you avoid repeating the same icon or title across a hundred entries. And the locations option itself, an array of locations, defaults to empty.

So the library is not only a marker helper. The package keywords list circles and directions alongside markers and locations, and the type option covers the same ground.

The build, and what a jQuery 2.1 dependency implies

The package manifest is from the era of the library, and it is worth reading as history rather than as a recommendation.

The name is maplace-js, the version is 0.2.10, the description is a Google Maps jQuery plugin and markers helper, and the main entry is dist/maplace.min.js. The published files are dist, src, package.json, README.md and LICENSE-MIT, so the source ships alongside the build. The homepage points at the GitHub repository, and the licence is MIT.

There is exactly one runtime dependency, jquery at about 2.1, which was the current jQuery line when the library was written. That is the practical constraint: the plugin expects a jQuery of that era, and the site that includes it also has to include the Google Maps API v3, so the two are loaded together.

The build tooling is Grunt, with grunt-contrib-uglify for minification, grunt-contrib-jshint and grunt-jscs for linting and style checking, grunt-contrib-watch for the development loop, grunt-contrib-copy, and grunt-string-replace. The scripts are npm install and grunt build for a build, grunt watch for development and grunt test -v for the test run. The repository also has a Gruntfile.js, a .jscsrc file, a .travis.yml and a bower.json, so it was consumable through Bower as well as npm.

The website/ directory at the top level is the demo site, and the src/ directory holds the plugin source. The docs site at maplacejs.com is the demo and the documentation, and the fact that the README's own first line says the project is currently unmaintained tells you what to expect from a dependency on it. The library still does what it did, and it will not do anything new.

Editorial conclusion

Adopt Maplace.js if you want a locations map with a control menu and you would rather not write the Google Maps API calls yourself, because the whole configuration is one object with documented defaults and the control menu options cover most of what a small site needs. Do not adopt it as a foundation for anything you plan to extend, because the README marks the project currently unmaintained and the last tagged release is 0.2.10 from 2014, so you are inheriting an API that will not gain features. Before you build on it, check that your Google Maps key and the API version it targets still behave as it did, and read the option table carefully, because the controls_div and controls_on_map options have to agree with each other or the menu silently does not appear.

Frequently asked questions

Official sources

1. danielemoraschi/maplace.js on GitHub
2. License: MIT
3. Project website
4. README
5. Releases