My Maps location documentation

Introduction

Let your users search for locations and configure the display as you want. My maps location is simply the most advanced Google Maps integration for Joomla.

Main features:

  • Search for locations you've created
  • Auto geolocation
  • Map source can be Google Maps, Bing maps or Mapbox
  • Add map design
  • Get information from Google places
  • Import/Export/Sync locations from .csv file
  • Frontend location submission
  • A lot of 3rd party extension integrations

I. MY MAPS LOCATION INSTALL & UPDATE

1.1 Install

Our component is Joomla 3.x compatible. All the features and 3rd party integrations are included in all memberships.
In order to install our component you have to download the extension .zip file and use standard Joomla installer.

Then click on Browse > Upload and Install button, component, modules and plugins will be installed activated by default.

1.2 Update & automatic updater

In order to update My Maps location you can install a new version over the old one by downloading the ZIP file from JoomUnited or use the automatic updater (recommended).

 

The automatic updater, which push the update notification, is embedded in the Joomla extension you've installed. So you'll get notified like any other extension in the dashboard or using the menu: Extension > Manage > Update menu.

 

Login to your account to update

You need to login to your JoomUnited account to update all your JoomUnited Joomla extensions. In order to login access the main configuration of the component then click on the Live update tab. At the bottom, you'll find a login button. 

Enter your JoomUnited credentials, the same you use to login here @ www.joomunited.com

 

The button will turn orange, congrats! you can now update all the JoomUnited extensions on this website! If your membership is expired you'll get a renew link and a text that explain that.

Note: one single login will allow you to update all the JoomUnited extensions (regarding your membership). Login won't expire unless you disconnect it.

II. LOCATIONS AND CATEGORIES

2.1 Get a Google Maps API key

Each time you use the Google Maps APIs, if you domain has been created after June 22 2016, you must include a key, to validate your request.
Get a key and enable API: https://developers.google.com/maps/documentation/javascript/get-api-key

More information: https://developers.google.com/maps/documentation/javascript/usage?hl=en

The first step is to cretae a project and 

Then type the name of the project. If i want to allow all requests from mydomain, then the pattern to follow is *.joomunited.com/*
If you want to just allow single domain for example mydomain.com then pattern would be joomunited.com/*


On a localhost environment, you can put any valid key and it will work without any domain referring.


The API key is generated then, this is the key you need to copy to add to My Maps location.

Add the key to My Maps Location.

From the Components > My Maps Location > Option view, you can add a key in the configuration.

 

Paste the key.

 

Step by step resumé:


So the steps i follow are

  • Go to the Google API Console
  • Create or select a project
  • Click on Continue to enable the API and any related services
  • On the Credentials page, get a Browser key (and set the API Credentials)
  • To prevent quota theft, secure your API key following those best practices

2.2 Manage categories of location

Location are classified in categories. Those categories can be displayed as filter in frontend or used as a predefined parameter in a menu item to load some categorized locations.
 

 

If you have a lot of locations, it's recommended to use categories. You can create categories and sub categories.
To create a category, please go in My Maps location > Category and click on New


 

Then from the category screen you'll need to add a title and a parent category in case you want to create a subcategory

You can also define a default marker for location in the ctaegory using the tab Marker selection

 

Note: a category is created by default named "My category" allowing you to start adding locations directly after install

2.3 Create a location

In order to create a location, please go in My Maps location > Location > New

There is 3 mandatory fields:

  • Name of the location
  • Category of the location
  • Location (address)      

 

For the address you got 3 solution to add it:

  • Use the search field (recommended)
  • Navigate onto the map and use the cursor to point a location
  • Fill an address (must be Google Maps valid)

 

To add a location with the search engine, type the name of the place you want to add.

 

On selection, the latitude and longitude fields will be filled automatically. My maps is also integrated with Google places! It means you can search for a shop or anything else that is registered on Google Maps, our component will get all the place information.

 

 

 

You can also move on the map and put a marker directly, the result will be the same and you’ll get a latitude and a longitude automatically filled.

 

Be careful with the address field and zip code if you fill it manually, it must match with a Google Maps known address.

 

All other information of the location (description, hours,...) are displayed in the detailed view of the location.

The contact link in the location detail edition, is the possibility to add a contact link, mailto or URL per location. On frontend it will a contact button that will open the URL or execute the mailto action.

2.4 Other location information

On each location you can add an image and a marker. 

  • Image will be displayed as a thumbnail in the tooltip of the location and at a bigger size on the location detail page. 
  • Markers will be displayed on the map as location marker icon. You also got some nice marker sets for your locations included in My Maps Location extension

 

 

My Maps location is using the Joomla native multilingual feature. You can define a language in categories of location and in locations. On language switch, locations will be filtered like any other Joomla content in order to display the language approved content.

The location description field is one of the most important.
It will be displayed on the location detail page and, depending on the theme, as an intro text of the location in search results. More important, the description is a WYSIWYG editor with all the plugin loaded inside, it means that you can anything you want in it (images, videos...).

 

Here's the intro text displayed in location search results.

 

The tag field is the same tag system as Joomla. You can add tags and sub-tags then load it in frontend as filter. To manage all the tags, just load the Joomla tag component: Menu Component > Tags
On frontend, depending of the configuration, tags can be displayed as checkbox (like bellow) or as a dropdown list.

 

My Maps Location got additional fields to fill meta information (for search engines). This fields are loaded on the location detail page.

2.5 Display locations on frontend

In order to display your locations on frontend you can use:

  • A menu to display location search engine, single location or category of locations
  • A module to display a search field or select a set of locations
  • An editor button to display single or multiple locations in any editor

Load locations from a menu

From the Joomla menu manager, add an element  and select as type “Location search and display”. It will display the location search engine with filters. 
Select “Location detail view” to display a single predefined location.

 

If you select “Location search and display” you have some display parameters. Some may override default component parameters.

 

From the main tab of the menu you can setup:

  • Enter address: you can force a default address to be displayed on page load. It can be left empty
  • Distance: the distance to lock search, referring the address above. It can be left as -1 (default)
  • Category: load a specific category of location
  • Search limit: limit the number of search results. 10 will only return the 10 first results on location search
  • Ordering: order search results by Date, Title, Distance (default)

 

Then on the My Maps Location menu tab, you can setup:

  • Component selection: My Maps Location or all 3rd party integration like K2, Jomsocial...
  • Component layout: select between one the 3 themes, default, full width and sidebar
  • Map type: select Google Maps, Bing Maps or Mapbox to style your Maps
  • Designs: depending of the map source you have several map design and colors
  • Auto geocode popup: load automatically location tooltip after location search
  • Map zoom: define a default zoom level on the map
  • Map and search results width and height options

 

Frontend display based on theme

 

Result for a single location search display:


Display locations using a module

My maps location comes with 2 modules for native locations + other for 3rd party integration (like a module to display K2 item locations)

The Map module allows you to display your locations with the same filters as the menu but in a module position. You can select a set of locations or select location categories.

 

My Maps Location – Search module will display a search engine with some filters as option like the map width or the component in witch the location will be searched (search for K2 location only for axample).

 

Display module on frontend:

 

 

Display locations using a editor button


The editor button will be loaded in your Joomla editor (usually in articles or HTML custom modules). You’ll see the button at the bottom of your editor.
On click you’ll see a lightbox that allows you to select one or several locations you’ve added before.

 

Then you can select one or some location and push the button to add it in your article. If you don’t specify any zoom level, it will be automatically loaded to fit you location area.
The tag code you’ll see in your WYSIWYG editor will be like this model: {mymaplocations mapid width height}

Ex. {mymaplocations 1 400 400} this code will display a map with the location ID=1 and with 400px width an height

 

III. FRONTEND LOCATION SUBMISSION

3.1 Add and manage locations

My maps location offers the option to submit and manage your own locations from frontend. First you'll need to create a menu that allows frontend submission.

From the Joomla menu manager, add an element  and select as type “Add locations”. Then by clicking on it users will be redirected, after login, to a location submission form.
The menu "My locations" allows user to edit their previously submitted locations.

 

Frontend menu form overview:

 

3.2 Access limitation

The frontend submission and edition process is controlled by Joomla ACL. To edit who's is allowed to submit and edit location, click on Components > My Maps Location > Options > Permissions.
From there you can control witch Joomla user group is able to:

  • Create locations
  • Delete locations
  • Edit locations
  • Edit state of publication
  • Edit own locations

 

IV. IMPORT - EXPORT LOCATIONS

My Maps location got an Import - Export - Synchronization tool for location from a .csv or .kml file (Google Earth file). Click on the menu My Maps Location > Import/Export to get access to the interface.

 

From this interface you can:

  • Import locations from a .csv or .kml file
  • Export locations from a .csv or .kml file
  • Make an update (synchronization) of the locations from a .csv or .kml file

 

Note: the sync button also works when you've added location directly in the database

 

V. PARAMETERS

5.1 Settings

The component has a lot of options, some may be override in the menu view as we've seen before. Click on the menu: My Maps Location > Options to get access to the interface (top right of the screen)

Tab1: General configuration

Parameters1

  • Unit of distance: Miles or Kilometers
  • Map type: choose between Google maps, Microsoft Bing maps or Mapbox
  • Each time you use the Google Maps APIs, if you domain has been created after June 22 2016, you must include a key, to validate your request. 
    More information: https://developers.google.com/maps/documentation/javascript/usage?hl=en
    Get a key: https://developers.google.com/maps/documentation/javascript/get-api-key
  • Map design: Map type (satellite, plan…)
  • Scroll map: Enable the zoom in/zoom out using the mouse when you're hover the map
  • Marker tooltip open: open tooltip on marker hover or click
  • Auto zoom: automatically adjust the zoom to display all the markers of the map
  • Bing Maps type: map type (satellite, plan…)
  • Bing maps API key: put an API key to make it works ;)
  • Mapbox API: put the Mapbox API key to make it works
  • Mapbox Map ID: put the Mapbox Map ID to select the map created in mapbox

Parameters2

 

  • Anywhere search: add the option in the radius search  to search anywhere on the world
  • Search anywhere by default: by default, the radius selector in the search view will be set to Anywhere
  • Tag format: display the tag filters as checkbox or dropdown list
  • Route format: display the route on My Maps location or redirect to Google
  • Contact link: display the contact link
  • Contact button: display the contact button
  • Map size: map and search results width and height
  • Distance: determine the values of the radius search dropdown list
    Ex. User can choose to search 10 miles around New-York city.
  • Distance select list: display the radius search in the search view

 

 

  • Word counter: crop the location description at a certain amount of word in search results
  • JQuery sidebar: change the default sidebar to a JQuery one (smaller and smooth scroll effect)
  • Color for OR button: “OR” button color on default theme
  • Button color: "Geolocate me" button color on default theme
  • Marker text color: Color of the text above the marker
  • Background image: image in the background of the search on default theme
  • You marker: add you position on the map and select an image as marker

5.2 Bing as map source

To use Bing Maps from Microsoft as map source you need to fill an API key in the global configuration of My Maps location. The Bing page is here: https://www.bingmapsportal.com/

 

You need to create a free account from here and copy the API key code from your account.

 

Then you'll be able to use Bing map as map source from the global configuration (to enable it as default) or from the menu item.

5.3 Mapbox as map source

To use Mapbox, the custom mapping platform for developers, as map source you need to fill a Mapbox API and Mapbox ID in the global configuration of My Maps location.
The Mapbox home page is here, you need to create a free account from there: https://www.mapbox.com/

 

From there you can create some new page design and store it on your account.

To get your credentials use the menu Account (bottom right):

  • Mapbox ID: it's your User ID
  • Mapbox API: use the menu Account > API and Access tokens

So you get one key per map style you've created.

Then just copy it in My Maps location configuration to use it.