As you would expect, Locator is compatible with all common web browsers and devices. On narrower screens, the location list reflows to display under the map container. As a bonus feature, clicking the 'Directions' link against a list item opens the full Google Maps website or app; giving users step-by-step instructions and an estimate of time for getting to the location (directions are only supported with XML data types). You will find Locator to be a remarkably clever and flexible stack to use; invaluable for use in dozens of different projects.
Locator is using Google Maps API 3. The database of store locations can be generated from an exported Google Earth KML file or manually coded in either XML or JSON formats. A great many options are provided in Locator, making it the most customisable solution of its kind available for RapidWeaver.
Of course, Locator is not only limited to displaying the location of businesses. It can also be leveraged to display other data on a Google Map. Locator could quite easily be used to display a map of sporting fixtures, campuses, real estate for sale, events, places of interest, businesses and just about any other spacial data. Likewise Locator can be configured to just display just a simple static map with one highlighted pin (no search box or list of locations). Locator is a highly configurable map stack which offers excellent value for money.
A visitor to your website starts a location search, by entering a town name or other location in the search box. Or you can enable auto-geolocation (if your website has SSL support). When a location search is run, the location from the user is geocoded and compared to locations in your database. The locations are shown visually on a Google Map (with map pins) and the details of the locations are also shown (closest first) as an interactive list. Clicking pins or location items brings the details of that pin into view.
Locator is using Google Maps API 3. The database of store locations can be generated from an exported Google Earth KML file or manually coded in either XML or JSON formats. A great many options are provided in Locator, making it the most customisable solution of its kind available for RapidWeaver.
Of course, Locator is not only limited to displaying the location of businesses. It can also be leveraged to display other data on a Google Map. Locator could quite easily be used to display a map of sporting fixtures, campuses, real estate for sale, events, places of interest, businesses and just about any other spacial data. Likewise Locator can be configured to just display just a simple static map with one highlighted pin (no search box or list of locations). Locator is a highly configurable map stack which offers excellent value for money.
A visitor to your website starts a location search, by entering a town name or other location in the search box. Or you can enable auto-geolocation (if your website has SSL support). When a location search is run, the location from the user is geocoded and compared to locations in your database. The locations are shown visually on a Google Map (with map pins) and the details of the locations are also shown (closest first) as an interactive list. Clicking pins or location items brings the details of that pin into view.
Example
Here is a working example of Locator, with all the default options applied.Setup
Follow these setup instructions carefully for adding Locator to your website. Please note that Stacks 3.5 or later is required.- Once installed into Stacks / RapidWeaver, open the Stacks Library and search for 'locator'
- Drag and drop a copy of the stack into your webpage
- In the stack settings provide your Google Maps API key. If you don't know what one of these is, read the chapter below
- Choose the data type and source, for your locations. Locator supports exported Google Earth KML files or a manually coded database of locations in either XML or JSON formats. Please read the details below carefully, regarding data formats available to use
- Customise any of the other stack settings, like styles or localisations
- Preview your webpage in RapidWeaver. Test the search box to make sure the map and locations are shown.
Locator contains complex Javascript code that needs to be loaded in a specific order. Therefore we advise against using Locator on complicated webpages that feature lots of sliding, toggle or parallax features. Locator may conflict with some other stacks, so please make use of the free demo provided. Only a single locator stack can be used per-page.
Support policy: We are happy to answer basic, general questions about the stack and discuss things like simple CSS modifications. We cannot provide detailed one-to-one support with either getting an API key from Google setup or generating your database of locations. These latter tasks are outside of our normal free support remit, and therefore billable by the hour. You can get in contact via the support page, to discuss your requirements.
Locator comprises of a very long list of customisable options. Don't be put-off by how complicated the stack looks; many of the settings can be ignored for basic use. As always, hovering your mouse over individual settings will display an informational tooltip. These tooltips contain useful information.
Data formats
Locator needs a simple database of locations, that it can pin onto the map and display the closest locations in a list. We currently give you the option of three data file formats; these being KML, XML or JSON formats.KML
By far the easiest way to create your database of locations file is in Google Earth (this is a free download). Within Google Earth, create a new folder (Add > Folder) and add pins. You'll find that you can drag these pins around on the map. Each pin can be assigned information and simple HTML markup. HTML tags like
<br> can be used to line-break longer addresses or other info. Once done, select the new folder in the Places sidebar containing your pins, click File > Save > Save Places, and export the file in KML format. Add the KML file to your RapidWeaver project (as a resource) or publish it to your web server. In the Locator settings, link to your generated KML file. KML requires no complicated coding. As discussed above, basic HTML might be needed to improve the appearance of pin information. KML also carries the benefit of letting you re-open files at a later time (in Google Earth) to edit them again. Google Earth is widely available for different operating systems, as a free download. Many tutorials exist for Google Earth if you have not used it before. You can download a sample KML locations file here (right-click and 'save as' if the link does not work in your browser).XML
We actually recommend XML as the preferred format, because it offers a 'structured' template to supply Locator all the required information it needs. Through using XML, you will be able to make use of features like directions. XML files are surprisingly easy to open in any code editor and work with. You can clearly see all the data for each location. It really isn't much more difficult than editing a spreadsheet! Latitude and longitude coordinates can be extrapolated from Google Earth (moving your mouse cursor over a map displays the coordinates in the status bar). Within titles or descriptions, replace any special characters (like ampersands) with HTML entity equivalents. Once done with your editing, the XML file can be saved. Attach your XML file as a resource in RapidWeaver or upload it to the web server and link to it from there. You can download a sample XML locations file here (right-click and 'save as' if the link does not work in your browser).
JSON
The third and final option for data is JSON format. If you have previously built a store locator for Wordpress or a similar platform, then your data was probably saved into a MySQL database table. Often the only way to export that data is in JSON format. Therefore this data format provides a useful ability to reuse store location data you may have previously created for another platform or addon. You can download a sample JSON locations file here (right-click and 'save as' if the link does not work in your browser).
Generating your Google Maps API key
An API key needs to be registered with Google, before you to use Locator on your website. The Google website has the most up-to-date information available on generating API keys, so please refer to this link: https://developers.google.com/maps/documentation/javascript/get-api-key#keyThe API key supplied with Locator is fine to use for quick, casual testing. But this key is prone to being cancelled or changed at any time (without warning). So you really must register your own API key, if you intend to use the stack in your website.
It is recommended that you signup for email notifications, so that Google can send you any important notifications or give you advanced notice of any possible future changes to your API keys. API key generation can sometimes take a couple of minutes, so please be patient and keep the browser window open! Other than needing the Geocode API, normally the API key Google generates does not need any other 'credentials' or 'permissions' applied to it. Locator is quite clever, in that it can talk-back to Google servers to request anything further it needs.
Give your API key a distinct name like 'My Locator Stack'. Make a note of the API key (it will look like a random string of letters and numbers). If you anticipate that your store locator is going to be very popular, carefully review the API usage. In extreme circumstances, you may need to purchase additional allowances.
