MapPress Documentation

This is the documentation for the current stable version of MapPress and MapPress Pro. 

Table of Contents


MapPress

Compatibility and Installation

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

Creating Your First Map

MapPress is easy to use.  Basically, the steps 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, edit a WordPress post or page.  You will notice a new ‘meta box’ has been added for the MapPress Map Editor.

If you already have some maps you’ll see an initial list of maps.  Click a map to edit it. 

Since we don’t have any maps yet, click the “new map” button to create a new map. 

image_thumb3

 

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

My location link:  click to enter your current location into the map.  This is called ‘geolocation’.  The accuracy of the location is determined by your browser (or other device).

Center map link: click to re-center the map between all of the map markers

Enter a POI

To create a new POI, enter a place into the search box.  Places may be entered as a street address, country, state, place or monument.  You may also enter a latitude/longitude in the format “lat, lng”, which will place the marker at that exact location.  Or, enter it as “(lat, lng)” to place the marker at the nearest street address.

For example, all of these can be used to find the White House:

1600 Pennsylvania Ave NW, Washington, DC 
White House
38.898954,-77.036359
(38.898954,-77.036359)

Note that in the last version the lat/lng was entered in parentheses.  In this case MapPress will match it to the nearest street address: “1535-1561 Pennsylvania Ave NW”.

Enter a POI now.  Once the POI is created it will appear in the list on the left.

Click the POI to edit its text (this is called an ‘InfoWindow”), then save the POI.

image_thumb5

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

Inserting Images and Links

Images and links may be inserted into the POI body using the visual editor. 

In the HTML editor enter an <img> tag for images.  Be sure to specify the image width and height so Google can correctly size the POIs InfoWindow.  For example:

<img src='http://www.google.com/images/logos/ps_logo2.png' style='width:100px;height:100px'>

Links can be added with HTML anchor <a> tags.  For example, to link the Google image to www.google.com use:

<a href='www.google.com'><img src='http://www.google.com/images/logos/ps_logo2.png' style='width:100px;height:100px'></a>

Creating POIs Using Shapes

(MapPress Pro only) Use the shapes toolbar at the top of the map 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.  

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).  Here is an example KML file:

http://kml-samples.googlecode.com/svn/trunk/kml/Region/polygon-min-max.kml

There are other examples available at http://code.google.com/p/kml-samples/

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

If you have multiple POIs you can drag and drop them in the Map Editor to change their sort order.  Normally the order is irrelevant because MapPress will sort the POIs alphabetically by title.  But you can turn off the default sorting using the shortcode parameter sort=”false” (see the shortcode parameter reference).

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, while suppressing the directions link:

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

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

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

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 should generally be 32×32 .png files, 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.

Icon Shadows

As part of Google’s ‘visual refresh’ the Maps API no longer supports icon shadows.

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

MapPress by default sorts POIs by title. 

You can turn off the default behavior using the shortcode parameter sort to “false”.

If the default sort is turned off, you can use the WordPress order and orderby parameters in queries to sort your posts by various fields including author, date, etc.  For example to sort all posts by date, descending:

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

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

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 

Templates

MapPress Pro maps are displayed using Template Files, which can be used to adjust the formatting and content of various parts of the map.  The idea is very similar to your WordPress theme, which contains separate files for the page header, body, footer, and so on.

The default templates are in directory /templates.   To modify a template, just copy it form the plugin directory to your theme’s (or child theme) directory and modify it there.  WordPress overwrites all theme files when a theme is upgraded, so you should always use a child theme if possible. 

The template files are:

  • map_layout.php – the general layout of the map elements (the map itself, the POI list, and directions)
  • map_directions.php – the directions form
  • map_poi_list.php – the POI list
  • map_poi.php - the contents of the map POI InfoWindows

You may override the default files names for any map by using shortcode parameters.  See the shortcode parameter reference for more information.

Splitting the Layout

The template map_layout.php specifies the layout of the other templates.  For example, the default map_layout.php places the map above the POI list and the directions form. 

The sub-templates may actually be placed anywhere on the page just by creating a <div> element with the correct name. 

For example, suppose you want to show the map and directions in your blog page, but the POI list in the sidebar.  If the map is named ‘mapp0′ then follow these steps:

  1. Remove the POI list <div> from your map_layout.php
  2. Add this HTML anywhere in your theme’s template files (for example, in sidebar.php): <div id='mapp0_poi_list'></div>

See the shortcode ‘name’ parameter for details about how maps are named.

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

The display method also accepts an array of options to override.  For example to force the map to display without directions:

echo $mymap->display(array("directions" => 'none'));

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(array("directions"=>"none"));

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. 

Styled Maps

MapPress Pro supports styled maps, which allow control of the appearance and visibility of different map features.

To create a styled map, use the Google styled maps wizard.  When your 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. 

One common use for styled maps is to disable businesses points of interest on the map.  In the wizard, select ‘Point of Interest’ as the feature type, then ‘business’ as the sub-type.  Select the ‘visibility’ checkbox and choose ‘off’.  The JSON to hide business points of interest is shown below.

[{"featureType": "poi.business", "stylers": [{ "visibility": "off" }]}]

Other features:

  • To automatically apply the style to all maps, select the style under the ‘default style’ setting
  • To make the style available as a selection in the map types control, select the checkbox next to the style’s name in the ‘Map Types’ setting
  • To use the style as the default style for just one map, make the style available in the map types control as described above, then select the style in the Map Editor and save the map
  • You may also use the shortcode parameter maptypeid, for example: [mappress maptypeid="mystyle"]

Reference

Overriding Map CSS

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

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

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

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

.mapp-layout { margin: 10px; }

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

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 InfoWindows and in the POI List:

  • ‘Inline’ displays directions in your blog
  • ‘Google’ opens directions in a new Google Maps window
  • ‘None’ suppresses the directions links
Draggable Allow maps to be dragged using the mouse

Keyboard shortcuts

Allow panning and zooming using the keyboard

Scroll wheel zoom

Allow zooming using the mouse scroll wheel

Map types

Select the allowed map types. If you create a custom map style you can also select it here.

Map controls

Select the map controls that should appear on each map.

Note that bicycling, traffic and public transit information is not available in all areas.  See Google’s coverage spreadsheet.

Map Links

Add special links above the map:

  • ‘Bigger map’ displays a larger map. The size can be set using shortcode parameters biggerWidth and biggerHeight
  • ‘Center map’ recenters and zooms the map so all POIs are visible
  • ‘Reset map’ resets the map to its initial state

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

Map border

Set a border for the map

Open first POI

Open the first POI automatically when the map is displayed

POI list

Show a table of POIs under the map

Use DataTables

Show the POI list using the jQuery DataTables plugin, which allows dynamic sorting

POI links

Add special links at the bottom of each POI:

  • ‘Zoom’ zooms in on the POI
  • ‘Directions from’ and ‘Directions to’ provide directions from or to the POI.  Note that if the ‘Directions’ setting is set to ‘none’ the directions links will also be suppressed.

Tooltips

Show POI titles as a tooltip on mouse hover

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.

InfoWindow type

When a POI is clicked a ‘bubbles’ opens with details about the POI. Select the standard Google InfoWindows or MapPress InfoBoxes. InfoBoxes have two advantages:

· They can extend past the edges of the map. This is especially useful on small maps where it can be hard to read the full POI details.

· They can be styled using CSS (see the ‘mappress.css’ file)

InfoWindow panning

When a POI is clicked the map is normally panned to center on that POI before the InfoWindow is opened.

Select this checkbox to prevent panning and open the POI without centering on it. This setting is useful only if you are using InfoBoxes, since they can extend beyond the map edges (if you are using InfoWindows the POI content will be cut off).

Even with panning disabled, the map will be still be centered if the POI is outside the visual area of the map.

Mashup POI title

Select what to show for the POI title in mashups:

  • The title saved with the POI
  • The title of the post the POI is linked to

Mashup POI body

Select what to show for the POI body in mashups:

· The body HTML saved with the POI

· The POI’s street address

· An excerpt from the post the POI is linked to

Mashup POI click

Select what to do what a mashup POI is clicked:

· Open the POIs InfoWindow (the default)

· Go directly to the post the POI is linked to

Link title

Check to automatically link POIs to their underlying post. The link is applied to the POI title.

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 to use for the map controls, geocoding 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.

All other texts (other than the map controls) 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.

Directions units

Select imperial or metric units for directions and the map ‘scale’ control.

Adaptive display Re-center maps when the window is resized.  This setting is intended for ‘adapative’ themes and the maps must have a % width in order to resize.  Only select this if needed, since it slows performance.

POI editor

Uncheck this option to turn off tinyMCE in the Map Editor

Turn off CSS

Prevents loading of the mappress.css stylesheet. If you select this option you must copy all map styling to your own theme stylesheet, ‘styles.css’.

Load maps last Check this box to load maps after all other page content has loaded.  Normally this is not required.

API key

Enter an optional API key. API keys are only required for usage monitoring or billable Google Maps for Business services.

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

adaptive boolean false Re-center the map when the window is resized.  Intended for ‘adapative’ themes.  Maps must have a % width in order to resize.  Only set if needed, since it slows performance.

alignment

center
default
left
right

default

Map alignment

bicycling

boolean

false

Enable the bicycling overlay control

bigWidth

pixels or %

100%

Width of bigger map when using the ‘bigger map’ link

bigHeight

pixels or %

400px

Height of bigger map when using the ‘bigger’ map link

directions

google
inline
none

inline

Directions type for the map

draggable boolean true Allow the map to be dragged using the mouse
from number or string empty Default ‘from’ address for the directions form.  This can be either an address or a POI number (0 is the first POI)

hidden

boolean

false

Hide the map initially and show a ‘show map’ link instead. Clicking the link displays the map.

hideEmpty boolean false Hide empty mashup maps (maps with no POIs)

initialBicycling

boolean

false

Enable the bicycling overlay when the map is first displayed

initialOpenDirections

boolean

false

Open the directions form when the map is first displayed.  See also the ‘from’ and ‘to’ parameters.

initialOpenInfo

boolean or number

false

Open the first POI when the map is first displayed:

  • “true”- open the first POI 
  • “n” – open the nth POI, for example “2″ opens the 3rd POI

For example initialOpenInfo=”2″ opens the 3rd POI.

initialTraffic

boolean

false

Enable the traffic overlay when the map is first displayed

initialTransit

boolean

false

Enable the transit overlay when the map is first displayed

iwType

ib
iw

iw

Open POIs using InfoWindows or InfoBoxes

iwDisableAutoPan

boolean

false

Disable map panning when a POI is opened

language string blank

Language to use for the map controls, geocoding and directions. If not specified, Google will use the language setting in the user’s browser.  Google provides a spreadsheet with a list of supported languages.

mapLinks

bigger
center
reset

blank

Links to show above the map. Enter as a comma-separated list, for example “center, bigger”.

mapTypeControl

boolean

True

Enable the map type control on the map

mapTypeId

hybrid
roadmap
satellite
terrain
<custom>

blank

Map type to display. If blank displays the first available map type.  The type may also be a custom style name: “mystyle”

mapTypeIds

hybrid
roadmap
satellite
terrain
<custom>

all types

Limit the map types available in the ‘map type’ control. Enter as a comma-separated list.  The list may include custom map styles.  For example:”roadmap, mystyle”

mashupTitle

poi
post

poi

Title text for mashup POIs:

  • “poi” – title saved with the POI 
  • “post” – title of the post the POI is linked to

mashupBody

address
poi
post

poi

Body text for mashup POIs:

  • “poi” – body saved with the POI
  • “post” – excerpt from the post the POI is linked to

mashupClick

boolean

false

Behavior when a mashup POI is clicked:

    • “poi” – open the POI’s InfoWindow
    • “post” – open the POI’s underlying post

mashupLink

boolean

true

Set true to link mashup POI titles to the underlying post

maxZoom

1-21

blank

Set maximum allowed map zoom

minZoom

1-21

blank

Set minimum allowed map zoom

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.

poiLinks

directions_from
directions_to
zoom

directions_to

zoom

Links to display for each POI. Default is “directions_to, zoom”.

poiList

boolean

false

Display the POI list under the map

poiZoom

1-21

15

Default zoom for POIs entered by lat/lng

sort

boolean

true

Enable sorting.  By default POIs are sorted by title title.  Set to “false” to use the POI order that was saved with the map instead.

streetViewControl boolean true Set true to display the street view ‘peg man’ control on the map

template

string

map_layout

Template file for the map layout

templateDirections

string

map_directions

Template file for the directions form

templatePoi

string

map_poi

Template file for the map POIs

templatePoiList

string

map_poi_list

Template file for the POI list

thumbs boolean true Enable thumbnail images in POIs (applies to mashups only)
to string or number empty Default ‘to’ address for the directions form.  This can be either an address or a POI number (0 is the first POI)
tooltips boolean true Set true to show a tooltip (the POI title) when the mouse hovers over a marker
transit boolean false Set true to show an overlay of transit routes (buses, trains, etc.) on the map
traffic boolean false Set true to show a button that allows the user to turn on a traffic overlay.  The overlay displays real-time traffic on the map.  Note that traffic is not available in all areas
zoomControl boolean true Show the zoom controls on the map

Filters and Actions

Several filters and actions are available to customize the appearance and behavior of the maps.

POI Filters

These filters are called for each POI just before the map is displayed.

mappress_poi_title ( $html, $poi )

Set the POI title.  The $html parameter contains the existing title saved with the POI.

mappress_poi_body ( $html, $poi )

Set the POI body.  The $html parameter contains the existing body saved with the POI.

mappress_poi_html ( $html, $poi )

Set the html for the entire POI.  The $html parameter contains the HTML that MapPress would normally display for the POI.

mappress_poi_iconid ( $iconid, $poi )

Set the icon ID for the POI.  The $iconid parameter contains the icon ID of the icon that would normally be displayed.

Map Actions

Map actions are passed the map object, by reference, and no return value is required.  If you modify the map object MapPress will use the modified values. 

In other words, you can choose to modify the map or just do your own processing.

mappress_map_display ( $map )

This action is called 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, sorting by a custom field.

mappress_save ( $map )

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

mappress_delete ( $map )

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

Examples

Modifying the POI Template

The POI template can be modified to show information from the current post.  The post ID can be taken from the POI property $poi->postid for mashups, or from the global $post variable for individual maps.

Below is a sample ‘map_poi.php’ POI template that outputs the custom field ‘test’ from the current post.  Remember to place the modified template into your child theme directory so it won’t be overwritten when the plugin is upgraded.

<div class='mapp-iw'>
<?php
global $post;
$postid = ($poi->postid) ? $poi->postid : $post->ID;
?>
<div class='mapp-title'>
<?php echo $poi->get_title_link(); ?>
</div>
<div class='mapp-body'>
<?php echo $poi->get_thumbnail(array('class' => 'mapp-thumb')); ?>
<?php echo get_post_meta($postid, 'test', true); ?>
<?php echo $poi->get_body(); ?>
</div>
<div class='mapp-links'>
<?php echo $poi->get_links(); ?>
</div>
</div>

Automatic Icons

The filter mappress_poi_iconid can be used to have MapPress automatically display an icon based on a category or custom field value.  Add the example code below to your theme’s functions.php to assign a blue icon for posts in category ‘cata’ and a red icon for posts in category ‘catb’.

function myiconid($iconid, $poi) {
global $post;
$postid = ($poi->postid) ? $poi->postid : $post->ID;
if (has_category('cata', $postid))
return 'blue-dot';
if (has_category ('catb', $postid))
return 'purple-dot';
return $iconid;
}
add_filter('mappress_poi_iconid', 'myiconid', 10, 2);

Below is a similar example using a custom taxonomy ‘mytax’ with terms ‘term1′ and ‘term2′:

function myiconid($iconid, $poi) {
global $post;
$postid = ($poi->postid) ? $poi->postid : $post->ID;
if (has_term('term1', 'mytax', $postid))
return 'blue-dot';
if (has_term('term2', 'mytax', $postid))
return 'purple-dot';
return $iconid;
}
add_filter('mappress_poi_iconid', 'myiconid', 10, 2);

Custom Sorting

By default MapPress always sorts the POIs in the POI list alphabetically by title. 

The shortcode parameter ‘sort’ can be used to turn off the default sort.  Setting sort=”false” for a single map will display the POIs in the order in which they were saved in the Map Editor.  You can drag and drop POIs in the editor to change their sort order.

For mashups, or to change the default sort, you can use the filter mappress_sort_pois.  For example to sort POIs by title in descending order, add the following code to your 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');

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 or Zoom a POI Using Javascript

Javacript can be used to open a specific map POI. 

For stand-alone maps, POIs are accessed using the method getPoi(index)where index is the order in which the POI is listed for the map, starting with ’0′.  For example, if the map is named ‘mapp0′ this code will retrieve the second POI:

mapp0.getPoi(1);

For mashup maps, POIs may be accessed using the method getPoiById(postid) which retrieves the first POI for the given post.  For example, to retrieve the POI for post 1234 use:

mapp0.getPoiById(1234);

Once a POI is retrieved, it can be opened using the open() method.  For example:

mapp0.getPoi(1).open();

The POI can be centered and optionally zoomed using the center() method.  This method takes a zoom parameter with the following allowed values:
false = don’t zoom
true = automatically zoom in on the POI
integer (0-21) = use the specified zoom

For example:

mapp0.getPoi(1).center(10);