https://github.com/magesuite/store-locator

Storelocator module provides a separate page with Google map filled with markers for store subsidiaries. In the sidebar, there is a list of shops that are currently visible on the map. Thanks to search input a user can search for a specific location. Click on marker displays and information popup with a custom template that contains information about a specific shop.

1 Installation
2 Admin settings
3 Backend
- 3.1 Controller
  - 3.1.1 vendor/creativestyle/magesuite-store-locator/Controller/Index/Index.php:34
4 Frontend
- 4.1 Files structure
- 4.2 Store locator page structure
- 4.3 Screens and user journey:
- 4.4 Options (default values)

Installation

This module is optional.

composer require "creativestyle/magesuite-store-locator" ^1.0.0

Admin settings

The basic setting for the store locator page can be found in; Stores -> Configuration -> MageSuite -> Store Locator

Field	Option	Comment

Field

Option

Comment

Is Enabled

Yes/No

If disabled customer will be redirected to the Base URL.

Meta title

Field is used to set meta tile for store locator page.

Meta description

Field is used to set meta description for store locator page.

Backend

In progress

Controller

vendor/creativestyle/magesuite-store-locator/Controller/Index/Index.php:34

class Index extends \Magento\Framework\App\Action\Action
{
    public function execute()
    {
        $result = $this->pageFactory->create();
        .....
        if (!empty($this->configuration->getMetaTitle())) {
            $result->getConfig()->getTitle()->set($this->configuration->getMetaTitle());
        }

        if (!empty($this->configuration->getMetaDescription())) {
            $result->getConfig()->setDescription($this->configuration->getMetaDescription());
        }

        return $result;
    }
}

Frontend

Files structure

storelocator_index_index.xml is a store locator layout.

There are 2 container hotspots, which allow adding some project-specific content above and below the store locator:

<container name="before.store.locator" label="Above Storelocator map" htmlTag="div" htmlClass="cs-container cs-store-locator__before" before="-"/>

<container name="after.store.locator" label="Below Storelocator map" htmlTag="div" htmlClass="cs-container cs-store-locator__after" after="-"/>

The basic phtml file is MageSuite_StoreLocator::storelocator.phtml

Scripts and styles for the store locator module are located in theme-creativeshop, in theme-creativeshop/src/MageSuite_StoreLocator folder.

The store locator page uses cms bundle as a base. There is an additional separate entry file (theme-creativeshop/src/entries/magesuite-store-locator.ts) that generates store locator styles and scripts.

The store locator is initialized in store-locator/index.ts file. The class accepts 2 arguments - jquery dom element and optional options.

if ($('.cs-store-locator').length) {
    new StoreLocator($('.cs-store-locator'));
}

In order to pass custom options in a child project the above file should be overwritten.

Store locator page structure

The main HTML elements of the store locator are:

sidebar
- sidebar toggle
- search input
  - autocomplete
  - action buttons
- results list
map

Screens and user journey:

When the StoreLocator class is initialized a google map is initialized on the DOM element with store-locator-map ID. Also _attachEvents method is executed - this method attaches events not directly connected to the map. There is for example sidebar toggle functionality or events connected with screen resizing.

Then graphql request is sent in order to fetch all stores and their details.

GraphQL response

When the request succeeds response.data.storePickupLocations.items are assigned to this.stores array and _initMap method is executed. _initMap method takes care of creating markers on the map and also tries to set the user's location and zoom map to display shops in the area nearby the user’s current location. The left sidebar is then populated with shops visible on the map (up to limitOfShopsInitiallyDisplayed - see options section below).

If a number of shops that is visible on the current map zoom exceed the limitOfShopsInitiallyDisplayed limit, a show more button is added at the bottom of the sidebar list.

When a user searches for a location in the sidebar input the request is initialized in order to get the coordinates of the inserted query. The method responsible for the action is called searchButtonClickHandler. Then the script pan (zoom) to coordinates returned by the backend and sets the user location to this place. Additionally, distances for all stores are recalculated.

There is also autocomplete feature introduce in order to help a user quickly find the desired location. When a user types anything in the search form modified Magento search widget is executed (magesuite.quickSearch). The widget is modified in store-locator/form-mini.js file.

After clicking on a marker a popup with shop information is displayed.

Options (default values)

Option	Default value	Comment

Option	Default value	Comment
mapOptions → zoom	7	Initial zoom that is set when the map is loaded. It is usually quite small to show at least a greater part of an area where the majority of stores is located
mapOptions → center	{ lat: 51, lng: 9 }	Coordinates for initial central point of the map. By default they are set to show the most part of Germany.
mapOptions → mapTypeControl	false	https://developers.google.com/maps/documentation/javascript/controls
mapOptions → streetViewControl	false	https://developers.google.com/maps/documentation/javascript/controls
mapOptions → fullscreenControl	false	https://developers.google.com/maps/documentation/javascript/controls
basicZoom	13	Desktop basic zoom is set when the map centers on a specific location (for example when the user is geolocalized or when we pan to a specific store or a location)
basicZoomSmallDesktop	12	Tablet/small desktop map zoom.
basicZoomMobile	12	Mobile zoom.
useDefaultMapStyles	false	When set to true default google maps styles are used. If not, styles from store-locator/ map-style.js file are used.
markerIcons		`sizes for markers in px`
clusterStyles	`{ url: '', height: 22, width: 22, textSize: 12, textColor: '#fff', backgroundPosition: 'center', }`	Styles for clusters (circles that groups stores ans show their amount if there is no space to show all markers separately)
limitOfShopsInitiallyDisplayed	50	Browsers may have problems with rendering hundreds or thousands of store in the sidebar. If there is a lot os subsidiaries limit is necessary to avoid performance problems
storeData	` name latitude longitude city street postCode description sourceCode countryId phone fax email url `	Fields included in graphql call

mapOptions: {
    zoom: 7, //
    center: { lat: 51, lng: 9 },
    mapTypeControl: false,
    streetViewControl: false,
    fullscreenControl: false,
},
basicZoom: 13,
basicZoomSmallDesktop: 12,
basicZoomMobile: 12,
useDefaultMapStyles: false
markerIcons: {
    pin: {
        sizes: {
            x: 18,
            y: 25,
        },
    },
    pinAlt: {
        sizes: {
            x: 18,
            y: 25,
        },
    },
    pinActive: {
        sizes: {
            x: 18,
            y: 25,
        },
    },
    userLocation: {
        sizes: {
            x: 25,
            y: 25,
        },
    },
},
clusterStyles: {
    url: '',
    height: 22,
    width: 22,
    textSize: 12,
    textColor: '#fff',
    backgroundPosition: 'center',
},
limitOfShopsInitiallyDisplayed: 50,
storeData: `
    name
    latitude
    longitude
    city
    street
    postCode
    description
    sourceCode
    countryId
    phone
    fax
    email
    url
`,

In order to learn more about possible google map options visit: https://developers.google.com/maps/documentation/javascript

StoreLocator (optional)