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
  • Comparable functionality to Google if Mapbox is used
  • Traffic, bicycling and transportation overlays and shape drawing tools are not available

Mapbox and Leaflet

If you’re using Leaflet, it’s strongly recommend to sign up with Mapbox.

The default map tiles for Leaflet are from OpenStreetMap. They’re plain and unattractive, and the default geocoder is Nominatim, which isn’t very accurate. .

Mapbox provides:

  • Detailed map tiles,
  • An accurate geocoder
  • Styled maps

To use Mapbox, just get a Mapbox access token and enter it in the MapPress settings. Mapbox services are free for most sites because they offer a generous free usage tier.

Google API Keys

Google Maps require a Google API key. Click the link to learn how to create one:
How to Get A Google Maps API Key

For Leaflet maps, no API keys are needed, unless you’re using the Google geocoder.

Google API key issues

If maps aren’t displaying after entering the API key, check the browser’s JavaScript console for any errors (F12 for most browsers).  If there’s a message saying the API key is invalid, get a new one using the steps in Get a Browser API key

A common error is having the maps API loaded multiple times. See the Troubleshooting FAQ section if there are console errors indicating the API has been loaded more than once.

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.

If you’re using Leaflet, it’s strongly recommend to sign up with Mapbox.

  • The Google geocoder is excellent, but requires setup of a Google API key
  • MapBox is also excellent. It requires a Mapbox access token, which is easy to set up and has generous free usage limits.
  • Nominatim is the default geocoder. It’s free and has no usage limits but the geocoding is poor. In many locations it only provides ‘street level’ accuracy: if a house address is entered, it will return the middle of the nearest street.
ServiceTerms of ServiceFreeRegistrationUsage LimitAccuracy
MapBoxLinkNoYes100,000 per monthExact
GoogleLinkNoYesYesExact
NominatimLinkYesNoNoneExact in some Locations, street elsewhere

Creating a Map

MapPress supports both the Gutenberg Editor and the Classic Editor, making it easy to create a map while editing a post. Maps created in this way are linked to the underlying post, and can be displayed in ‘mashup’ maps.

When MapPress editing popup opens, it displays the Map Library, a list of all maps and which post they’re linked to – it’s similar to the Media Library in WordPress. From the Map Library, maps can be selected to edit or delete.

The Map Library can also be opened directly from the MapPress menu, without first going to the WordPress post editor.

Create 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.

Create 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

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). 

Most KML files are protected by CORS, a security feature that prevents resources from being loaded by other domains. If you see an error when reading a KML file on a remote server, it’s almost certainly due to CORS restrictions.

To use a KML, you’ll need to save it on your computer, then upload it to your blog using the WordPress media uploader.

Here’s a sample file you can use for testing:

https://developers.google.com/kml/documentation/us_states.kml

Save the file to your computer, then upload it to your blog. Copy the URL on your blog, and enter it in the MapPress search box. You should see the outlines of US states.

Google KMLs

Google has strict limits on KML files:

  • Maximum file size <= 3MB
  • Maximum uncompressed KML file size <= 10MB
  • Maximum number of features <= 1,000
  • There is also a limit on the number of KML Layers that can be displayed on a single Google Map. If you exceed this limit, none of your layers will appear on the map, and an error will be reported in the browser’s JavaScript console.
  • Full limitation details are available here

Leaflet KMLs

Leaflet KMLs are processed using the Omnivore library from MapBox. There are some important Omnivore features to be aware of:

  • Files can only be read from CORS-enabled web sites. In practice, there are few KML sources available like this so it’s usually best to save the file locally and then upload it to your own server.
  • KML/KMZ files can be uploaded to your server using FTP or the WordPress media uploader
  • Omnivore can read KML files from localhost without any issues

State KML Files

For US state outlines, the census has a complete set of KMLs at various resolutions (and various file sizes):

https://www.census.gov/geographies/mapping-files/time-series/geo/kml-cartographic-boundary-files.html

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.

Icons

MapPress Pro includes an icon editor that can be used to create millions of custom icons. The editor is available in the MapPress settings screen and in the map editor.

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.

Creating New Icons

Click the ‘new icon’ button to open the icon editor. Here, you can select one of the predefined shapes, a color and an (optional) icon to show inside the shape. Two fonts are supported for icons: ‘Map Icons’ (a set of default icons) and Google Material Icons.

Uploading Custom Icons

Click the ‘upload icons’ link in the bottom-right of the icon editor to upload custom icons.

FTP Custom Icons

It’s usually easiest to upload icons using the icon editor, but it’s also possible to upload using FTP.

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 upload directory. 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.

Automatic Icons

Icons can be automatically assigned to maps using the Automatic Icons setting in the MapPress settings screen.

Select a taxonomy (categories, tags, or a custom taxonomy) to use. For each taxonomy term (the ‘key’ column) an icon can be selected. For maps attached to posts with that term, all POIs will show the selected icon.

Automatic icons only show in the blog front-end. In the editor, you’ll still see whatever icon the POI was saved with.

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: https://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:

https://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.

By default, markers are shown within a 200km radius the search result, but this can be changed in the MapPress settings.

Search Biasing

Search results are always biased towards locations within the current viewport. For example, if a map of the world is displayed searching for “Paris” will show “Paris, France” as the first item in the list. If the map is zoomed in on Texas, the first result is “Paris, TX”.

Search Restriction

Searches can be restricted by country, in which case only results from that country will be displayed.

For the Mapbox and Nominatim geocoders, a bounding box can also be set to restrict searches to a specific geographic area. For example, to restrict searches to only the New York City area, enter “-75.32776,40.12009,-72.66632,41.31289”.

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-popup.php – map POI popup
  • map-item.php – map POI list row
  • mashup-popup.php – mashup POI popup
  • mashup-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, pick a style from Snazzy Maps and copy 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. 

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 the style URL (use the ‘share’ or ‘preview’ URL that starts with mapbox://).

The new style will appear as a selection in the style control in the map editor. 

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.

Learn more about WPML and its Advanced Translation Editor.

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.
Clustering MaxZoomDisable clustering beyond when the map is zoomed beyond this level
Clustering SpiderfyEnable or disable the “spiderfy” feature that explodes clusters into individual POIs at the maximum zoom (Leaflet only, this is not supported by the Google marker clusterer).
SearchSet this checkbox to enable the search box for mashup maps.
Search radiusSearch radius around the searched center. Note that this is the minimum radius. If a larger area is searched, like “USA”, then the radius is ignored.
Bounding boxLimit searches to the give bounding box (Leaflet only, not supported by Google).
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
scrollwheelbooleantrueEnable/disable scroll wheel zoom (Leaflet)
scrollWheelZoombooleantrueEnable/disable scroll wheel zoom (Google)

Filters and Actions

Filters

mappress_filter_label ( $html, $value, $label, $iconid)

Used to override the term labels in the mashup filters dropdown. The parameters are:

  • html – the MapPress generated html for the term label
  • value – the term slug
  • label – the term name (the display label in WordPress)
  • iconid – the icon to display for the term, if automatic icons are configured

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.

Frontend Forms

MapPress is compatible with a number of popular front-end forms plugins.

Advanced Custom Fields (ACF)

MapPress fully supports ACF. There are two ways to handle ACF data:

  1. Generate MapPress maps from ACF fields
    or
  2. Automatically include ACF maps in MapPress mashups

Regardless of which approach is used, the first step is to set add up your theme to display ACF fields and provide a Google Maps API key to ACF, as described here.

Generate MapPress Maps from ACF Fields

If you plan to use MapPress to edit maps on the backend, you can generate MapPress maps from ACF text or map fields as described in the geocoding section. For example, a form might contain several address fields, which can be configured to generate a MapPress map when the form is saved.

Only text and map fields are supported. Other types won’t work, such as checkboxes, textareas, editors, etc.

To use a map field, just link the ACF map field name to the MapPress ‘Address line 1’ field. When the ACF form is saved, a MapPress map will be generated from the map location. Here’s how it would look if the ACF map field is named ‘acfmap’:

Include ACF Fields in Mashups

If you plan to use ACF to enter and maintain your maps, it’s not be necessary to generate a MapPress map from the ACF form. Instead, the ACF map locations can be included directly in MapPress mashups. This allows you to leave the map data in ACF, while still using the search and filter functionality of MapPress.

Just enter the ACF map field name in the ‘Frontend Forms’ part of the MapPress settings. When a mashup is displayed, the ACF map locations for the selected posts will be included.

Here’s how it would look if the ACF map field is named ‘acfmap’:

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);

Examples

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();