@wmyl/places

Interactive map based on Google Maps. Each place can have a popup with information, along with other features such as in-view list and clustering.

Installation

npm install --save @wmyl/places

Usage

Step 1 - Get Google Maps API key

Don't worry! It's free, at least for a smaller amount of request.

https://developers.google.com/maps/documentation/javascript/get-api-key

Step 2 - Add HTML

Add container such as div with class name places in HTML

<div class="places"></div>

Step 3 - Init JavaScript

import Places from '@wmyl/places';

...

const options = {
    tag: "https://maps.googleapis.com/maps/api/js?key=<YOUR_KEY_HERE>",
    places: [{
        lat: 57.682909,
        lng: 11.932970,
        name: 'My First Place'
        address: 'Exampleroad 23',
        link: 'https://github.com/wmyl/places',
        phone: '555-1234567',
        comment: 'This place is wonderful!'
    }, {
        lat: 58.232909,
        lng: 07.562970,
        name: 'My Second Place'
        address: 'Exampleroad 25',
        link: 'https://github.com/wmyl/places',
        phone: '555-1234569',
        comment: 'This place is almost as wonderful!'
    }],
    popup: true,
    mapStyle: 'minimalistic',
    imagePath: '/assets/static/images/dog',
    sidebar: {
        footer: {
            text: 'Visit our site!',
            logo: '/assets/static/images/companyLogo.png',
            logoLink: 'https://github.com/wmyl/places'
        }
    },
};

new Places(options);

...

Step 4 (Optional) - Add custom styling

You can override all styling on the map with your own css.

Options

Option	Type	Required	Default	Description
tag	string	Yes		Google Maps Script tag with API Key
places	array	No	[]	List of place objects
popup	any	No		Whether to show popup on marker click or not and if so, specify popup options
mapStyle	any	No	'default'	Use one of predefined map styles or provide own
startPos	object	No	{ lon: 57.7004286, lat: 11.9543521 }	Start position of map. Will change if geoloc is enabled and position is found
noGeoloc	Boolean	No	false	Set to true to disable geolocation in map
pinImagePath	string	No		Path to pin images. Will pick different depending on place type. See below.
iconImagePath	string	No	Same as pinImagePath	Path to icon images. Will pick different depending on place type. See below.
sidebar	any	No		Whether to use sidebar or not and if so, specify options
clusterer	any	No	false	Whether to use marker clustering or not and if so, specify clusterer options

Place object

Property	Type	Required	Default	Description
lat	number	Yes		The latitude of the place
lng	number	Yes		The longitude of the place
type	string	No		The type of the place. Not predefined, so it can be anything. Will only affect the icon of the place.
name	string	Yes		The name of the place. This must match the name in Google Maps for the search to work properly.
address	string	Yes		The address of the place. This must match the address in Google Maps for the search to work properly.
link	string	No		URL to the link for the place
phone	string	No		Phone number to the place
comment	string	No		Short description or comment of the place

Popup options

Option	Type	Required	Default	Description
noResultText	string	No	Vi hittar tyvärr inte några resultat på <PLACE_NAME>	Text shown when to result is found for a location. Use <PLACE_NAME> to insert the name of the place.
link	string	No		URL for link shown when a place is searched for but not present, such as "Contact Us". Both link and link text is required.
textLink	string	No		Text for link shown when a place is searched for but not present, such as "Contact Us". Both link and link text is required.
noResultHTML	string	No		Custom HTML to override all other HTML in the popup, when place is not present.

Map styling

It is possible to either specify a custom array of Google Map styles, see more here: https://mapstyle.withgoogle.com/

It is also possible to specify one of predefined styles. Current valid stlyes are:

• default
• minimalistic

Image paths

Path to the collection of images for the place icons. The images need to be in .png-format. The file ending (.png) will automatically be appended. If types are used, this will be appended to the image path as well. Note that if pinImagePath is not specified, Google Maps default pins will be used for the map and no icons will be shown in sidebar.

For example, if image path is place_ and a place has type "hotel" the map will expect there is an image named place_hotel.png. If the place has no type, simply place_.png will be expected.

Sidebar options

Options can be specified but for default usage true is enough. Will display a sidebar to the leftwith all places in viewport. Has a search bar at the top. On mobile, the sidebar will be on the lower half of the screen and is minimizable. On mobile phones, the sidebar will be minimized when tapping a marker on the map.

Option	Type	Required	Default	Description
searchBar	object	No		Search bar options object. If the sidebar is enabled, the searchbar is always enabled too.
footer	any	No	false	Whether to use sidebar footer or not and if so, specify options.
mobileListToggleIcon	string	No		Image to use for closing and opening sidebar on smaller devices (preferably an arrow)

Search bar options

Option	Type	Required	Default	Description
searchIcon	string	No		Image to use as the search icon (typically magnifying glass)
placeholder	string	No		Placeholder for search bar

Footer options

Option	Type	Required	Default	Description
html	string	No		Replaces all HTML in the footer with this string.
text	string	No		Text shown in footer
logo	string	No		Path to image to use in logo
logoLink	string	No		URL for the logo (requires logo image)
logoTitle	string	No		Title property for the logo image (requires logo image)

Clusterer options

Clusterer will put close places together in a cluster with a number showing how many places are clustered in the cluster.

Option	Type	Required	Default	Description
imagePath	string	No		See below.
textSize	number	No	16	Textsize of the numbers in the clusters
textColor	string	No	'#000'	Textcolor of the numbers in the clusters
sizes	array	No	[10, 10, 10, 10, 10]	Array of pixel sizes for the different images

The imagePath is similar to the imagePath of the main options but more strict. It requires that there are five different square PNG images, each ending with a number from 1 to 5. For example, if imagePath is cluster_ball_, the clusterer will expect that there are five images; cluster_ball_1.png, cluster_ball_2.png, cluster_ball_3.png, cluster_ball_4.png and cluster_ball_5.png. This is unfortunately how the used library js-marker-clusterer works.

Examples

Bare minimum map

This is the absolute minimum configuration - it will only show the default Google Maps.

const options = {
    tag: "https://maps.googleapis.com/maps/api/js?key=<YOUR_API_KEY>",
};

new Places(options);