MapPress Documentation

 Table of Contents

What’s New

MapPress

Compatibility and Installation

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

Picking a Mapping Engine

MapPress supports two mapping engines: Leaflet and Google.

The engine selected controls which map ’tiles’ (backgrounds) are displayed and how addresses are geocoded (matched to latitude/longitude coordinates).

  • Google – Google Maps look great, but Google requires billing information and a complicated API key.  Google has strict free usage limits, so it can be very expensive for high-traffic sites.
  • Leaflet – Leaflet is a popular free, open-source alternative to Google.
    The leaflet engine uses geocoding from Algolia.
    By default Leaflet uses plain map tiles from Open Street Map (OSM).  M
    ore detailed map tiles are available from Mapbox (sign up to get a Mapbox access token).  Mapbox isn’t free but their free usage level is higher than Google and their paid usage is less expensive.  

Leaflet Limitations

The current MapPress implementation of Leaflet has some limitations:

  • Google Traffic, bicycling and transport overlays are not available
  • Inline directions are not available.  Directions are provided from Google Maps.
  • Drawing tools for shapes and polygons are not provided.  If shapes are created using a Google map, they will be converted to markers in Leaflet.

Creating Your First Map

MapPress is easy to use.  The steps to create a map are:

  1. Edit a post and use the MapPress Map Editor to create a map
  2. Add markers or shapes (called Points of Interest, or “POIs”) to your map
  3. Add the MapPress shortcode to your post

Create a Map

After you activate MapPress.  You will notice a MapPress ‘meta box’ has been added in the WordPress post editor.

If you already have some maps you’ll see an initial list of maps.  Click a map to edit it, or click the “new map” button to create a new 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:  click one of the links to choose a default size or enter a custom size.  Sizes may be in pixels or percent, for example “425” or “100%”

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 your map.  The map will also be saved if you publish or preview a post or page.

Cancel button: cancel any map edits

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

Enter a POI

To create a new POI, enter an address, place, or business into the search box.  You may also enter a latitude/longitude in the format “lat, lng”, or the URL for a KML file (MapPress Pro only).

For example, enter “1600 Pennsylvania Ave NW, Washington, DC” for the White House.

Click the POI to edit its text in the popup.  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

Use the map types control in the upper-right to set a map type: you may choose ‘map’ for a roadmap or ‘satellite’ for satellite imagery.

Save the Map

When the map is saved it will ‘remember’ its map type, zoom and center, and will be displayed with those settings by default.  You can override the settings in the shortcode.

Save the map now by clicking the ‘save’ button.

Insert the Shortcode

Once a map has been saved you can insert it into your post using the [[mappress]] shortcode.  Click the map you just saved to edit it, then click somewhere in your WordPress post.  Then click the ‘insert into post’ button to insert the shortcode at that point.

Adding POIs

Creating POIs Using Shapes

(MapPress Pro only) For Google Maps, the the shapes toolbar at the top of the map can be used to create POIs represented as lines, polygons, circles and rectangles.  When drawing a shape, the shape can be completed by clicking on its last point again.

This feature is not yet available for Leaflet maps.

Creating POIs From KML Files

POIs can be created for KML files.  To add a KML file, enter its URL in the ‘search’ field (where you would normally enter the POI’s address).  To test this:

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

 

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

Sorting

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

Dragging POI Markers

Sometimes it’s impossible to exactly locate a POI using a street address.  In this case you can click the POI’s marker on the map and drag it to the correct location.

POIs saved this way do not have a street address, they have only latitude/longitude coordinates.

Shortcodes

The simplest form of the shortcode displays the first map in the 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"]]

Map Sizing for Mobile Devices and Responsive Themes

For mobile devices or ‘responsive’ themes it is often required to resize a map when browser window size changes.

MapPress makes this easy.  The map width can be specified as a percentage in the map editor or the shortcode.  Height usually remains fixed because most web pages do not have a fixed height.  For example:

[[mappress width="100%" height="400"]]

Normally the map center does not change when it is resized.  To force the map to re-center whenever the window size changes, use the shortcode parameter adaptive, or select the “Recenter maps when window is resized” checkbox on the MapPress settings screen.  For example:

[[mappress width="100%" height="400" adaptive="true"]]

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

Tip: 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 lets you set a different icon for each marker.  You may use a standard icon (over 200 are included) or a custom icon you’ve created yourself.

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

image_thumb7_thumb1

You will see a list of icons.  Click an icon 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.

Tip: if you change the default icon on the settings screen, any existing POIs assigned to the default icon will be updated.

image_thumb12_thumb1

Custom Icons

The 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 uploads directory, but you can check the correct icons directory for your blog in the MapPress settings screen.

To add your own icons, just copy them to the custom icons directory.

Icons must be .png or .gif files.  They are usually 32×32 pixels, although you can also use larger sizes.  There are many places on the web where you can find pre-made custom icons or icon generators. For example, this site has over 500 custom icons: http://mapicons.nicolasmollet.com.

Mashups

Mashups combine multiple maps into a single larger map.

To create a mashup you specify a query for which posts to display.  MapPress reads all of the matching posts and combines all of the map locations in those posts on a single mashup map.

The mashup query can find a single post, all posts, or posts matching certain criteria, like all posts for a specific tag or category.

For example, you might have posts containing business locations.  Each post contains some information about the location and a map of that location.  A mashup map can be used to combine all of the locations onto a single map.

Mashups can be inserted into posts, pages and templates using a shortcode, template tag or widget.

Mashup Shortcode

The most basic version of the shortcode is just

[[mashup]]

This will create a mashup map of the currently displayed posts.

Tip: always put the shortcode on its own line (WordPress requires this).

Mashup Queries

Almost any query can be entered for the show_query parameter. MapPress understands the format WordPress uses for the query_posts function.

You can find many query examples in the WordPress Codex Article About Query Parameters.

The parameters used in the MapPress shortcodes are what WordPress calls ‘query-string’ style parameters, rather than PHP arrays: Codex Article About Query String Parameters.

Testing Queries

To test if a query is working, you can usually type the query right into your blog’s URL to test it.

For example, assume your blog is at http://myblog.com and you want to query for posts with category name ‘beta’.  You can type this into your browser to test the result:

http://myblog.com/?category_name=beta

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"]]

Tip: WordPress will normally only return one blog “page” of results.  To get all posts that match your criteria, use “posts_per_page=-1”

[[mashup query="posts_per_page=-1&post_type=post"]]

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 first 5 posts in category “mycat”:

[[mashup query="posts_per_page=5&category_name=mycat"]]

Show posts for custom post type “business”:

[[mashup query="post_type=business"]]

When entering a query argument with multiple values (an array), just separate the values by commas. For WordPress shows the query_posts syntax for the first 5 posts in tag 37 and 47 using an array:

query_posts(array('posts_per_page' => 5, 'tag__and' => array(37,47)));

To use that query in a mashup shortcode, write it like this:

[[mashup query="posts_per_page=5&tag__and=37,47"]]

Show posts assigned to category 1 or category 3:

[[mashup query="category__in=1,3&posts_per_page=-1"]]

Show posts assigned to both category 1 and category 3:

[[mashup query="category__and=1,3&posts_per_page=-1"]]

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

[[mashup query="meta_key=color&posts_per_page=-1"]]

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

[[mashup query="meta_key=color&meta_value=blue&posts_per_page=-1"]]

Queries to Set the Sort Order

You can use the WordPress order and orderby parameters in queries to sort your posts (and POIs) by various fields including author, date, etc.  For example to sort all posts by date, descending:

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

Queries Using Custom Taxonomies

WordPress allows complex taxonomy queries using arrays.  Unfortunately there is almost no documentation about how to enter them in a query string, but it is possible.  Here are some examples.

Custom taxonomy ‘hotels’ with term value ‘budget’:

[[mashup query="hotels=budget&posts_per_page=-1"]]

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

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

This excellent article has additional examples about custom taxonomy queries:

http://thereforei.am/2011/10/28/advanced-taxonomy-queries-with-pretty-urls/

Mashup Parameters

See the shortcode parameters reference for a list of parameters.

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

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

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

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

 

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

MapPress Templating

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

JavaScript Templates

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

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

Customizing JavaScript Templates

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

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

PHP Code

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

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

Template Variables

Template variables are output using the underscore.js template engine 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.

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

posts_per_page=-1&category_name=cat1

Geocoding and 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 using TurboCSV.

To use this feature, you will need to custom fields containing 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.  You may also optionally specify fields for the POI title, body and icon.

When a post containing those fields is published or updated, a map will automatically be generated.  The map will have a single POI at the specified location.

Any errors that occur during map generation will be written to the custom field mappress_errors.

Tip: The WordPress Codex explains how to create custom fields. To create a custom field you must actually add it to at least one post and save that post.  One way to do this is to create a single post with dummy values for the custom fields.

Geocoding

For maps generated using an address custom field, the address must be ‘geocoded’ (converted to latitude/longitude coordinates) before the map can be displayed.

Geocoding is slow, up to about 1 second per address, so MapPress saves the result with the map.  This allows for faster map display than geocoding the POI each time the map is displayed.

Both Google and Nominatim geocoding servers are supported.  You must select at least one server in the MapPress settings screen.  If both are checked, the plugin will try Google first.  If Google returns an error (for example a geocoding limit as described below), it will try Nominatim instead.

Google is generally more accurate but it has a usage limit of about 2,500 geocoding requests per day.  Once that limit is exceeded all geocoding will be rejected: generated maps will show a location at lat/lng (0,0), which is in the ocean near Africa, and you will see error messages in the custom field mappress_errors.

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

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

  • 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 Nominatim, which currently has no usage limits.

Manually Editing Generated Maps

A map that has been generated automatically can be edited manually, just like any map you created yourself.

The map will normally re-generated if the post is published or updated again – overwriting any manual changes.  To prevent this, uncheck the setting ‘Regenerate the map every time its post is published’ on the MapPress settings screen.

Events for Generating Maps

MapPress generates maps only when a post is saved or published.  Some plugins or themes update custom fields directly, without saving the containing post.  For example, ‘forms’ plugins often take user input from a form and save it directly to custom fields

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();
Tip: If you specify a center, you must also specify a zoom, and vice-versa.  Both parameters are required in order to show the map.

Icon IDs

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

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

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

Geocoding with PHP

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

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

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

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

Google Styled Maps

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

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

Mapbox Studio Styles

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

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

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.

Settings

The settings screen controls defaults for the plugin.  Some of the 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
Post types Select the post types where you plan to use the MapPress Map Editor
Automatic map display Automatically display maps in each post without adding a shortcode.  If a shortcode is present in a post this setting is ignored.
Directions Select the type of directions you want to offer.  Directions links appear in map POI Popups.

  • ‘Inline’ displays directions in your blog
  • ‘Google’ opens directions in a new Google Maps window
  • ‘None’ suppresses the directions links
Map alignment Alignment of the map relative to surrounding text:

  • ‘default’ displays the map left-aligned
  • ‘center’ centers the map on the page
  • ‘right’ aligns the map right and lets text flow around it
  • ‘left’ aligns the map left and lets text flow around it
Open first POI Open the first POI automatically when the map is displayed
POI list Show a table of POIs under the map
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.
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)
Mashup POI body Select what to show for the POI title and body in mashups:

  • The title and body saved with the POI
  • The title and excerpt for the post the POI is linked to
Mashup POI click Select what to do what a mashup POI is clicked:

  • Open the POI’s popup (the default)
  • Go directly to the post the POI is linked to
Mashup 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 or specify a size in pixels. Note that using a default size is much faster than resizing on display.
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.
Styled maps Provide a style name and enter JSON directly from the Google Styled Maps Wizard.
Default style Select a custom style to be used as the default on all maps.

Note that you can also add the style to the list of map types by selecting it in the ‘map types’ setting. In this case users can select the map style just like the standard types (roadmap, satellite, etc.)

Geocoders Enter the geocoders to use for geocoding. Google has strict usage limits. Nominatim is sometimes less accurate but has no limits.

You may select both geocoders. MapPress will try Google first. If there is no result (for example if you have reached your usage limit), then Nominatim will be used.

Geocoding fields Select custom fields to use to automatically create maps.
Language Select a language.  For Google, this affects that map tiles, map type and zoom controls, geocoding (search) results and directions. If not specified, Google will use the language setting in the user’s web browser.  Google provides a spreadsheet with a list of supported languages.

For Leaflet, the language setting controls only geocoding results.  Map tiles are always served in their ‘native’ language, e.g. Chinese for China.  You can use Mapbox tiles if you prefer English.

All other texts come from MapPress.  See the MapPress FAQ for information on creating and editing translations.

Country Provide a default country to use as a preference for searches.  For example, if you enter ‘Toledo’ Google will normally display Toledo, Ohio. But if you set the country code to ‘ES’ (for Spain) it will show Toledo, Spain.
Directions server If you have selected ‘Google’ for directions, you may enter a local Google maps server (for example “maps.google.fr” or “maps.google.de”) to obtain directions in your own language.
Scripts Check this box to load MapPress scripts in the footer (the default).  Uncheck it if using other plugins that use AJAX to fecth content (these plugins typically don’t call the WordPress theme footer function).
API key Enter your Google Maps API key.  See the FAQ for tips on setting it up.
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

Filters and Actions

Filters

mappress_poi_iconid ( $iconid, $poi )

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

Actions

mappress_map_display ( $map )

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

mappress_sort_pois ( $map )

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

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

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

add_action('mappress_sort_pois', 'mysort');

mappress_save ( $map )

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

mappress_delete ( $map )

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

Examples

Generating Maps When a Custom Field Changes

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

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

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

Map Generation for Formidable Forms

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

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

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

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

Open a POI Using Javascript

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

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

Or:

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