MapPress Documentation

MapPress

Compatibility and Installation

MapPress is compatible with WordPress 5.0 and higher.  See the Installation Instructions for information about installing the plugin.

Picking a Mapping API

MapPress supports two mapping APIs:

Google

  • Google has very accurate geocoding and great-looking maps
  • Requires billing information and an API key
  • Free usage is limited.

Leaflet

  • Completely free and open-source
  • Geocoding is only accurate to street level unless MapPress Pro is used
  • The default map tiles aren’t very attractive, but Mapbox offers improved tiles (sign up to get an access token. Mapbox is not free, but the free usage level is much higher than Google and paid usage is less expensive.
  • Traffic, bicycling and public transportation overlays are not available
  • Drawing shapes and lines is not supported

Creating a Map with the Gutenberg Block Editor

Select the ‘MapPress Map’ block type to insert a map into the post. Settings can be controlled from the WordPress inspector toolbar. To insert an existing map, use the map library button in the MapPress block.

To insert an existing map, or replace a map with another one, use the Map Library button in the block toolbar. This opens the Map Library popup with a list of all existing maps. The list can be filtered to show only maps attached to (created in) the current post, or all maps. It’s also possible to search by mapid, map title or post title.

Creating a Map with the Classic Editor

MapPress adds a map editing meta box to WordPress classic editor.

The meta box is only present for the post types selected in the MapPress settings

Click an existing map to edit it, or click the “new map” button to create a new map.

Editing a Map

Map ID: when a map is saved it is assigned an ID number.  You can use this ID in the [mappress] shortcode to display a specific map.

Map Title: enter a title for the map

Size:  This setting only appears in the classic editor – for Gutenberg, it’s in the inspector sidebar. Click one of the links to choose a default size or enter a custom size. 

Search box: enter an address or place to search for (see below)

Insert into post button: insert the MapPress shortcode for this map into your WordPress post.  Click the cursor in the post where you want the shortcode inserted before pressing the button.

Save button:  save the map

Cancel button: cancel any map edits

Geolocation icon (right side of search box):  click to enter your current location into the map.

Creating a POI

To create a new POI, enter an address, place, or business into the search box.  Latitude/longitude coordinates may also be entered as decimals.

For example, enter “1600 Pennsylvania Ave NW, Washington, DC” for the White House, or “38.8792,76.9818” for the corresponding coordinates.

By default, Leaflet locations are only precise to the nearest street. See the MapPress Pro section on geocoders for details.

Click the POI to edit the popup text and title.  Then save the POI.

Title: enter a title for the POI.

Body: enter the body for the POI

Icon: click the icon to change it (MapPress Pro only)

Save button: save your changes

Cancel button: cancel your change

Setting the Map Type

Google has several standard map types which may be selected using the map type control in the upper right of the map editor.

Leaflet has only one map type, so the map type control is not displayed by default. However, if a Mapbox access token is entered in the MapPress settings, the control will appear and several Mapbox types may be selected.

Creating POIs Using Shapes

(MapPress Pro only) The shapes toolbar on the map can be used to create lines, polygons, circles and rectangles.  When drawing a line (called a polyline) or polygon, the shape can be completed by clicking on its last point.

Polygons and polylines can also be edited.

  • Add a new vertex
    • Click a transparent handle between the existing vertices
  • Delete a vertex
    • Google: right-click the vertex
    • Leaflet: click the vertex

Creating POIs for KML Files

To add a KML file to the map, enter its URL in the ‘search’ field (where the POI’s address would normally be entered).  The KML may reside on a remote server, provided it allows access, or on the local server.

For example:

  1.  Copy this file to your WordPress ‘uploads’ directory:
    https://developers.google.com/kml/documentation/KML_Samples.kml
  2. Enter the URL to the file in the MapPress search box.  For example:
    http://myserver/wp-content/uploads/KML_Samples.kml
  3. You should see the KML file has been added to the map

Google will not display KML files larger than about 10MB.  Google also limits the number of KML files that can be displayed on one map: depending on the size of the files the limit is around 12-15 KML files.

Sorting

POIs can be dragged in the Map Editor to change their sort order.  There is also a checkbox on the MapPress settings screen to sort POIs alphabetically by default.

Dragging POI Markers

Sometimes it’s impossible to exactly locate a POI using a street address.  In this case the POI’s marker can be dragged to the correct location. Note that POIs that have been dragged do not have a street address, they have only latitude/longitude coordinates.

Shortcodes

The simplest form of the shortcode displays the first map for a post:

[mappress]

A map ID can also be specified to display a specific map:

[mappress mapid="2"]

Many other parameters are available – see the “Reference” section.  For example, this will open 400×400 map with mapid “1234”.  It will also open the first marker immediately:

[mappress mapid="1234" width="400" height="400" initialopeninfo="true"]

Converting Existing Shortcodes in the Gutenberg Editor

Existing MapPress shortcodes must be converted to blocks in order to edit the underlying map. If the post hasn’t been converted to Gutenberg already, the shortcode will be in a ‘classic block’. Select the block and choose ‘convert to blocks’ from the block menu.

Shortcodes must be on a separate line, with no adjacent text or punctuation.

If the post has previously been converted to blocks, the shortcode will be in a ‘shortcode’ block. Select the block and use the ‘change block type’ button to convert it to a Map or Mashup block.

Map Sizing

For responsive maps, set the map width to a percentage. 90% works well because it leaves space along the side of the page for scrolling on mobile devices.

Map height usually works best as a fixed pixel size, but it can also be set to a percentage. The percentage is based on the map’s width. For example a map with 100% height is as tall as it is wide. Similarly, a height of 56.25% corresponds to a 16:9 aspect ratio.

Maps can also be set to a percentage of the viewport width or height. For example 50vw will size the map to half the width of the browser window, at 50vh will do the same for the height.

Template Tags

Maps can be displayed by adding PHP template tags to theme template files.  MapPress loads all of the required JavaScript and CSS only when a map is being displayed.

The easiest way to add a map to your template is using the do_shortcode() statement.

For example, this will display the map with mapid=20:

<?php echo do_shortcode('[[mappress mapid="20"]]'); ?>

Put the whole shortcode in single quotes, but the shortcode arguments in double quotes

Backing Up and Copying MapPress Data

MapPress stores all of its data in two tables: mappress_maps and mappress_posts. Options are stored in the standard WordPress options table.

The MapPress tables will normally be included if you’re backing up your entire WordPress database, or you can export them using MySQL.

If you copy your blog from one place to another you will also need to copy the MapPress tables. If for some reason you renumber of change your post IDs you will also need to update the mappress_posts table with the new post IDs.

MapPress Pro

Overview

MapPress Pro is the premium version of MapPress.  It contains additional features that are described below.

Geocoding

A geocoder is a web-based service that translates addresses like ‘200 Main Street’ into latitude and longitude coordinates that can be displayed on a map. 

The Google API always uses the Google geocoder. This is the best available geocoder and it has very precise results.

For Leaflet, there are a variety of geocoders available.

Algolia is free and has no usage limits, but its geocoding is mediocre. It is also limited to ‘street level’ accuracy: if a house address is entered, it will return the middle of the nearest street.

Nominatim is similar to Algolia, but it has house-level accuracy in some areas.

The admin email address is included with Nominatim geocoding requests (a Nominatim requirement)

MapBox is more accurate than Algolia and Nominatim. It isn’t free but has generous usage limits.

ServiceTerms of ServiceFreeRegistrationUsage LimitAccuracy
GoogleLinkNoYesYesExact
AlgoliaLinkYesNoNoneStreet only
NominatimLinkYesNoNoneExact in some Locations, street elsewhere
MapBoxLinkNoYes100,000 per monthExact

Icons

MapPress Pro includes standard marker icons, and custom icons can be uploaded through the MapPress settings screen.

To set the icon for a POI, edit the POI in the map editor.  In the upper-right corner you should see the current icon.  Click on it to change the icon.

image_thumb7_thumb1

Click on an icon in the popup list to select it.  Click the link ‘use default icon’ to select the default icon.  The default icon can be assigned in the MapPress settings screen.

image_thumb12_thumb1

Custom Icons

Standard icon .PNG files are located in the /pro/standard_icons/ subdirectory of the MapPress plugin.  When MapPress is activated it also creates a directory for custom icons in the WordPress uploads directory:

/wp-content/uploads/mappress/icons

Some themes change the upload directory. The correct location is shown in the MapPress settings screen.

To add custom icons, copy them to the custom icons directory using FTP or use the MapPress settings screen to upload them from a PC.

Icons may be .jpg, .png or .gif files.  They are usually 32×32 pixels. There are many web-based icon generators and custom icon collections.

Mashups

Mashups combine multiple maps into a single larger map.

Mashups are based on a query, which specifies which posts to display.  MapPress reads all of the matching posts and combines the map locations from those posts into a single mashup map.

The mashup query can find a single post, all posts, or posts matching certain post type, author, tag, category, taxonomy, or custom field.

Mashups in the Gutenberg Editor

To create a mashup in the Gutenberg editor, just select the MapPress Mashup block. The mashup query parameters can be set in the Gutenberg inspector control. In the example below, a mashup is added to a post and the query is set to select only posts with the tags ‘blue’ and ‘green’. The posts each have a blue or green marker.

Mashups in the Classic Editor

In the classic editor, mashups are created by typing a shortcode directly into the post content. The most basic version of the shortcode is:

[mashup]

This will create a mashup map of all posts.

WordPress shortcodes must be on a separate line, or they won’t work

Mashup Queries

More advanced mashups requires a query attribute to specify which posts to read. The query is in the same format as the WordPress query_posts function, so query examples are available in the WordPress Codex for WP_Query.

Query Examples

Show a single post with post ID = 5:

[mashup query="p=5"]

Show a single page with page ID = 5:

[mashup query="page_id=5"]

Show map locations from the currently displayed posts (you may also just omit the query parameter):

[mashup query="current"]

Show all pages with maps:

[mashup query="post_type=page"]

Show the posts (or pages) with post ID = 3, 4 and 5:

[mashup query="post__in=3,4,5"]

Show the posts in category “mycat”:

[mashup query="category_name=mycat"]

Show posts for custom post type “business”:

[mashup query="post_type=business"]

Shows posts for tags 37 and 47:

[mashup query="tag__and=37,47"]

Show posts assigned to category 1 or category 3:

[mashup query="category__in=1,3"]

Show posts assigned to both category 1 and category 3:

[mashup query="category__and=1,3"]

Show posts that have the custom field ‘color’, regardless of the field value:

[mashup query="meta_key=color"]

Show posts that have the custom field ‘color’ set to the value ‘blue’:

[mashup query="meta_key=color&meta_value=blue"]

The order and orderby parameters can be used to sort the query results by various fields including author, date, etc.  For example to sort all posts by date, descending:

[mashup query="orderby=date&order=desc"]

Show posts with custom taxonomy ‘hotels’ with term value=budget:

[mashup query="hotels=budget"]

Posts having custom taxonomy ‘hotels’ with value ‘luxury’ AND custom taxonomy ‘rating’ with value ‘5star’:

[mashup query="hotels=luxury&rating=5star"]

This excellent article has additional examples about custom taxonomy queries: http://thereforei.am/2011/10/28/advanced-taxonomy-queries-with-pretty-urls/

Queries Using Arrays

WordPress expects an array value for some parameters.  For example dates are specified with a date_query array.  This array would show posts created before yesterday:

'date_query' => array(
    array(
        'before'      => 'now-1day'
    )
)

WordPress shortcodes don’t support arrays directly, so arrays must be converted to a URL string notation, where [0] is the first array element, [1] is the second, and so on:

date_query[0][before]=now-1day

Unfortunately, WordPress also prohibits braces in shortcodes!  To work around this, MapPress allows the parameters to be enclosed in curly braces. instead (you may also use the HTML codes %5d and %5e instead of braces). For example, the query above is written like this in the mashup shortcode:

[mashup query="date_query{0}{before}=now-1day"]

or:

[mashup query="date_query%5b0%5d%5bbefore%5d=now-1day"]

Queries Using URL Parameters

WordPress parses the URL for various parameters.  For example, category archives are displayed with the following URL format:

http://myblog.com/category/mycat

When the page is displayed, WordPress places the current category name in the ‘cat’ parameter (in this case, it’s category ‘mycat’).  To create a mashup that displays the current page category, no matter what it is, specify the ‘cat’ query parameter as ‘@cat’:

<?php echo do_shortcode('[mashup query="cat=@cat"]'); ?>

Mashup Template Tag

Adding a mashup to your template is easy. Just add a few lines of PHP code:

<?php echo do_shortcode('[[mashup]]'); ?>

For example, this will display a mashup of all maps:

<?php echo do_shortcode('[[mashup width="425" height="350"]]'); ?>

Be careful to put the whole shortcode in single quotes but the shortcode arguments in double quotes

It’s also possible to use variables in the query.  For example, adding this code to the category archive template will show all posts in the current category:

<?php
$cat = get_category( get_query_var( 'cat' ) ); 
$cat_id = $cat->cat_ID; 
$query = "cat=" . $cat_id;
echo do_shortcode('[mashup width="425" height="350" query="' . $query . '"]'); 
?>

A search box is present at the top of every mashup.  Users may enter an address, business or place to center on a particular area.  As the map is panned or zoomed, the POI list is updated to show results from just the current area

MapPress Templating

MapPress maps are displayed using customizable map template files.  Each file controls a part of the map output.

JavaScript Templates

JavaScript template files are used to render parts of the map dynamically.  The templates are:

  • map-tmpl-popup.php – map POI popup
  • map-tmpl-item.php – map POI list row
  • mashup-tmpl-popup.php – mashup POI popup
  • mashup-tmpl-item.php – mashup POI list row

Customizing JavaScript Templates

JavaScript templates can be edited directly in the MapPress settings screen, using the template editor.  The editor shows either the default template file (from the plugin directory /templates) or a customized file (if one exists).  Customized template files are always saved to the theme or child theme directory.

JavaScript templates contain a mix of HTML, PHP, template variables, and JavaScript.

PHP Code

PHP is used in the default templates to output text strings.  This allows the strings to be translated by multilingual plugins.  For example, the map-tmpl-popup template file contains this line, which outputs the string ‘Directions’:

<?php _e('Directions'); ?>

Template Variables

Template variables are output using the underscore.js template library that is included with WordPress.   The following delimiters are used:

  • {{ ... }} : HTML-escaped variables (for example character ‘&’ will be escaped to ‘&amp;’
  • {{{ ... }}} : Variables without HTML-escaping

The available POI fields are shown above the editor.  Click a field name (such as ‘title’ or ‘body’) to insert the template variable and the correct delimiters.

Custom Fields

To add a custom field to a template, use this syntax:

{{poi.props.myfield}}

MapPress will automatically include that custom field when the template is output.

Custom Properties

Each POI has a set of standard properties (title, body, etc.).  It also has a ‘props’ array that contains custom properties.

Filter mappress_poi_props can be used to add custom properties to the props array.  For example, adding this code to a theme’s functions.php file will create a ‘message’ property for each POI that shows a ‘hello’ message and the POI’s underlying post ID:

<?php
function myfilter($props, $postid, $poi) {
    $props[['message']] = "Hello from post " . $postid;
return $props;
}
add_filter('mappress_poi_props', 'myfilter', 10, 3);
?>

The new message property can now be included in templates as:

{{poi.props.message}}

JavaScript Code

JavaScript code can be included in a template using the tags <# ... #> For example, adding this tag to a template this would display an alert box every time the template is rendered:

<# alert('hello world!'); #>

Conditionals are also possible. For example, this will output an HTML message if the POI is attached to post #1234:

<# if (poi.postid == 1234) { #>
<p>This is post 1234!</p>
<# } #>

PHP Templates

Some of the map templates are PHP files.  These templates are static – that is, they’re output only once when the map is first displayed.

  • map.php – the general layout of the map elements
  • map-directions.php – the map directions form
  • map-filters.php – the map filters form
  • map-header.php – the map header (search bar and filters link)
  • map-search.php – the search box

Customizing PHP Templates

Generally, PHP templates do not need to be modified, so that aren’t supported in the MapPress template editor.

If you do need to modify them, the default templates are in the plugin directory /templates.  Copy the template to be modified to the theme (or child theme) directory using FTP, then modify the copy using a text editor.

WordPress overwrites all theme files when a theme is updated, so always use a child theme.

Widgets

Mashup Widget

The MapPress Mashup widget is available from the WordPress widgets screen. The widget can display a custom query, similar to the shortcode.

For example, to show the blog page with ID = 5 the shortcode looks like this:

[mappress query="page_id=5"]

In the widget the same query is entered like this:

page_id=5

Or, to show all posts with category “cat1” enter this in the custom query text box:

category_name=cat1

Generating Maps From Custom Fields

MapPress Pro can automatically generate maps from custom fields. This is useful if you store address data in custom fields or if you need to import map data from a file.

Each generated map contains a single POI. To specify the POI’s location, you must have custom fields with either a street address, or a latitude and longitude, on each post.  Select the fields on the MapPress settings screen in the ‘Geocoding’ section, and save the settings.  The address fields are concatenated together and become the street address for the POI.

When any post containing the address fields is published or updated, a map is generated and attached to the post. 

You may also specify fields for the POI title, body and icon, but this is often not necessary. If post information (title and excerpt) is being shown in the POIs, there is no need to specify a title and body. And automatic icon assignment by taxonomy is often more flexible than assigning icons explicitly. See the MapPress settings screen for the relevant settings.

The dropdown lists of custom fields shows only fields that are used in at least one post. If you’re setting up the fields in advance, you will need to create a dummy post with those fields to get them to show in the list.

If errors occur during map generation, they are shown in the MapPress settings screen. Error details are also written to the custom field mappress_errors.

Geocoding

When maps are generated from custom field data, the address is be ‘geocoded’ (converted to latitude/longitude coordinates).

If you are using the Google API, the Google geocoder is used. This geocoder is very accurate, but Google imposes a usage limit of about 2,500 geocoding requests per day.  Once that limit is exceeded all geocoding will be rejected, and maps will show a location at lat/lng (0,0) (in the ocean near Africa).

Google’s usage limit is by IP address, so on shared hosts, all the sites combined cannot exceed that limit.  In other words, another site on the same host may consume the geocoding limit.

If you find that you’re exceeding Google’s usage limits:

  • You can purchase Google Maps for Business from Google or contact them for usage-based billing. They will give you an API key that has its own (not shared) usage limit.
  • You can use Leaflet with Algolia or Nominatim, which currently have no usage limits, or MapBox, which has more generous limits.

Manually Editing Generated Maps

Generated maps can be edited manually. However, the map will normally re-generated if the post is published or updated, overwriting any manual changes. To prevent this, uncheck the setting ‘Overwrite maps when posts are saved’.

Events for Generating Maps

MapPress generates maps only when a post is saved or published.  Some forms and custom field plugins update custom fields directly, without saving the containing post.  In this case it is necessary to trigger map generation using some PHP code.  See The ‘Examples’ section for code samples.

Displaying Maps Using PHP

Maps can be displayed dynamically by using PHP code in template files.

MapPress uses the classes Mappress_Map, Mappress_Poi and Mappress_Options to define maps, POIs and options settings, respectively.  Object constructors accept an array of attributes to override defaults settings.

For example, this code creates a new map object.  The default map size is 425px by 350px, but in this example the width is set to 600px:

$mymap = new Mappress_Map(array("width" => 600));

This creates two new POI objects, specifying the title, body and ‘point’ (the latitude / longitude):

$mypoi_1 = new Mappress_Poi(array("title" => "DC", "body" => "Beautiful Washington, DC", "point" => array("lat" => 38.90279, "lng" => -77.037849)));
$mypoi_2 = new Mappress_Poi(array("title" => "500 Chestnut St", "body" => "Independence National Park, Philadelphia, PA<br/>19106", "point" => array("lat" => 39.948712,"lng" => -75.15001)));

Once the POIs have been defined, they can be added to the map:

$mymap->pois = array($mypoi_1, $mypoi_2);

Finally, the map can be displayed:

echo $mymap->display()

Putting it all together gives the following code:

$mymap = new Mappress_Map(array("width" => 600));

$mypoi_1 = new Mappress_Poi(array("title" => "DC", "body" => "Beautiful Washington, DC", "point" => array("lat" => 38.90279, "lng" => -77.037849)));

$mypoi_2 = new Mappress_Poi(array("title" => "500 Chestnut St", "body" => "Independence National Park, Philadelphia, PA<br/>19106", "point" => array("lat" => 39.948712,"lng" => -75.15001)));
$mymap->pois = array($mypoi_1, $mypoi_2); 
echo $mymap->display();

Setting Center and Zoom

If a map has no center and zoom specified, it will be automatically centered and zoomed to show all of its POIs.  It’s also possible to set a specific center or zoom.  For example, this code will show a map centered over Washington, DC (without any POIs):

$mymap = new Mappress_Map(array("center" => array("lat" => 38.90279, "lng" => -77.037849), "zoom" => 12));
echo $mymap->display();

If you specify a center, you must also specify a zoom, and vice-versa.  Both parameters are required in order to show the map.

Icon IDs

Each POI may have its own icon.  The iconid property specifies either a standard icon or a custom icon for each POI.  For standard icons the icon ID is the image file name without any extension.  For example the icon ID for the standard green dot icon green-dot.png is green-dot.  For custom icons, the icon ID is the entire filename including the extension, such as myicon.png

In the example below the first POI is assigned to the standard green dot icon and the second is assigned to a custom icon called “family.png”:

$mymap = new Mappress_Map(array("width" => 600));
$mypoi_1 = new Mappress_Poi(array("iconid" => "green-dot", "title" => "Standard Icon Example", "point" => array("lat" => 38.90279, "lng" => -77.037849)));
$mypoi_2 = new Mappress_Poi(array("iconid" => "family.png", "title" => "Custom Icon Example", "point" => array("lat" => 40.7269, "lng" => -74.0087)));
$mymap->pois = array($mypoi_1, $mypoi_2);
echo $mymap->display();

Geocoding with PHP

If POIs are defined by street address (rather than latitude/longitude) the geocode() method must be used before the map is displayed.  This method geocodes the address and defaults the POI title and body, if they aren’t set explicitly.

For example, to create a POI using the street address “500 Chestnut St” use:

$mypoi = new Mappress_Poi(array("address" => "500 chestnut st, phildelphia"));
$mypoi->geocode();

The above code geocodes the POI every time the map is displayed, so high-traffic blogs may encounter Google’s geocoding usage limit (see the ‘Geocoding’ section for details).  If so, it may be better to generate the maps using custom fields, or use the Nominatim geocoder.

Google Styled Maps

For Google maps, use the Google styled maps wizard.  When the style is complete, click the ‘show JSON’ button in the wizard to get the style definition.  Copy and paste the JSON code into the MapPress styled maps settings.

To automatically apply the style to all maps, select the style under the ‘default style’ setting.  To apply the style to a single map or mashup, use use the shortcode parameter maptypeid, for example: [mappress maptypeid="mystyle"]

Mapbox Studio Styles

For Leaflet maps, use the Mapbox Studio online style editor to create and edit styles.  The style can be used in MapPress by entering a name and URL in the MapPress styled maps settings (note: use the ‘share’ URL from Mapbox Studio).

The new style will appear as a selection in the layers control in the MapPress editor.  To apply the style to a single map or mashup, use use the shortcode parameter maptypeid, for example: [mappress maptypeid="mystyle"]

Reference

Overriding Map CSS

The default MapPress CSS styles are in the plugin file mappress.css.  CSS styles can be overridden there, or in your theme’s style.css file, but those files will be overwritten when you upgrade the plugin or theme, respectively.

Instead, WordPress recommends creating a child theme, and making any CSS changes there.  CSS styles in child themes are safe from both theme and plugin upgrades.

To override specific settings, just include the CSS class you want to override in your theme/child theme style.css file.  Any settings there will take priority over the MapPress defaults.

For example to set a 10px margin around the map place this line in style.css:

.mapp-layout { margin: 10px; }

In some cases it may also be necessary to override all of the default CSS styles.  To do this select the checkbox “Turn off CSS” in the MapPress settings screen – but be sure to copy all of the map CSS styles from mappress.css to your theme’s style.css.

Translation Support

MapPress is fully translatable. All strings and templates are localized and can be translated using POEdit. A POEdit guide is available in the MapPress FAQ.

Leaflet map controls are displayed using the current blog language. For Google, the API defaults to the browser language, but it can be forced to a specific language by entering a value in the ‘language’ setting in the MapPress settings screen.

WPML

MapPress fully supports the WPML translation plugin. The current WPML language takes priority over other settings, and all controls and texts are localized to that language, including the Google API map controls.

When creating a WPML translation, there is an option to duplicate the content from the original post, overwriting the target (translation) post.

During duplication, MapPress will:

  1. Delete any maps in the target (translation) post
  2. Copy all maps from the original post to the translation post
  3. Update all shortcodes and Gutenberg blocks to use the new map IDs

The new maps can be edited in the translation language and will not affect the originals. This behavior can be switched off in the MapPress settings screen.

Settings

The settings screen controls defaults for the plugin.  Many settings can also be set for individual maps using the MapPress shortcode or template tags.

Underlined settings are only available for MapPress Pro.

SettingDescription
Mapping APISelect the Google or Leaflet API
Google API keyIn order to use the Google API, obtain an API key and enter it here.
Mapbox Access TokenIf you are using the Leaflet API, optionally enter a Mapbox access token to use Mapbox map tiles and Mapbox Studio custom map styles.
GeocoderIf the Leaflet API is used, select a geocoder. See the Geocoding section for details
MapPress license keyEnter your MapPress license key. You can find the key in your account.
Beta versionsSelect this checkbox to allow installation the latest versions of MapPress. It’s best to set this in development or staging systems, but not in live blogs.
Post typesSelect the post types where you plan to use the MapPress Map Editor. This applies only to the classic editor. The MapPress Map and Mashup blocks are always available in the Gutenberg editor.
Automatic displayAutomatically displays the maps attached to each post, without having to add a shortcode or insert a map block. 
Map alignmentSet a default map alignment. This applies only to the classic editor, in Gutenberg the alignment is set with the block controls.
Directions‘Inline’ shows a simple from/to form before opening directions in Google Maps. ‘Google’ sends users directly to Google Maps with the destination already selected.
POI listShow a table of POIs under the map
POI list layoutSelect a layout for the POI list. ‘Left of map’ works best in most cases.
Mini widthPixel width at which maps with a left POI list should switch to a ‘mini’ layout. In this layout, the map or list are shown separately and can be toggled by buttons at the button of the map.
SortSelect the checkbox to sort the POI list alphabetically by title.
Default zoomMapPress uses this setting to set the zoom level for POIs entered by latitude / longitude. This parameter is ignored for POIs entered as a street address or place; those POIs have a default ‘viewport’ that is used to set the zoom instead.
Open first POISet this checkbox to open the first POI when the map is displayed.
ClusteringSet this checkbox to enable marker clustering.
SearchSet this checkbox to enable the search box for mashup maps.
FilterSelect a taxonomy to use as a filter with mashup maps.
POI contentSelect what to show for the POI title and body in mashups:
-the title and body saved with the POI, or
-the title and excerpt for the post the POI is linked to.
POI clickSelect what should happen when a POI marker is clicked.
KMLsSelect whether to include KML POIs in mashup maps (for example, region outlines are often used in individual maps, but do not need to appear in mashups).
ThumbnailsCheck to automatically include featured image thumbnails in mashup POIs. The thumbnails are taken from the post each POI is linked to.
Thumbnail sizeSelect an existing thumbnail size for mashup images, or specify a size in pixels.
Popup typeWhen a POI is clicked a ‘bubbles’ opens with details about the POI. Select the standard Google InfoWindows or MapPress InfoBoxes. InfoBoxes can be styled using CSS (see the ‘mappress.css’ file)
Default iconSelect a default icon to use for all maps. Any POI that doesn’t have an icon explicitly assigned to it will use this icon.
Custom icons directoryDirectory for custom icons.
Custom iconsClick to upload custom icons from your PC.
Icon scalingOptionally select an icon size to use in maps and the POI list.
Automatic iconsUse the dropdown to automatically assign icons by post type, category, tag, or custom taxonomy.
Styled mapsIf the Google API is used, provide a style name and enter JSON directly from the Google Styled Maps Wizard. For Leaflet, enter a style name and URL from Mapbox studio. See the section on styled maps for details.
Default styleSelect a custom style to be used as the default on all maps. Custom styles can also be selected in the map editor ‘map type’ dropdown.
Geocoding fieldsSelect which custom fields to use to automatically create maps. The selected fields are combined and the resulting address is geocoded before the map is saved.
OverwriteCheck this box to overwrite an automatically-generated map when a post is published, even if the map has bee n manually edited.
Geocoding errorsIf any geocoding errors occur, the most recent errors are shown here. The errors are also stored in a custom field for each post named ‘mappress_errors’.
TemplatesClick to open the template editor to edit the templates used for POI popups and POI list rows. Maps and mashups have separate templates.
Search language For Google, the language affects map tiles, map type and zoom controls, geocoding (search results) and directions. If no language is specified, Google will use the language setting from the user’s web browser. 

For Leaflet, the language setting only controls geocoding and search results. The default map tiles are always served in their ‘native’ language, e.g. Chinese for China. Mapbox tiles can be used if you prefer English labels.

All other texts come from MapPress. See the FAQ for information on creating and editing translations.
Country For Google, the country parameter is used to bias results to a certain country only when geocoding from custom fields. For interactive searches, results are biased based on the current map viewport.

For Algolia and MapBox, this parameter restricts geocoding and interactive searches to only the entered country. For example, if the country code is set to “ES”, only results in Spain will be found.
Directions serverTo use a local Google maps server (for example “maps.google.fr” or “maps.google.de”) enter the URL here.
ScriptsMapPress normally outputs scripts in the footer, and only when a map is being displayed. Uncheck this to output scripts in the header instead. This is usually necessary if you are using third-party plugins (such as infinite scrollers) that fetch content using AJAX. These plugins typically don’t allow script output in the footer.
Map sizesEnter up to three default map sizes.  These sizes are presented as defaults in the map editor.
Force resizeResize all maps from a given size to a new size.

Shortcode Parameters

Underlined parameters are only available for MapPress Pro.

Basic Parameters

ParameterValuesDefaultDescription
centerlat, lngblankSpecify a center for the map using a latitude/longitude, for example “-32, 22”.  If blank, the center saved with the map will be used. For mashups and maps with no saved center, the map is automatically centered and zoom to show all of its POIs.
heightpixels or % Map height, for example “50%” or “400px”
widthpixels or % Map width
zoom1-21 Map zoom

Other Parameters

ParameterValuesDefaultDescription
alignmentcenter
default
left
right
defaultMap alignment
hideEmptybooleanfalseHide empty mashup maps (maps with no POIs)
initialOpenDirectionsbooleanfalseOpen the directions form when the map is first displayed
initialOpenInfobooleanfalseOpen the first POI when the map is first displayed
mapTypeIdhybrid
roadmap
satellite
terrain
blankMap type to display.  You may also use a custom style name if you have created custom styles in the MapPress Pro settings.
namestringblankSet the name for the map. If no name is provided, the first map on the page is automatically named ‘mapp0’, the next is named ‘mapp1’, and so on.
poiListbooleanfalseDisplay the POI list under the map

Filters and Actions

Filters

mappress_tile_providers ( $providers )

Used to add custom map tile providers.  The $providers parameter contains an array of provider data.  Enter entry has the provider name as a key and an array of attributes for that provider.   

Providers generally specify an array of attributes necessary to access their tiles, including a formatted URL.  The default providers are ‘osm’ (OpenStreetMap) and ‘mapbox’.  As an example, this is the entry for OSM:

'osm' => array(
'attribution' => 'Map data (c)<a href="https://openstreetmap.org">OpenStreetMap</a>',
'url' => 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
)

mappress_poi_iconid ( $iconid, $poi )

Called once for each POI, just before the map is displayed.  Used to set a specific icon for each POI.  The $iconid parameter contains the icon ID of the icon that would normally be displayed, and $poi contains the POI object.

Actions

mappress_map_display ( $map )

Called once just before a map is displayed.  The map is passed by reference, so it can be modified – for example to add or remove POIs, change icons, etc.

mappress_sort_pois ( $map )

This action is called just before a map is displayed.  You can use it to apply your own sorting routines.  For example, to sort POIs by title in descending order, add the following code to the functions.php file:

function mysort($map) {
   usort($map->pois, 'reverse_sort');  
}

function reverse_sort($a, $b) {
   return strcasecmp($b->title, $a->title);  
}

add_action('mappress_sort_pois', 'mysort');

mappress_save ( $map )

This action is called after a map is saved to the database.

mappress_delete ( $map )

This action is called just after a map is deleted from the database.

Examples

Generating Maps When a Custom Field Changes

To trigger an update every time the field ‘myfield’ changes, add this to your functions.php:

function my_meta_update($meta_id, $object_id, $meta_key, $meta_value) {
    if ($meta_key == 'myfield')	
	do_action('mappress_update_meta', $object_id);
}

add_action('added_post_meta', 'my_meta_update', 10, 4);
add_action('updated_post_meta', 'my_meta_update', 10, 4);
add_action('deleted_post_meta', 'my_meta_update', 10, 4);

Map Generation for Formidable Forms

If you’re using the Formidable Forms plugin, you’ll need to use this approach to trigger the map update when a form changes:

function my_meta_update($entry_id, $form_id) { 
    // Replace '17' with your form ID 
    if($form_id == 17) { 		
	//get ID of post to be created global 
	global $frmdb; 
        $post_id = $frmdb->get_var( $frmdb->entries, array('id' => $entry_id), 'post_id'); 

	// Update the map for that post 
	do_action('mappress_update_meta', $post_id); 
    } 
} 

add_filter('frm_after_create_entry', 'my_meta_update', 50, 2);

Open a POI Using Javascript

The method getPois() can be used to retrieve an array of all of the Map’s POIs.  The open() method can be used to open a POI.  For example, to open the second POI (1) on the first map (‘mapp0’):

var pois = mapp0.getPois();
pois[[1]].open();

Or:

mapp0.getPois()[[1]].open();