line_graphic_business_20

MANUAL & DOCUMENTATION

HOW TO USE THIS PLUGIN

Welcome

Thank you!

Thank you for purchasing a license of “Google Maps PLUS for Visual Composer”.

We are hoping that this little add-on for Visual Composer will prove valuable to you and allowing you to use Google Maps to their fullest potential. Please read this manual for more information about how to install, activate and use the plugin.

acknowledgements_01

Information

This plugin includes standalone elements, allowing you to easily create advanced Google Maps, using the popular “Visual Composer – Page Builder” plugin.

The same elements that are part of this plugin can also be found in our large-scale add-on bundle, “Composium – Visual Composer Extensions Addon”. If you also use “Composium – Visual Composer Extensions Addon”, you should disable this plugin, as it will provide the exact same elements.

If this plugin detects an active installation of “Composium – Visual Composer Extensions Addon”, it will automatically prevent itself from loading any elements or files, in order to prevent conflicts with “Composium – Visual Composer Extensions Addon”.

This manual covers two plugins, that both contain the same Google maps elements (“Google Maps PLUS for Visual Composer” and “Composium – Visual Composer Extensions Addon”).

Due to different update cycles, either one of those plugins might (temporarily) still miss some of the features detailed in this manual. If that is the case, an update for that plugin is either already pending, or will be released shortly, in order to bring the map elements in both plugins to the same release level.

Installation

Plugin Installation

Please install the plugin like you would install any other plugin in WordPress. You can either upload the extracted plugin directory directly to you server using any FTP program, or use the WordPress Plugin Installation routine.

Standard WordPress Routine:

1. In your WordPress Admin panel, click on “Plugins” -> “Add New”

2. Click on “Upload”

3. Click on “Browse” and navigate to the folder on your harddrive where the plugin file (ZIP version; the file as downloaded directly from CodeCanyon) is located. Select the plugin file and click on “Open” in your popup window.

4. Click on “Install Now”

5. Wait until WordPress finishes the upload and installation process.

6. Click on “Activate Now”

Manual Upload via FTP:

1. Extract the ZIP file you received from CodeCanyon. The file should include a folder named “ts-googlemaps-for-vc”

2. Using any FTP program, navigate to your WordPress installation and find the folder “wp-content”. Open that folder and (inside) find the folder “plugins”. Now open that folder and you should see a listing of all currently installed plugins for your WordPress installation.

3. Upload the complete plugin folder you extracted in step 1 into the “plugins” folder you just navigated to via FTP. Ensure, that the plugin folder is uploaded directly into the “wp-content/plugins” folder and not accidentally into one of the existing folders for one of the existing plugins.

4. Once the upload is finished, log into your WordPress admin section and go to the plugins section. You should now see “Google Maps PLUS for Visual Composer” listed as available plugin. All that is left is to activate it.

If you have problems installing the plugin, follow the step by step instructions you can find here.

If you have followed all these steps correctly, and your system passed the memory check, the plugin should now be installed and functional.

CONGRATULATIONS, because you are done with the installation!

Error Messages

Depending upon your individual WordPress setup and internal size limits, you might encounter some problems/errors when attempting to install or activate the plugin.

Upload / Post Size Limits

When using the standard WordPress routine, please ensure that your WordPress upload and post size limits are large enough in order to accommodate the size of the plugin file. Otherwise, you will have to upload the plugin via FTP or to increase the restricting limits first.

Are you sure you want to do this?

If during the standard install routine you encounter a white page or a message asking you “Are you sure you want to do this?”, your upload / post size limits are most likely not sufficient for the file size and you should opt for the FTP method.

In order to increase upload and post size limits for WordPress, you need to change some key system files, which allow you to set a custom upload value. Please follow the instructions provided in this article:

http://www.wpbeginner.com/wp-tutorials/how-to-increase-the-maximum-file-upload-size-in-wordpress/

Any basic Google search will also provide you with more detailed information. In general, you need to add the following lines to your php.ini file:

upload_max_filesize = 32M
post_max_size = 32M

Error Message after attempting to activate Plugin:

When activating the plugin, it will conduct a basic memory check in order to ensure that your system is having sufficient memory left to actually handle the plugin and all of its elements and features. If that check determines that there is NOT sufficient memory, it will prevent the plugin from getting activated.

That is done in order to prevent any WordPress crashes due to memory overflows, which would otherwise result in the so-called “White Screen of Death”. In that case, a critical error message (see below) will be shown instead, asking you to contact our support for further assistance. Of course, increasing your PHP server memory will fix the problem. There is a section dedicated to that process further down on this page.

Insufficient Memory Warning

Unfortunately, and to prevent a potential system crash, the plugin “Google Maps PLUS for Visual Composer” could not be activated. It seems your available PHP memory is already close to exhaustion and so there is not enough left for this plugin.

Composer Elements

After you activated the plugin, you might have to enable those newly created Composer Elements in the Visual Composer Settings (that is, the settings for the actual Visual Composer Plugin) as well. You can find the Visual Composer Settings in your WordPress admin menu under “Settings” -> “Visual Composer”, or as main menu item “Visual Composer” (starting at v4.6.0). That step is necessary if you utilize the user rights manager from Visual Composer itself, which allows you to enable/disable elements for specific user groups.

Once in the Visual Composer settings, you need to stay in the “General Settings” tab and navigate to the section called “Role Manager”. There you can enable or disable each available Composer element for each available user role. After you made your changes, don’t forget to click on the “Save Changes” button at the bottom of the page.

General Usage

Map Elements

After installation and activation of the plugin, you will find two new (different) map elements in Visual Composer.

The “TS Google Maps SINGLE” element should be used if your map requires only one (single) marker and no overlays. All settings, including marker information, are contained in this single map element. Some advanced features such as filtering are not available, as those are not relevant if there is just one marker.

The “TS Google Maps PLUS” element should be used for complex maps with multiple markers and/or overlays, or if you want to import markers via external JSON file.

This element is a so-called “container element”, which means the actual markers or overlays will be added via sub (or child) elements, using the various “plus” icons in the container element, which in turn will open the Visual Composer element selection panel.

The element selection panel will be limited to two elements …

  • TS Google Maps Marker
  • TS Google Maps Overlay

… which are used to add the actual marker or overlay information to the map.

If you want to import markers via JSON file, you will find a setting option to provide the path to where the JSON file is stored, so the map can then load and process the JSON file every time the map is rendering.

Marker Import via JSON File

While the main way to add markers to a map is to use the provided marker child element for the map, it is also possible to import markers via a dedicated JSON file, which will define the core information for each marker. The option to do so will only be available when using the “TS Google Maps PLUS” element.

The JSON file will be imported to the map whenever the map renders on the frontend. As such, you need to ensure that the file is hosted on a server that can be remotely accessed by the map.

In order to use a JSON file, you must ensure that the JSON file is created following a specific syntax and structure, and the underlying script that will read and process the file expects said syntax and structure.

The map will render much faster, when you provide marker locations via coordinates, rather than using an address. The reason for that is that each address has to be converted to coordinates first (“geocoding”), before a marker can be created.

The Google Maps API imposes limits as to how many geocoding requests can be sent and processed at any given time, and also how many such requests can be sent in a 24 hour period.

By default, the script will use a delay of 200ms between each request (can be adjusted in the map settings), in order to avoid too many requests at once, so processing 4 marker addresses will take at least one second … meaning, the more marker addresses you provide, the longer it will take the map to render them all.

It is therefore highly recommended, to use marker coordinates whenever possible.

The following is a sample for the required JSON file, also including some notes about which information are required for a marker. In general, in order for the map to create a marker, you need to define a marker title, and the marker location. The location can either be defined by providing latitude and longitude coordinates, or by providing the postal address for the marker.

You will find a JSON file template and sample file in the plugin’s “json” sub-folder.

/*
 * For performance reasons, you should provide all marker locations via GPS coordinates (latitude / longitude), instead of using postal addresses.
 *
 * Coordinates can be used by the map immediately, while addresses have to be geocoded first, in order to obtain the matching coordinates.
 *
 * Google imposes limits as to how many geocode requests can be sent at a time and also sets a daily limit. So use addresses, if necessary, only for few markers.
 *
 * Do NOT change the Callback Name "GoogleMapsPlusMarkerImport" as it is required!
 *
 * The following parameter are required for each marker: 'title' AND 'latitude' + 'longitude' (if using coordinates) or 'address'
*/

GoogleMapsPlusMarkerImport(
	{
		'markers':
		[
            /*
            {
                // Marker Title / Name
                'title':                '',                         // required!
                // Optional Marker Group Names (separate multiple by "|")
                'group':                '',
                // Marker Location: Latitude
                'latitude':             '',                         // required! (or 'address')
                // Marker Location: Longitude
                'longitude':            '',                         // required! (or 'address')
                // Marker Location: Address
                'address':              '',                         // required! (or 'latitude' + 'longitude')
                // Full Path to Marker Image
                'icon':                 '',
                // If not provided, global map settings value will be used instead
                'icon_width':			     32,
                'icon_height':			    32,
                // InfoWindow Content (Basic HTML Code can be used for styling)
                'content':              '',
                // InfoWindow Position Offset (in Relation to Marker)
                'offset':				       0,
                // Allow Automatic Streetview
                'streetview':            false,
                // Show Directions Button + Text
                'directions_show':       false,
                'directions_text':      'Get Directions',
                // Show Google Map Button + Text
                'googlemap_show':       false,
                'googlemap_text':       'View on Google Maps',
                // Show other Link Button + Link + Text
                'other_show':            false,
                'other_url':            '',
                'other_text':           'Learn More!',
            },
            */
            {
                'title':                'Brandenburg Gate',
                'group':                'Sights',
                'latitude':             '52.51626004',
                'longitude':            '13.3774209',
                'address':              '',
                'icon':                 '',
                'content':              '',
                'streetview':           false,
                'directions_show':      true,
                'directions_text':      'Get Directions',
                'googlemap_show':       true,
                'googlemap_text':       'View on Google Maps',
                'other_show':           true,
                'other_url':            'https://en.wikipedia.org/wiki/Brandenburg_Gate',
                'other_text':           'Learn More!',
            },
            {
                'title':                'Berlin Victory Column',
                'latitude':             '52.5143405',
                'longitude':            '13.34984779',
            },
		],
	}
);

Map Overlays

Aside from normal map markers, the plugin also allows you to add so-called overlays (or shapes) to your map. The option to add an overlay will only be available when using the “TS Google Maps PLUS” element. Once you added a “TS Google Maps PLUS” element on you page, you will notice that it is a so called “container element” which allows you to add sub (or child) elements to it.

In order to add an overlay, you need to select the “TS Google Maps Overlay” child element, using the various “plus” icons within the container element, which in turn will open the element selector panel in Visual Composer.

Each overlay (shape) can also have an infowindow assigned to it, which will be opened when a viewer clicks anywhere on the overlay (shape).

In order to add a circle shape to your map, you require one coordinate set (latitude/longitude), representing the center of the circle on your map, as well as the map radius, which can be expressed either in miles, kilometers, feet or meters.

You can also define the circle fill color, as well as the circle border color and border strength.

In order to add a rectangle shape to your map, you require two sets of coordinates, each set consisting of latitude and longitude value.

The first set represents the top left corner of the rectangle, or the north-west position on your map.

The second set represents the bottom right corner of the rectangle, or the south-east position on your map.

You can also define the fill color for the rectangle, as well as the border color and border strength.

A polyline shape can be as simple as a straight line on your map, which requires to sets of coordinates, each coordinate set consisting of latitude and longitude values.

The first set in a straight line represents the starting point of the line, while the second set simply represents the end point of the line.

You can define the line color and line strength.

The more your line is supposed to reflect an actual outline on your map, for example, following the exact direction of a road or highway, the more coordinate sets are required, that reflect the actual turns the road or highway is taking.

When entering multiple coordinate sets, ensure that the coordinate sets are entered in the right order, beginning with the start point of the line, and then working your way towards the end point of the line.

A polygon is a irregular shape on the map, and can be used to highlight map sections like parks or any other area that can not be represented with a basic circle of rectangle.

The more a polygon is supposed to reflect an area on the map, the more coordinate sets are required, each coordinate set consisting of latitude and longitude values.

When entering the coordinate sets, ensure that they remain in order. It is usually recommend to start the coordinate sets at the most top right position of your shape, and with all subsequent coordinate sets to work your way in clockwise direction, until you eventually end up right next the first coordinate set.

You can define the fill color for the polygon, as well as the border color and border strength.

External Triggers

Starting with v2.0.0 of “Google Maps PLUS for Visual Composer” and v5.0.5 of “Composium – Visual Composer Extensions Addon”, it is possible to control some map features externally, using links/triggers with a specific syntax to cause the map to go to a specific marker or overlay.

For the map to recognize and process those external triggers correctly, the trigger element requires certain attributes and a specific class name.

You also need to provide an unique name to the map element itself, as well as to the markers/overlays you want to trigger externally. You will find appropriate input options in the element settings panels for the map container, the marker element, as well as the overlay element.

In the map container element, you also need to enable the option “Location: Allow External Triggers”, which can be found in the settings tab named “Map Features”.

Trigger HTML Markup Requirements

Your custom trigger element can really be anything on the page that you can assign a specific class name and some data attributes to. The following are the required information for an external trigger to be recognized and processed correctly:

Attribute “class”:

ts-advanced-google-map-external

You can use any other additional class names for the trigger element (for example, for styling purposes), but the external trigger must carry the class name “ts-advanced-google-map-external” to be recognized and processed by the plugin.

Attribute “data-map”:

This attribute contains the unique ID/name you assigned to the map itself, so the plugin will now, which map the marker or overlay is contained in.

Attribute “data-id”:

This attribute contains the unique ID/name you assigned to the marker or overlay, and is used to find the correct marker or overlay within the map.

Attribute “data-style”:

This attribute defined whether the trigger is affecting a marker on the map, or an overlay. Possible values are therefore limited to “marker” or “overlay”

Attribute “data-type”:

This attribute is either set to “marker” for all triggers affecting map markers, or it defines the type of overlay, the trigger is meant to control (“circle”, “rectangle”, “polyline” or “polygon”).

External Marker Trigger:
<div class="ts-advanced-google-map-external" data-map="MyCustomGoogleMap" data-id="BrandenburgGateMarker" data-style="marker" data-type="marker">Show Marker</div>

data-map=”MyCustomGoogleMap”

data-id=”BrandenburgGateMarker”

data-style=”marker”

data-type=”marker”

For map markers, the “data-style” and “data-type” attributes are always set with the value “marker”, as there is no differentiation in marker types.

External Overlay Trigger:
<div class="ts-advanced-google-map-external" data-map="MyCustomGoogleMap" data-id="MyCircleOverlay" data-style="overlay" data-type="circle">Show Overlay</div>

data-map=”MyCustomGoogleMap”

data-id=”MyCircleOverlay”

data-style=”overlay”

data-type=”circle”

For overlays, the “data-type” attribute must be set according to the type of overlay this particular external trigger is supposed to affect. Available options are “polyline”, “polygon”, “circle” or “rectangle”.

Address vs. Coordinates

When adding a marker to any map, you can provide the marker location either by its official postal address, or via its corresponding latitude/longitude coordinates. The plugin can handle the map location either way, but it is highly recommended to provide marker locations via its geographic coordinates, whenever possible..

Benefits of Coordinates

In geography, any location on this planet is assigned an unique combination of longitude and latitude coordinates, which immediately identify that location. On top of that, a 3rd coordinate is provided, representing the locations elevation level, which is only relevant for 3D representations of maps.

For the purpose of a Google map, the longitude and latitude coordinates are always required in order to place a marker on a map. If you provided the location via an arbitrary postal address instead, created by some local municipality/government, the plugin needs to convert that address into a coordinate set first, by requesting said coordinates from Google.

That process is not always precise and takes time, as such a request is sent for every address based marker on your map, and processed one after another, with a delay between each process. The delay is required since he Google API only allows for a limited number of simultaneous requests to be sent.

So, the more address based markers your map includes, the longer the overall process of converting the addresses into coordinates will take, adding a potentially significant waiting time for your website users, until the map is fully rendered and all marker have been added.

But if you provide all markers with their coordinates directly, the plugin can add those marker to the map immediately, without having to contact the Google Maps API for each marker first.

Find Coordinates

There are many online portals available, that can convert postal addresses into coordinates for you, but this plugin has you covered already.

Using the “TS Google Maps PLUS” element, you are able to set the map into a so-called “Listener” mode, which generated a Google Map for you, that can be used to easily find coordinates to any address.

Below, you find an example of such a specialized map. Please note, that some advanced map features are not available for maps in “Listener Mode”, and the “Listener Mode” will also be automatically disabled on mobile devices.

Simply enter the postal address of the location you require coordinates for, and the map will retrieve that information from Google for you, and place a corresponding marker onto the map, Clicking on the marker will open an info window, which will provide you with the desired coordinates.

Mouse Position:N/A Map Center:N/A
Mouse Tile:N/AMap NE:N/A
Mouse Pixels:N/AMap SW:N/A
Mouse Click Coordinates:N/AMap Zoom:N/A
Mouse Click Address (Approximated):N/A

Usage in Other Content Elements

It is NOT recommended to use the map elements within other content elements, such as tabs, tours or accordions, as maps embedded in any section that are initially not visible on the page are unable to correctly determine and set their dimensions, which are required by the Google Maps API to correctly render the map.

The maps created through this plugin make extended usage of the Google Maps API, which requires exact dimensions for the map to be available, in order to correctly render the map and its contents.

When using a map element within another content element, such as tabs, tours or accordions, the map might not be able to determine its dimensions correctly anymore, if it is shown in a section that is not (yet) visible upon page load.

Most tabs/tour/accordion (or similar) elements work by either using “display: none;” rules for all sections that are initially hidden, or by assigning a width and height of 0px (zero) to those sections, which effectively hides them too. Either way, when the map is attempting to determine its dimensions on the page, it will in those cases also return a width and height of 0px, which prevents the Google Maps API to correctly calculate the size of the individual map tiles that make up the map. As a result, the map can appear blank, with only the controls showing.

For more advanced tabs/tour/accordion elements, that “hide” sections not by “display” rules or “0” (zero) size settings, but rather utilize absolute/fixed positioning outside the visible screen area, the map elements should work correctly, as sections “hidden” that way still carry their correct dimensions, even if they are not visible on the screen anymore.

Google Map API

Google Maps API Key

Starting around June 2016, Google is now requiring all websites using the Maps API to identify themselves with an API key. If no API key is provided, an error message might either appear in the browser console, or via popup on the screen.

Obtaining an API key is free for most users, unless you site is viewed by a REALLy large number of visitors, at which point Google will charge you for any additional API uses.

You can learn more about API keys here:

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

Once you obtained an API key, you need to enter that key in the plugin settings page, so the plugin can use the key whenever it is loading the API from Google.

Load Google Maps API

In order to generate the map, the plugin will load the official Google Maps API script. Sometimes, your theme or another plugin is already loading the API file, causing a warning in the browser console:

Warning: you have included the Google Maps API multiple times on this page. This may cause unexpected errors.

… or a popup on the screen, stating the following:

Oops! Something went wrong.

This page didn’t load Google Maps correctly. See the JavaScript console for technical details.

While there are usually no adverse effects on the map(s) generated by this plugin, potential conflicts can not always be avoided, plus, you are loading the same file twice (or even more often than that).

In order to avoid any such conflicts, each map has a settings option, allowing you to prevent the map from loading the Google Maps API. When using that option, ensure that your theme or another plugin is in fact loading the API already on that particular page or post, as the map will not work without it.

When embedding multiple maps from this plugin on the same page or post, this plugin will load the Google Maps API file only once, as it is using the appropriate “wp_enqueue_script()” routine from WordPress, which can detect that the plugin is attempting to load the same file for each map again, so there is no need to disable that option in the map settings.

But that will only work for any file load attempts from this plugin, but not for other plugins or your theme, as this plugin can’t control what other parts of your website do.

Top