Overview
This is the documentation for both MapPress and MapPress Pro. If you need additional help, please try posting to the forums or contact me directly.
Compatibility
MapPress is compatible with WordPress 3.0 and higher. It requires PHP version 5.2 or higher.
Installation
MapPress installation is just like any other plugin installation. Here’s one way to install it:
- Download the .zip file
- Unzip the file to your
wp-content/plugins directory. You should now have a directory like:wp-content/plugins/mappress-google-maps-for-wordpress - Go to the WordPress ‘plugins’ menu and activate the MapPress plugin
- After you activate you should see the MapPress ‘settings’ menu in your WordPress administration menu
The Options Screen
The options screen lets you set various defaults for how maps should be displayed in your blog. Most of these settings can also be set for each map using the MapPress shortcode and template tags.
The available settings are listed below. If you’re using MapPress Pro there are some additional settings see the Pro section at the end of this document.
| Setting | Description |
| Automatic map display | Automatically display maps in your post/pages. Note that maps will not be automatically displayed if a mappress shortcode is present in the post/page. |
| Post types | Select the post types that should include MapPress maps for editing. Note that ‘post’ and ‘page’ are the standard post and page types, so if you uncheck them you may not be able to edit your maps. |
| Map alignment | Determine the alignment for maps around your post/page text |
| Directions | Choose ‘inline’ to include a link in each map marker for directions or ‘google’ to display open a new directions window from Google. |
| Marker List | MapPress Pro feature: show a list of markers under the map |
| Map types | Display a button on each map that lets the user change the map type (“street” or “hybrid” for example) |
| Street view | Show the street view “peg man” on the map. The peg man icon can be dragged anywhere on the map to switch to street view. |
| Scroll wheel zoom | Allow zooming using the mouse scroll wheel. This can be annoying when they are trying to scroll a web page instead, so by default it’s disabled. |
| Keyboard shortcuts | Allow panning and zooming using the keyboard |
| Open first marker | Open the first map marker automatically when the map is displayed |
| Show traffic button | Include a ‘traffic’ button on each map. Click the button for real-time traffic as red/yellow/green overlays on the map. Traffic information is not available in all areas. |
| Tooltips | Show the marker title as a tooltip when the user moves the mouse over it. If you use HTML in the marker titles you should disable this feature, because Google will display the raw HTML code. |
| Overview map | An overview map is an inset map that is zoomed out more than the main map. Select the checkbox to display an “overview map control” (a small arrow in the bottom right of the map that can be clicked to open an overview map). You may also choose to have the overview map opened initially when the map is displayed. |
| Language | normally the map language defaults to the language set in your browser. Use this setting to force a particular language for the map controls and directions. A list of languages is available here. You will also need a translation for MapPress. The MapPress language files are in the ‘languages’ sub-directory. |
| Country | Provide a default country for map 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 here (otherwise it defaults to the US server). This lets you offer directions in your readers’ native language, for example “maps.google.fr” or “maps.google.de”. |
| Custom CSS | If you want to override CSS settings enter the full URL to your CSS file, for example: http://myhost/myfile |
| 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. |
Using The Plugin
MapPress is easy to use. Basically, the steps are:
- Edit the post or page and create a map
- Add markers to your map
- Optionally add the MapPress shortcode
- Publish your post
That’s it! You should immediately see your map in your post or page.
Create a Map
After you activate MapPress, go to the WordPress post or page editor. You will notice a new MapPress ‘meta box’ has been added.
Click the “new map” button to create a map and open the map editor:
Location: use this field to enter a street address, country, state, place or monument. For example “Washington, DC”.
You may also enter an location as a latitude/longitude – use the format [title]@latitude,longitude (the title is optional). For example, these both will display Washington, DC:
The Capitol@38.90279,-77.037849
38.90279,-77.037849
Title: enter a title for the map
Dimensions: click one of the links to choose a default size or enter a custom size in the boxes below
Save button: save your map. The map will also be saved if you publish or preview a post or page.
Center button: click to re-center the map between all of the map markers
Edit Markers
When you are creating or editing a map you are in ‘edit mode’. In this mode you can edit the map markers.
To select a marker click its address or icon in the marker list, or click the marker on the map. You can then change the marker title or body, delete it, or zoom in on it.
The marker title and body can contain any valid HTML.
Putting an Image or Links in a Marker
To include an image in a marker use the HTML <img> tag. Note that in order for Google to correctly size the marker infowindow (the balloon) you must specify the image width and height.
For example, type this into your marker to see an image of the Google logo:
<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>
Sizing the InfoWindow
Google always tries to automatically size the infowindows to fit their contents and the map size. However, its algorithm is not always accurate.
For best results try to make sure that any HTML in your infowindows specifies sizes explicitly (as in the <img> example above) or you may need to use a larger map.
Drag a Marker
Markers can also be dragged to a specific location. You must be in editing mode to do this.
Set the Map Type, Center and Zoom
Any changes you make to the map type, center or zoom level in edit mode will be reflected in your blog when the map is displayed. Be sure to set them correctly before saving your map.
Save the Map
When you’re done editing the map click the “save” button. MapPress will save all of the map data. It’s not necessary to publish or update your post to save the map, but if you do MapPress will also save at that time.
At this point the map should be visible in your post. By default MapPress automatically displays any maps above your post text (in the options screen you can choose display above, display below or no automatic display).
However, even if you’re using automatic display there may be times when you want to more precisely place the map in your post. To do this you can use the [mappress] shortcode. Read on to the next section to learn more.
Insert the MapPress Shortcode
After a map has been created and saved you will see it in the map list for your post or page. This is the ‘display’ mode. In this mode you see the map and markers exactly like your users would see them, but you can’t edit them.
Hover your mouse over a map in the list to see some additional options:
Edit: switch to editing mode
Insert into post: insert the [mappress] shortcode into your post at the current cursor position
Delete: delete this map and all of its markers
Tip: if you insert the shortcode into your post, MapPress will switch off automatic display for that post. That way you won’t see two of the same map.
Shortcodes
The simple form of the shortcode just displays a single map:
[mappress mapid=”2”]
Many other parameters are available – see the list below. For example, this will open map with mapid “1234″ as a full-width map. It will also open the first marker immediately, while suppressing the directions link:
[mappress mapid="1234" width="100%" initialopeninfo="true" directions="false"]
| Parameter | Allowed Values | Default | Description |
| width | width in pixels or % | 425 | Map width |
| height | height in pixels or % | 350 | Map height |
| zoom | 1-20 | 1 | Map zoom. If left blank, the map will be automatically zoomed so that all markers can be shown. |
| center_lat | latitude | none | Set the map center. If the center is left blank, the map will automatically center between all markers |
| center_lng | longitude | none | Set the map center |
| directions | inline | google | none | inline | Show directions in your blog (inline) or from Google (google). |
| traffic | true | false | true | Show real-time traffic
Not available in all areas – see Google’s coverage spreadsheet |
| tooltips | true | false | true | Show marker tooltips |
| alignment | default|left|right|center | default | Set map alignment (default will display the map on its own line with no text wrap around it) |
| maptypeid | roadmap | hybrid | satellite | terrain | roadmap | Map type |
| initialopeninfo | true | false | false | Open the infowindow (the bubble) for the first marker immediately |
| initialopendirections | true | false | false | Open the directions to the first marker immediately. This will also center the map on the first marker |
| overviewmapcontrol | true | false | false | Show an overview map control in the bottom-right corner of the main map. |
| initialopenoverviewmap | true | false | false | Open the overview map initially (when the main map is first displayed) |
Template Tags
Maps can be displayed anywhere on your blog – in the header, footer, sidebar, etc. MapPress loads all of the required Javascript and CSS only when a map is being displayed.
Adding a map to your template is easy. Just add a few lines of PHP code:
<?php echo do_shortcode('[myshortcode]'); ?>Where [myshortcode]is the shortcode for the map you would like to display. Enter the shortcode exactly as you would type it into a post.
Tip: Be careful to put the whole shortcode in single quotes but the shortcode arguments in double quotes
Tip: It’s a good idea to test the shortcode in a post or page first, before adding code to the template
For example, this will display the map with mapid=20:
<?php echo do_shortcode([mappress mapid="20"]'); ?>Creating Maps Dynamically
You can use MapPress objects to create your own maps dynamically using PHP code. For example, you could make a map showing where all of your blog readers are in the world, or a real estate blog with home listings shown on a map.
The key objects are Maps, POIs (points of interest – the markers on your map), and Options (display options). These are all represented as objects of appropriate classes (Mappress_Map, Mappress_Poi and Mappress_Options). Each object has appropriate default settings when it’s instantiated but you can pass in an array of attributes to override the defaults.
For example, this creates a new map object with a width of 600 pixels:
$mymap = new Mappress_Map(array("width" => 600));
To create a new POI with title “my title” and body “my body” over Washington, DC:
$mypoi_1 = new Mappress_Poi(array("title" => "DC", "body" => "Beautiful Washington, DC", "point" => array("lat" => 38.90279, "lng" => -77.037849)));
If you don’t know the point’s latitude and longitude in advance, you can automatically geocode it by specifying an address, then calling the geocode() method (this will also set a default title and body if you haven’t specified one):
$mypoi_2 = new Mappress_Poi(array("address" => "500 chestnut st, phildelphia"));$mypoi_2->geocode();
To add the new POI to the map object:
$mymap->pois = array($mypoi_1, $mypoi_2);
Finally, to display the map:
echo $mymap->display()
The display method uses the default options from the MapPress settings screen, but it also takes an array of attributes as an argument so you can override any option. For example to force the map to display without directions:
echo $mymap->display(array("directions" => 'none'));
Putting it all together gives the following code to display the map:
$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("address" => "500 chestnut st, phildelphia"));
$mypoi_2->geocode();
$mymap->pois = array($mypoi_1, $mypoi_2);
echo $mymap->display(array("directions"=>"none"));
The finished map looks like this:
Centering the Map
By default, MapPress automatically sets the map center and zoom level to show all of the POIs. You can also set the center and/or zoom level manually.
In the shortcode the center and zoom are specified using parameters center_lat, center_lng, and zoom. For example, to center on Washington, DC:
[mappress width="100%" initialopeninfo="true" directions="false" center_lat="38.90279" center_lng="-77.037849" zoom="4"]
To set the center in PHP code or a template tag, pass the center argument as an array, like this:
$mymap = new Mappress_Map( array("width" => 600, "center" => array("lat" => 38.90279, "lng" => -77.037849), "zoom" => 8 ) );
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
MapPress Pro is the premium version of MapPress. It contains many additional features that are described below.
Marker 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 a marker icon, go to your map and edit a marker. You should see the marker icon highlighted in blue, in the upper-right corner of the infoWindow:
Click on the icon to open the icon picker. From here you can click on an icon to change it or use the “back” option to go back without changing the icon:
Custom Icons
The standard icon .PNG files are located in the /pro/standard_icons/ subdirectory of the MapPress plugin. Don’t change the icons in this directory.
To use custom icons, copy your icon files to the /icons/ subdirectory in the root of the MapPress plugin directory (not to the standard directory).
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.
Icons in Template Tags and Custom Code
The iconid parameter lets you specify a standard icon or a custom icon.
Use the name of a standard icon without any extension. For example, to display the standard green dot icon (“green-dot.png”) the iconid is just “green-dot”:
$mypoi_1 = new Mappress_Poi(array("iconid" => "green-dot", "title" => "Standard Icon Example", "point" => array("lat" => 38.90279, "lng" => -77.037849)));
For custom icons, the icon name must include the file extension (“.png”, “.jpg”, or “.gif”). For example this would display a custom icon file “family.png”:
$mypoi_2 = new Mappress_Poi(array("iconid" => "family.png", "title" => "Custom Icon Example", "point" => array("lat" => 40.7269, "lng" => -74.0087)));
Putting it all together gives the following code to display the two locations on the map:
$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();
Mashups
Mashups combine multiple maps into an overview 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: be sure to always put the shortcode on its own line (there’s a WordPress bug that requires this). To show a mashup of posts currently being displayed (for example, the list of posts on your main page) use:
[mashup show="current"]
To show a mashup with the title of each marker = post title and the body = post excerpt, use:
[mashup marker_title="post" marker_body="excerpt"]
Parameters
The following shortcode parameters are available for mashups. You may also use any of the parameters used for maps (width, height, etc.).
| Parameter | Allowed Values | Default | Description |
| show | allcurrent query | current | Show all posts, current posts, or a custom post query |
| show_query | custom query | none | if show=”query” then specify the query here (see the WordPress codex for more info) |
| marker_title | post marker | marker | Set the marker title to the post title or the marker title as it was originally saved. |
| marker_body | excerpt marker none | marker | set the marker body to a post excerpt, the original marker body, or empty. Default = marker. |
| marker_link | true false | true | wrap the marker title in <a> tags to link to the post. Default = true. Note that this won’t work if you have HTML in your marker titles! |
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 Your Query
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 show="query" show_query="p=5"]
Show a single page with page ID = 5:
[mashup show="query" show_query="page_id=5"]
Show map locations from the currently displayed posts:
[mashup show="current"]
Tip: A common “gotcha” is that by default WordPress will only return one blog “page” of results (usually 20 results). To get all posts that match your criteria, user “posts_per_page=-1″:
[mashup show="query" show_query="posts_per_page=-1&post_type=post"]
Show pages that contain maps:
[mashup show="query" show_query="post_type=page"]
Show the posts (or pages) with post ID = 3, 4 and 5:
[mashup show="query" show_query="post__in=3,4,5"]
Show the first 5 posts in category “mycat”:
[mashup show="query" show_query="posts_per_page=5&category_name=mycat"]
Show posts for custom post type “business”:
[mashup show="query" show_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 show="query" show_query="posts_per_page=5&tag__and=37,47"]
Show posts assigned to category 1 or category 3:
[mashup show="query" show_query="category__in=1,3&posts_per_page=-1"]
Show posts assigned to both category 1 and category 3:
[mashup show="query" show_query="category__and=1,3&posts_per_page=-1"]
Show posts that have the custom field ‘color’, regardless of the field value:
[mashup show="query" show_query="meta_key=color&posts_per_page=-1"]
Show posts that have the custom field ‘color’ set to the value ‘blue’:
[mashup show="query" show_query="meta_key=color&meta_value=blue&posts_per_page=-1"]
Mashup Template Tag
The mashup template tag takes the same arguments as the shortcode. In order to use the template tag you’ll need to reference the global $mappress object, like this:
<?php
global $mappress;
$atts = array('width'=>425, 'height'=>350);
echo $mappress->shortcode_mashup($atts);
?>
Widgets
Mashup Widget
The MapPress Mashup widget is available from the WordPress widgets screen. The parameters are similar to those for the mashup shortcode. When entering a custom query for the widget just enter the query itself. For example, to show only page number 5 from your blog, choose the custom query radio button and enter this in the text box:
page_id=5
To show all posts with category “cat1″ enter this in the custom query text box:
posts_per_page=-1&category_name=cat1
Here’s a screenshot of the other widget options. Other than the query, the options are similar to those on the MapPress settings screen. Note that if center and/or zoom are left blank (the default), the plugin will attempt to set them automatically to display all available markers.
Custom Fields
MapPress Pro can automatically generate maps from custom fields. This can be very useful if:
- If you have a plugin that populates a custom field
- You’re loading many posts or pages automatically using TurboCSV
TurboCSV is fully integrated with MapPress. It generates maps during import and logs any mapping errors, but it is not required to use the custom field functionality.
Creating Custom Fields
Before you can use the custom field functionality you must create a custom field that will contain the addresses you want to map. You may optionally create a second custom field to hold any error messages that MapPress generates when it attempts to display the map. Tip: The WordPress Codex explains how to create custom fields. To create a custom field you actually need to add it to at least one post, so you may need to create it with a dummy value initially.
Custom Field Settings
Once you’ve created your custom fields, you need to let MapPress know about them using these settings on the MapPress settings screen. The settings also control when maps should be updated:
| Setting | Description |
| Field for addresses | Select the custom field to use for addresses. |
| Field for errors | Select the custom field to use for errors messages. |
This is how the settings would look if you are using the custom field “Address” to store addresses and the custom field “meta_errs” to store errors:
Updates
Once an address custom field is specified, MapPress will create a map when a post containing that field is first saved. The map can be edited manually, just like a map you created yourself. If you plan to change the contents of the address custom field, you may also specify that the map should be updated automatically when the field contents change. Tip: when the map is updated automatically, any manual changes you made will be lost.
| Setting | Description |
| Update map when post is updated | Update the map whenever the post is updated. |
| Update map when address is changed by a program | Update the map when a program changes the contents of the address field. |
This is how the settings would look if you want to have the map updated whenever the post is saved or a program changes the address custom field:
Entering Addresses
Addresses are entered in the custom address field just as like you would add them to a map. For example “Paris” or “100 Main Street, San Francisco, CA”. To enter multiple addresses, create separate field values. For example, this is how the post edit screen would look with two addresses, Paris and Rome, in the custom field “Address”:
POIs
Sometimes you will want to have more control over the map markers than just the street address. You can do this by entering a “POI” or point of interest specification in the custom field instead of an address. The POI format lets you specify many different settings for each map marker. The value for each setting is enclosed in double quotes. For example, this is a POI with a specific title, body, and icon:
address="New York, NY" title="New York City!" body="Visit New York" iconid="green-dot"
This is how it looks in the post edit screen:
The allowed POI parameters are:
| Parameter | Allowed Values | Default | Description |
| address | string | none | Street address or place to map. You must specify this in order to get a map marker! |
| title | string | none | Marker title (may include HTML) |
| body | string | none | Marker body (may include HTML) |
| address | string | none | Marker address |
| iconid | string | none | Icon ID (see the Custom Icons section for details) |
| point_lat | number | none | Latitude for the marker (such as “38.24″) |
| point_lng | number | none | Longitude for the marker (such as “-109.32″) |
Custom Field Errors
Errors may occur when a map is being generated from your address custom field. If you specify a custom field for errors in the MapPress settings screen, any error messages will be written to that field. For example, if you specified the field “Address” for addresses and the field “meta_errs” for errors, then an invalid address “zzzzz” would like this in the post editing screen:
Update Performance
MapPress ensures that your blog stays speedy by geocoding the custom field addresses (geocoding is the process of determining the latitude and longitude for each location). Google’s geocoding service takes about half a second per address so it’s important to do the geocoding when posts are created or updated, and not when your readers are looking at your blog. Normally geocoding only happens infrequently, but if you find that you have a plugin or program that is triggering the post save event, or updating the address field very frequently, it could impact your blog’s performance. In these cases you may want to disable the MapPress update settings.
Marker List
On the MapPress settings screen there these settings are used to display a list of markers under the map:
| Setting | Description |
| Marker list | Show a list of locations under the map |
| Marker list template | Template used to display each row of the location list |
Set the checkbox to show a list of markers (also called “Points of Interest” or “pois”) under every map. To show a marker list just for one map, use the parameter poilist in the MapPress shortcode or template tags. For example, this shortcode will display a map with a list of locations under it:
[mappress poilist="true"]
Marker List Template
The marker list is displayed as an HTML table where each row is one marker. By default the marker’s icon, title and body are shown. If you would like to modify the template you can change the HTML. Since each marker is a table row the <TR> tags are generated automatically. You must add the table columns for each row, wrapped in HTML <TD> tags. Take a look at the the default template setting in the MapPress options screen as an example. You may also use these special pseudo-tags:
| Tag | Description |
| [icon] | Display the marker’s icon |
| [title] | Display the marker’s title if it exists, followed by a “<BR/>”. If the title doesn’t exist, nothing is displayed |
| [body] | Display the marker’s body if it exists, followed by a “<BR/>”. If the body doesn’t exist, nothing is displayed |
| [directions] | Display the directions link |
| [address] | Display the address exactly as it was originally entered |
| [correctedaddress] | Display the corrected address. For example, if you originally typed “Los Gtos, CA”, Google would correct that to “Los Gatos, CA, USA” |
| [address1] | Display the first line of the corrected address |
| [address2] | Display the second line of the corrected address (note that “USA” is stripped out when using this tag) |