Simple Store Locator

Simple Store Locator is a fully contained, Google Maps-based interface for showing locations (e.g. branches of a business) on a map. It supports geo-position detection, directions (walking, driving etc) and more features.

Simple Store Locator has a dependency on jQuery.

Example 🔗

Example 1: Create a store locator for dog shelters.

new Simple_store_locator({
    cntr: '#ssl-container',
    data_file: 'shelters.txt',
    tooltip_field: 'shelter_name',
    list_template: `
        <p>{shelter_name} ({distance})</p>
        <p>{address}</p>
        <p>{pcode}</p>
        <p>Tel: {phone}</p>
        <p>{show_on_map}</p>
        <p>{show_dirs}</p>
        <p><a href="{url}">Visit website</a></p>`,
    noun: 'shelters',
    country: 'uk',
    unit: 'miles'
});

You can see the output of this demo over here.

API 🔗

Simple Store Locator must be instantiated by calling the Simple_store_locator(params) constructor, where params is an object of the following options:

cntr (str, obj) - a selector string or object reference pointing to a HTML element that will act as the container
data_file (str) - a URI to the data file of store information to use. See Data files.
tooltip_field (str) - a field from within your data that should populate the in-map tooltips that appear when a location is clicked on the map.
place_template (str) - a string template to use for rendering each place in your Data file. See Place templates for syntax.
noun (str) - the plural noun to use for each place. Default is "places", but you may prefer "stores", "shops" etc.
default_radius (int) -the default search radius. Default: 20 miles (or kilometres, depending on unit).
show_user_location (bool) - whether to show the user's location on the map, as well as the places. Default: false.
crow_modifier (int) - an optional percentile to modify the "as the crow flies" calculation. Add 10%, for example, to make it a little more forgiving and include more places in a search radius.
country (str) - a two-character country code relating to the country in which any postcode look-ups (i.e. when the user enters their postcode) will be performed.
zoom (int) - the default zoom level on the map. Default: 10.
unit (str) - the default measurement unit - "miles" (default) or "km".
map_options (obj) - an optional object of additional params to pass to the new google.maps.Map() constructor.
new_tabs (bool) - whether links to places' websites (where the Data file contains the places' websites) should open in a new tab (default: true).
directions_layout (str) - the UI behaviour when the user clicks to view directions to a place. Options are "hide-places" (default), meaning the places list will hide to make room for directions, and "external", meaning directions are shown on Google, in a new tab.
directions_optimism (str) - a string denoting the "optimism" factor to use when Google should predict traffic density, when providing directions. Options are "best_guess" (default), "optimistic", "pessimistic".
directions_mode (str) - the default mode of transport for directions. Options are "driving" (default), "bicycling", "transit" and "walking".
direction_times (bool) - when viewing directions, whether to allow time options such as 'Leave at', 'arrive by' etc (true; default), or instead show simply the direction steps, irregardless of times (false)
directions_alt_routes (bool) - whether directions should offer alternative routes to the default, where available (default: false)
no_radius_circle (bool) - if true, no radius circle will be drawn on the map (though a radius is still enforced)
radius_circle (obj) - an optional object of params to style the radius circles drawn on the map. Refer to the Google documentation for possible params. If omitted, SSL's default styles will be used.
start_pos_icon (str) - an optional URL to an icon to be used on the map to denote the start point in directions. The default is the Google default.
location_icon (str) - an optional URL to an icon to be used on the map to denote the location of the selected place. The default is the Google default.

Data files 🔗

The data file is a JSON-formatted file that holds all the data about the places you want to show - your branches, shops, whatever.

Each entry must contain two mandatory properties: latitude and longitude, so Simple Store Locator knows where they are and can plot them on the graph and use them in distance calculations.

Beyond that, your Data file can contain any data you like (typical would be address, phone etc). The data it holds, together with the Place template you specify, will determine how your places appear in the list of places generated.

A basic example would be:

[
    ...
    {
        "shelter_name" : "Dogs Trust Shoreham",
        "address" : "Brighton Road, Shoreham by Sea, West Sussex",
        "pcode" : "BN43 5LT",
        "latitude" : 50.830329127668,
        "longitude" : -0.28723656896098,
        "phone" : "01273 452576"
    }
    ...
]

Place templates 🔗

Place templates are string templates, fed to the list_template param, that describe the information about a particular place (store, shop etc) should be laid out.

It can feature any property from its entry in your Data file via {property} syntax.

In addition, a few special instructions are available, too, all of which can be seen in action on the demo page.

{show_on_map} - generates a "Show on map" link for the place listing which, when clicked, will locate it on the map.
{show_dirs} - generates a "Show directions" link for the place listing which, when clicked, will generate and display directions to the place.
{distance} - denotes the distance that the place is from the user's location/postcode.

Download Download from Github

Did I help you? Feel free to be amazing and buy me a coffee on Ko-fi!