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:
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 and delete the original.

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.

Service	Terms of Service	Free	Registration	Usage Limit	Accuracy
MapBox	Link	No	Yes	100,000 per month	Exact
Google	Link	No	Yes	Yes	Exact
Nominatim	Link	Yes	No	None	Exact 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 and GPX Files

To incorporate a KML or GPX file into your map, simply enter the file’s URL in the ‘search’ field in the map editor using this format https://myserver/mykml.kml. Some sample files are listed below.

Limitations when working with KML files

• KML/GPX files are usually protected by CORS, a security feature that prevents files from being loaded from other domains. That means your server can’t use files hosted on another server.
• Google doesn’t allow KMLs to be hosted on a localhost server.

Google KML/GPX

1. Transfer the file to a web-accessible directory on your hosted web server (such as the main WordPress directory or the /uploads directory).
2. Use the URL for that file for maps on both the hosted server and localhost.

Note that Google also imposes strict limits on KML/GPX file size and content.

Leaflet KML/GPX

Leaflet uses the Omnivore library from MapBox to display KML and GPX files:

• Omnivore has no size or content limits
• It allows KML/GPX files to be hosted on localhost servers
• However, files on hosted servers can only be read from the server itself due to CORS restrictions.

To use a KML/GPX file with Leaflet:

1. Copy the KML/GPX file you want to use to your localhost server and use that URL in your maps during development.
2. When publishing your blog, make sure the KML/GPX files are also available on the hosted server. If both servers contain the files in the same subdirectory, there’s no need to modify KML POIs in your maps.

Sample KML Files

This KML showing Chicago transit lines is publicly available from Google:

https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml

This file shows the outlines of US states:
https://developers.google.com/kml/documentation/us_states.kml

The census provides additional KML files for each US state:
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.

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 . '"]'); 
?>

Mashup Search

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 ‘&’
• {{{ ... }}} : 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>
<# } #>

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

Importing Maps

The MapPress ‘Import’ menu page can be used to create maps from a CSV (comma-separated values) file. The file may be local (such as Excel), or online from Google Sheets. A sample file is shown below:

This kind of import is useful for creating stand-alone maps. To create maps that link to WordPress posts (such as a directory site) see the section on generating maps from custom fields below.

The file must contain one row per POI. The ‘mapid’ column is optional. It can be used to import multiple maps at once (for example, mapid “1”, mapid “2”, and so on.

Warning: if the mapid column is used, and the option ‘use map IDs from file’ is set during the import, any existing maps with those IDs will be overwritten.

Tips:

• Each POI must have either a ‘lat’ and ‘lng’ value, or an address. If no lat,lng coordinates are provided, the address will be geocoded. If coordinates and an address are provided, the coordinates are used to locate the POI, but the address will be used when requesting directions to it.
  
• MapPress isn’t suitable for bulk geocoding. If the file has more than a hundred lines, it will be cheaper and faster to use a specialized online bulk geocoding service.
  
• If the POI title or body contain special characters, such as accents or alternative character sets, try using a “UTF-8” file format. For example, Excel can save files as “CSV UTF-8”. Characters that aren’t recognized will appear as question marks.
  
• For default icons, specify only the name, such as “blue-dot”. For custom icons, use the name and extension, such as “myicon.jpg”.
  
• The icon ID for any icon can be found by hovering over it in the MapPress icon editor. On the MapPress settings screen, click on the icon in the ‘Default icon’ setting to bring up the editor and see all of the icons.

Generating Maps From Custom Fields

MapPress Pro can automatically generate maps from custom fields. This is useful if your site already has address data stored in custom fields or if you need to import posts with map data from a file. Any CSV importer plugin can be used to create the posts and a map for each post.

Each map generated from custom fields contains a single POI. To specify the POI’s location, custom fields must be available with either an address, or a latitude and longitude.  Select the fields to use on the MapPress settings screen in the ‘Geocoding’ section. If multiple address fields are used, they will be concatenated together to form the address for the POI.

Whenever a post containing the selected fields is published or updated, a map is automatically generated and attached to the post. 

Custom fields may also be specified for the POI title, body and icon. Note that it’s often easier to ‘automatic icon’ settings to automatically assign icons by taxonomy rather than setting the icon for each post.

If errors occur during map generation, they are shown in the MapPress settings screen. Error details are stored in the post, in 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" => "38.9027,-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.

Custom Map Tiles

If you have a custom map, you can replace the map tiles.

Custom tiles for Google

Google custom tiles hasn’t been implemented yet. If you need this functionality, please contact me and describe your use case (for example, image overlay on normal map or completely replacing the map tiles).

Custom tiles for Leaflet

For Leaflet, PHP filter mappress_options can be used override the MapPress translations and options before the are sent to the map, and replace the tile providers and allowed styles (tilesets).

For example, to replace the standard tile providers and styles use the code below in your functions.php:

function myfilter($l10) {
    $l10n['options']['tileProviders']['custom'] = array(
        'attribution' => ['<a href=https://openstreetmap.org target="_blank">&copy; OpenStreetMap</a>'], 
        'url' => 'https://{s}.tile-cyclosm.openstreetmap.fr/cyclosm/{z}/{x}/{y}.png', 
        'imageUrl' => null      // Use this if you have a thumbnail image for the tileset
    ); 

    $l10n['options']['standardStyles'][] = array(
        'id' => 'custom1', 
        'type' => 'standard', 
        'provider' => 'custom', 
        'name' => __('Custom')
    );
    return $l10n;
}

add_filter('mappress_options', 'myfilter');

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.

Setting	Description
Mapping API	Select the Google or Leaflet API
Google API key	In order to use the Google API, obtain an API key and enter it here.
Mapbox Access Token	If you are using the Leaflet API, optionally enter a Mapbox access token to use Mapbox map tiles and Mapbox Studio custom map styles.
Geocoder	If the Leaflet API is used, select a geocoder. See the Geocoding section for details
MapPress license key	Enter your MapPress license key. You can find the key in your account.
Beta versions	Select 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 types	Select 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 display	Automatically displays the maps attached to each post, without having to add a shortcode or insert a map block.
Map alignment	Set 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 list	Show a table of POIs under the map
POI list layout	Select a layout for the POI list. ‘Left of map’ works best in most cases.
Mini width	Pixel 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.
Sort	Select the checkbox to sort the POI list alphabetically by title.
Default zoom	MapPress 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 POI	Set this checkbox to open the first POI when the map is displayed.
Clustering	Set this checkbox to enable marker clustering.
Clustering MaxZoom	Disable clustering beyond when the map is zoomed beyond this level
Clustering Spiderfy	Enable 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).
Search	Set this checkbox to enable the search box for mashup maps.
Search radius	Search 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 box	Limit searches to the give bounding box (Leaflet only, not supported by Google).
Filter	Select a taxonomy to use as a filter with mashup maps.
POI content	Select 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 click	Select what should happen when a POI marker is clicked.
KMLs	Select 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).
Thumbnails	Check to automatically include featured image thumbnails in mashup POIs. The thumbnails are taken from the post each POI is linked to.
Thumbnail size	Select an existing thumbnail size for mashup images, or specify a size in pixels.
Popup type	When 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 icon	Select 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 directory	Directory for custom icons.
Custom icons	Click to upload custom icons from your PC.
Icon scaling	Optionally select an icon size to use in maps and the POI list.
Automatic icons	Use the dropdown to automatically assign icons by post type, category, tag, or custom taxonomy.
Styled maps	If 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 style	Select 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 fields	Select 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.
Overwrite	Check this box to overwrite an automatically-generated map when a post is published, even if the map has bee n manually edited.
Geocoding errors	If 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’.
Templates	Click 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 server	To use a local Google maps server (for example “maps.google.fr” or “maps.google.de”) enter the URL here.
Scripts	MapPress 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 sizes	Enter up to three default map sizes.  These sizes are presented as defaults in the map editor.
Force resize	Resize all maps from a given size to a new size.

Shortcode Parameters

Underlined parameters are only available for MapPress Pro.

Basic Parameters

Parameter	Values	Default	Description
center	lat, lng	blank	Specify 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.
height	pixels or %		Map height, for example “50%” or “400px”
width	pixels or %		Map width
zoom	1-21		Map zoom

Other Parameters

Parameter	Values	Default	Description
alignment	center default left right	default	Map alignment
hideEmpty	boolean	false	Hide empty mashup maps (maps with no POIs)
initialOpenDirections	boolean	false	Open the directions form when the map is first displayed
initialOpenInfo	boolean	false	Open the first POI when the map is first displayed
mapTypeId	hybrid roadmap satellite terrain	blank	Map type to display.  You may also use a custom style name if you have created custom styles in the MapPress Pro settings.
name	string	blank	Set 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.
poiList	boolean	false	Display the POI list under the map
scrollwheel	boolean	true	Enable/disable scroll wheel zoom (Leaflet)
scrollWheelZoom	boolean	true	Enable/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 many popular front-end forms plugins.

Formidable Forms

It’s easy to create MapPress maps with Formidable Forms! Please see this page for detailed setup steps.

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’:

Other Examples

Open a POI Using Javascript

You may need to open a map marker from your own code. If so, the method getPois() can be used to retrieve an array of a Map’s POIs, and the poiOpen method can be used to open them. For example, to open the second POI (number 1) on the first map (‘mapp0’), use:

const poi = mapp0.getPois()[1];
mapp0.poiOpen(poi);