menu

Manual

Gocha GEO is a plugin that lets you use the geolocation data in many ways – thanks to three different modes it can provide various behaviours connected with map.

Install

  • Open your WordPress admin.
  • On left menu choose: Plugins -> Add New.
  • On upper menu choose: Upload.
  • Choose file: gocha-geo-plugin.zip.
  • Click: install now.
  • Wait for the server to load the package.
  • And click Activate Plugin.
  • You will see Gocha GEO on your plugin list.
  • Done

On left menu choose: Tools -> GOCHA Geo.

EXEMPLARY USAGE

Gocha GEO is a plugin that lets you use the geolocation data in many ways – thanks to three different modes it can provide various behaviours connected with map.

Simple mode

Simple mode is particularly useful for showing localization of photos implemented into a post, while the photos are not directly connected between each other.

Of course, it is possible to display a map of all photos from a post, but it is not necessary – instead of this, the map can be displayed as a popup after moving the mouse over the photo and clicking an appropriate icon that opens the map.

This mode can be also utilized to display connections between photos in form of a route between localizations where the photos have been taken.

Gallery mode

In Gallery mode there are mostly photos that have connections between each other (however, it is not a must) – thanks to a showcase of photos along with a map containing localization connected with the photo, this mode is best for:

  • showing routes of trips
  • creating short photo journals from trips
  • presenting interesting places in given regions
  • creating interactive lists of recommended cafes, restaurants etc.
  • creating event calendars connected with specific places

It is worth remembering that Gallery mode is capable of connecting with chosen photos or posts.

Advanced mode

Advanced mode allows to display a collection of posts with geolocation data on map, along with listing of the posts below the map (optional).
Using this mode, it is possible to display:

  • list of company offices
  • localization of planned events throughout the country
  • list of visited places with links to larger descriptions

Thanks to connecting with posts, Advanced mode is perfect for creating a page that is grouping posts for geolocation.

Settings

Basic settings can be found in Settings tab of WP Dashboard and are mostly connected with global settings of the plugin.

API Settings

Google Maps API Key – here, the Google Maps API key is entered, whole procedure of acquiring the key is described here.

Google Static Maps API Key – here, the key for Static Maps PI is entered – it is used to show graphics with post location in metabox of post editor. Procedure of acquiring the key is described here.

Disable Google Maps API script for front-end – this options allows to turn off the scripts loaded by the plugin in front-end. It is useful when we use different plugin that loads Google Maps API scripts and does not allow for turning them off.

Disable Google Maps API script for Dashboard – option that has the same features as the previous one, but is applied for the cockpit.

Modes

Disable simple mode on all pages EXCLUDING these ones – intuitive feature allowing to enable the Simple mode only on the specified page ID. Good if you don’t want to have the plugin enabled on every picture automatically.

Use simple mode – allows to turn on/off Simple mode.

Use gallery mode – allows to turn on/off Gallery mode.

Use advanced mode – allows to turn on/off Advanced mode.

If all above options are turned off, the button to add shortcodes in post editor will be disabled as well.

Processing

Media library – allows to turn on/off displaying of additional media filtering field in media library.

Find images by URL – allows to turn on the detection of images in post content that do not have defined class with wp-image prefix – CAUTION! This option can affect performance of the website.

Skip featured images – allows to turn off considering featured images when choosing pictures to display in Simple mode.

How many images process at once – this option has the biggest impact for the performance of image processing for geolocation data existence. In case of problems with processing the pictures, it is recommended to decrease the value (what in turn will make the process of processing pictures longer)

List View

Group of options connected with listing of posts in categories and archives. Plugin displays buttons leading to maps directly in post, instead of displaying a map.

Map link style – style of map link, it can be stretched over the full width, behave like inline element or be centered.

Text for the map link – own button text leading to the map from Simple and Advanced modes. In case when this field is empty, the default text See the map will be applied instead.

Text for the gallery link – own text of the button leading to the gallery from Gallery mode. In case when this field is empty, the default text See the gallery will be applied instead.

Advanced

Reduce shortcode params – thanks to turning this option on, the shortcodes generated in the editor will have much less parameters. Only these that differ from the default parameters will be generated. It is a perfect solution for people who want to modify the appearance of many shortcodes from one place.

Show position preview – allows to enable preview of the localization using Static Maps API in metabox of localization in post editor.
CAUTION: after enabling this option we recommend generating the Google Static Maps API Key.

Enable touch events for maps on mobile devices – by default, when the user touches a map field on mobile, the swiping over the map area will just scroll the site – map is ‘frozen’. If enabled, swipes on the screen on mobile device will scroll the map.

Restore default settings – button allowing to revert to default settings.
CAUTION: this operation is irreversible and leads to losing all own settings of the plugins along with map styles, it can also make problems with appearance of the shortcodes applied in the posts before.

SIMPLE MODE

Simple mode is used when we wish to have a possibility to display popup with location of a given photo by clicking the icon that appears upon moving the mouse over the picture. Moreover, it is possible to display a map with all photos contained in a post.

Options available for this mode can be found in Simple mode tab.

Basic settings

Default preset – the default map style adjusted in maps of this mode.

Put simple mode shortcode automatically – allows to add a map with markers automatically, in all places where there are photos with defined geolocation data. Map can be placed at the beginning or ending of the post. Choosing Never turns that behaviour off.

Button “Show all markers” – turns on/off display of the button to show all marker on map.

Action after clicking icon over image – specifies the behaviour after clicking the icon appearing after moving mouse over the photo with geolocation data. We can choose from showing popup or scrolling the page to map and activation of the given marker.

Action after clicking marker on the shortcode map – specifies the behaviour after clicking marker on the map. We can choose from showing the popup or scrolling the site to the photo corresponding with the given marker.

Ratio for the shortcode map – proportions of the map block.

Icon

Settings of the icon appearing after moving mouse over the photo.

Icon position – sets the position of icon over photo (one of the corners or middle of the photo).

Icon background color – sets the background color of the icon.

Icon :hover background color – sets the background color of the icon upon moving mouse over it.

Custom icon image – allows to choose own picture for the marker icon.

Icon dimensions – sets the dimensions.

All above options are connected with the preview where we can see how the icon will look like and what is its position on the photo with geolocation data.

Popup

Options corresponding to the popup displayed after clicking the icon on the photo, provided that the display of the popup is turned on in Action after clicking icon over image:

Popup dimensions – sets the dimensions of popup.

Popup maximum dimensions – sets the max dimensions of the popup – percentage value in relation to the window.

Overlay background color – sets the color of background under popup.

Overlay opacity – sets the opacity of background under popup.

Info window in popup – defines if and how the popup for the marker will be displayed after displaying popup with map.

Markers

Use marker clusterer – allows to turn on/off marker grouping on the map – useful when there are a lot of markers around a small area.
CAUTION: in this case the merging of markers doesn’t work.

Marker icon – icon of the marker used on the map.

Custom marker icon – if the previous part has been set to Custom icon, then here it is the place to define own marker icon.

Info Window

Options regarding the popup displayed after clicking on the marker on the map.

Display post thumbnail – option allowing to determine whether the thumbnail should be displayed in popup (it only works on the main map in post – it doesn’t work for popups activated by clicking on images)
Info window title
– option allowing to determine what shall be displayed as a title in popup.
Info window text – option allowing to determine what shall be displayed as text in popup.

Point Connections

Create connections between markers – allows to turn on connecting points on the map by the shortest route.

Connections mode – allows to choose the means of connections between points: by car, on foot, on bike or using public transport.

Connections order – the way of determining order of posts when setting route between points.

GALLERY MODE

Options for Gallery mode, available in the corresponding tab.

Layout

Default preset – style of map.

Map position – position of map in relation to the photo showcase.

Ratio for the block – proportions for block with photos.

Ratio for the photos and map – proportions between block with photos and the map.

Background color for photos – color of the background of photos block.

Interface

Padding for the images – allows to specify the minimal distance between the picture and the border of the block with pictures.

Show photo titles – turns on/off displaying titles of photos/posts in photo showcase.

Show photo description – turns on/off showing short introduction based on description/photo content/post.

Background color for the image description – color of background for photo description.

Text color for the image description – color of text for photo description.

Image description opacity – transparency for the photo description block.

Show navigation – turns on/off the navigation between photos.

Show counter – turns on/off the photo amount counter.

Show controls on hover – turns on/off the counter and navigation only after moving the mouse over photo block.

Stop animation on hover – stops the autoanimation when cursor is over the gallery.

Background color for the navigation – color of navigation and photo counter.

Text color for the navigation – color of navigation text and photo counter.

Navigation opacity – transparency of navigation and photo counter.

Marker

Marker icon – icon of the marker used in the map.

Custom marker icon – if the previous option has been set to Custom icon, this option allows to set own picture for the marker.

Animations and Effects

Active pin effect – type of animation for active marker.

Active marker icon – if the previous option has been set to Change icon, this option allows to set how the marker should change while it is active.

Custom marker icon – if the previous option has been set to Custom icon, this option allows to set own picture for the marker.

Autoanimation interval (in ms) – time between transitions between photos in milliseconds.

Point Connections

Create connections between markers – allows to turn on connecting points on the map by the shortest route.

Connections mode – allows to choose the means of connections between points: by car, on foot, on bike or using public transport.

Connections order – the way of determining order of posts when setting route between points.

Advanced

Supported post types – thanks to this option it is possible to set what type of WordPress media content or post will be considered.

Use also featured image geodata – this option allows to turn on utilizing the geolocation data of featured image, provided that the post itself doesn’t have any data of that type.

ADVANCED MODE

Options for Advanced mode, available in the corresponding tab.

Map settings

Default preset – allows to choose the map style from list of styles created before.

Action after clicking marker on map – allows to decide what happens after clicking marker on the map: show the popup (show info window) or redirection to the corresponding post (navigate to the post connected with the marker).

Button “Show all markers” – allows to turn on/off the button to show all markers on the map.

Ratio for the map – allows to determine proportions of the map block.

Use marker clusterer – allows to turn on/off the grouping of markers on map – useful when there are multiple markers across small area.
Caution: in this case the merging of markers doesn’t work.

Marker

Marker icon – icon of marker used on the map.

Custom marker icon – if the previous option has been set to Custom icon, this option allows to set own marker icon.

Info Window

Options regarding the popup that is displayed after clicking marker on the map.

Display post thumbnail – allows to turn on/off display of the thumbnail of post in popup.

Use first post image – allows to turn on/off using the first photo from the post content, provided that the post does not have any icon set.
Caution: turning this option on can affect the site performance.

Info window title – option allowing to specify what should be displayed as a title in popup.

Info window text – option allowing to specify what should be displayed as text in popup.

Point Connections

Create connections between markers – allows to turn on connecting points on the map by the shortest route.

Connections mode – allows to choose the means of connections between points: by car, on foot, on bike or using public transport.

Connections order – the way of determining order of posts when setting route between points.

Posts Listing

Posts listing layout – choose the layout of yout lists.

Number of columns – choose the amount of columns for the listing.

Advanced settings

Supported post types – thanks to this option it is possible to set what type of WordPress media content or post will be considered.

Use also featured image geodata – this option allows to turn on utilizing the geolocation data of featured image, provided that the post itself doesn’t have any data of that type.

DETECTING GEOLOCATION OF PHOTOS

After installing the plugin, it is worth to process all photos in the media library for the existence of geolocation data – it can be done in the Processing media tab in the plugin settings:

After clicking the Find attachments without geodata button, all photos containing the geodata will be searched for.

In case of larger photo collections, some read error notifications can appear – in such a case it would be worth to repeat the whole process.

Caution: During the process the browser shall not be closed, nor the tab with the photo process page – the process is performed only when the page is open in the browser

Important: This operation is usually needed only one time – after installing the plugin, the newly added photos will have the geolocation data saved automatically during saving the photos. The only exception is the case when Gocha GEO plugin is for some reason uninstalled or deactivated for some time – then, it is worth performing the process again in order to make sure that the photos added over that time have correct geodata applied.

TAGGING PHOTOS ON THE MAP

Upon activating GOCHA Geo plugin, every photo in media library should have two additional fields specifying geolocation:

Provided that we have already processed our photos for the geolocation data existence, some of the photos should have the fields already filled in (like on the picture above).

In the case of photos which don’t have such data, you can click on Change coordinates –then, a popup will come up. It works exactly the same like the one we see when changing location of posts.

If you wish to easily find photos that haven’t got the geolocation specified yet, you can use the filter in media library that is also added as a feature of Gocha GEO:

Thanks to this we can find photos that: have the geolocation data, don’t have the geolocation data, have the geolocation data empty (removed when editing), unprocessed for geolocation data existence.

TAGGING POSTS ON THE MAP

After installing the Gocha GEO plugin, each post can be associated with geolocation. It is possible thanks to the metabox called GOCHA Geo Location:

After pressing the Set location button, a popup with map will come up:

It allows us to move the marker using drag-and-drop technique or by double clicking on the map. In case of more distant localization, it might be worth using the place browser placed on the top.

Pressing the button Use current marker coordinates will save our location in the metabox. Since then, the location will be connected with our post and will be able to be used in Gallery and Advanced modes.

Caution: If the mentioned metabox is not visible in the post editor, please make sure that Gallery or Advanced modes have been activated. Moreover, please check that the types of posts we edit are chosen in mode settings.

CREATING OWN MAP STYLE

Google Maps API offers the possibility to define own map styles – it requires creating special JavaScript object.

Less advanced users can choose one of predefined styles available in Snazzy Maps service or use official Google creator.
In Gocha GEO plugin there are two ways to add own map style:
– By adding a file containing style
– By using gocha_geo_custom_map_style filter

Adding file containing style

Objects generated on your own or by Snazzy Maps service should be saved in .JSON file and be given a name consisting of Latin alphabet, digits and hyphens (e.g. custom-map.json). Then, this file should be places in the following catalogue: wp-content/plugins/gocha-geo-plugin/map-styles/ – when done, it will appear in map style creator in field Custom map style:

Using this method is recommended ONLY if we wish to overwrite all existing styles and place one, specific map style. It comes out from the fact that this method will overwrite reading all maps styles by the style defined in filter function.
Filter can be used in two ways – to return new map style:

add_filter('gocha_geo_custom_map_style', 'my_map_style');
function my_map_style() {
return '[{...code of the custom style...}]';
}

Another option is to modify the object structure by operations on strings or by decoding, processing and saving again the JSON data as string:

add_filter('gocha_geo_custom_map_style', 'my_map_style');
function my_map_style($json_data) {
// Convert to an PHP object/array
$json_data = json_decode($json_data);
// ...
// operations on the object
// ...
// Revert to the string
$json_data = json_encode($json_data);
return $json_data;
}

Thanks to the aforementioned method we can e.g. change colors in all styles without the necessity of modifying their JSON files.

ADDING MAPS TO POST CONTENT

Maps can be added to the content of posts in two ways:
– Using shortcakes
– By turning on the feature of automatic map addition in Simple mode, for posts where there are photos containing geolocation data. Such behaviour can be enabled in Simple mode options – Put simple mode shortcode automatically.

Adding shortcode

Shortcodes can be added using a special button in the text editor:

After pressing it, a list with available shortcodes will appear. Clicking on chosen shortcode will bring up a popup with settings.

Caution: if all modes have been disabled in basic plugin settings, then this button will be hidden.

Every shortcode has got a bit different popup that depends on the settings of the mode. Most of the options are the same as the default settings in the plugin options. Additional ones will only appear in Gallery and Advanced modes.

Special options in Gallery mode

In Gallery mode there are options connected with data source:

Data source lets you determine whether the source of data should be photos or posts.

In case of photos, you just have to add photos from the media library by clicking the icon to add photos:

Chosen photos can be deleted after they have been added, their order can be changed by drag-and-drop technique.

In case of selecting posts as the data source, we have more options a tour disposal:

Only the posts which contain geolocation data in location metabox will be considered, as well as posts from the group of posts supported in Gallery mode (checked in Supported post types option).

Posts from option allows to specify where the posts will be taken from. After choosing specific options, the fields to choose source of data (categories, tags, posts) will appear.

Selection mode option allows to decide if the posts should come from the specified set (Include selected items) or they should rather be skipped (Exclude selected items).

Thanks to Number of posts option you can decide how many posts will be displayed. Moreover, Order by and Order direction allow to choose the manner of sorting.

Special Advanced mode options

In Advanced mode there are also some options to choose the data source, with the only difference being that in this case we can only choose posts:

Options behave exactly the same as in the case of Gallery mode.

Editing and removing shortcodes

When we add a shortcode to our post, it would not be comfortable to edit it manually. That’s why we can use much more convenient way – just mark the shortcode content in the text editor:

Then, a button will appear over the shortcode – one allows to bring up the configuration popup, the other one allows to quickly remove the shortcode.

Caution: this additional panel of editing/removing will only work when only one shortcode is marked (it is OK to highlight some normal text, too, the only restriction is that two or more shortcodes cannot be highlighted simultaneously).

AVAILABLE ACTIONS

All actions mentioned here reveive the shortcode ID as an argument – ID of post and ordinal number of shortcode in post, separated by comma:

gocha_geo_before_advanced_mode_shortcode – the place right before displaying shortcode for advanced mode

gocha_geo_after_advanced_mode_shortcode – the place right after displaying shortcode for advanced mode

gocha_geo_before_advanced_mode_posts_list – the place right before displaying post list for advanced mode

gocha_geo_after_advanced_mode_posts_list – the place right after displaying post list for advanced mode

gocha_geo_before_gallery_mode_shortcode – the place right before displaying shortcode for gallery mode

gocha_geo_after_gallery_mode_shortcode – the place right after displaying shortcode for gallery mode

gocha_geo_before_simple_mode_shortcode – the place right before displaying shortcode for simple mode

gocha_geo_after_simple_mode_shortcode – the place right after displaying shortcode for simple mode

AVAILABLE FILTERS

gocha_geo_custom_map_style – used to overwrite map presets. Filtering function receives only one argument – the data of map style in JSON format, saved as string,

gocha_geo_custom_posts_listing – used to overwrite post listings. Filtering function receives only one argument – listing template format saves as string,

gocha_geo_advanced_mode_output – used to overwrite output from a given advanced mode shortcode, receives two arguments – HTML code and shortcode ID,

gocha_geo_gallery_mode_output – used to overwrite output from a given gallery mode shortcode, receives two arguments – HTML code and shortcode ID,

gocha_geo_simple_mode_output – used to overwrite output from a given simple mode shortcode, receives two arguments – HTML code and shortcode ID,

gocha_geo_simple_mode_info_window_content – used to modify data for window connected with marker in simple mode – receives associative table with fields: title, desc, date,

gocha_geo_simple_mode_markers or
gocha_geo_gallery_mode_markers or
gocha_geo_advanced_mode_markers – used to modify marker table used on map in specific mode. Receives table of associative tables with fields: lat, lon, id, url, title, desc, date,

gocha_geo_format_parser_replacements – used to modify markers in post listing formats for advanced mode – receives marker table used for listing files, post data and map ID.

ADDING OWN LISTING STYLE IN ADVANCED MODE

Gocha GEO plugin provides a dozen of predefined listing styles for Advanced mode. However, there is nothing against creating own ones.

You can do it in two ways:
– by adding own file with .preset extension in wp-content/plugins/gocha-geo-plugin/post-listings catalogue
– by overwriting all listings using gocha_geo_custom_posts_listing filter

Caution: using the second way will lead to overwriting all listings, and the plugin settings for choosing listing of posts will not be respected anymore. It doesn’t apply to the situation when the structure of listing is just slightly modified using the filter (which may be useful e.g. to add a specific CSS class in all types of listings).

Filter gocha_geo_format_parser_replacements is an additional possibility when creating own formats. It lets you create own {NAME} type markers used in .preset files.

In this way, we can modify the table of markers that by default looks as following:

$replacements = array(
'{THUMBNAIL}' => '<img src="'.$data['img'].'" alt="" />',
'{EXCERPT}' => $data['post_excerpt'],
'{TITLE}' => $data['post_title'],
'{ENTRY_LINK}' => ''.__('Read post', 'gocha-geo').'',
'{MAP_LINK}' => ''.__('View on map', 'gocha-geo').''
);

ADDING OWN MAP STYLE

Thanks to built-in map style editor available in Map presets, it is easy and comfortable to create dedicated map styles (with live preview) that will be used in all modes of the plugin functionality:

For every style, it is possible to determine what controls will be visible and what map designs will be applied. You can also define own map designs.
After saving the map, it will appear in a list on the right:

The description of icons linked to each of the map style:

  • edit the map style
  • copy and open for editing (perfect for cloning styles)
  • delete map style

Changes on this lists are visible right away in the Default preset option in each of the plugin functionality mode.

VISUAL COMPOSER

Thanks to this, the plugin implements three blocks possible to use in VC:

  1. Gocha GEO Simple mode
  2. Gocha GEO Gallery mode
  3. Gocha GEO Advanced mode

All of them are available in Content tab.
Options available for the blocks are no different from the options available in WYSIWYG editor.

Caution: there is a fundamental difference between the behaviour of WYSIWYG editor and VC – in case of Visual Composer, the generated shortcodes will only include those parameters that are not set as default values – these from plugin settings. In other words, shortcodes are always generated as if the option Reduce shortcode params was enabled.

Support

If you come across problems or questions not mentioned in the manuals, feel free to contact out support. We are doing our best to provide you with the best and quick assistance. We are normally investigating the tickets twice a day, six days a week – from Monday to Saturday.

Support tickets
top
down
up