HOME PRICING FEATURES SUPPORT ACCOUNT GET STARTED MapPress Documentation MapPress Compatibility and Installation Picking a Mapping API Mapbox and Leaflet Google API Keys Geocoding Creating a Map Create a Map with the Gutenberg Block Editor Create a Map with the Classic Editor Editing a Map Shortcodes Map Sizing Template Tags Backing Up and Copying MapPress Data MapPress Pro Overview Icons Automatic Icons Mashups Mashup Search MapPress Templating Widgets Generating Maps From Custom Fields Displaying Maps Using PHP Google Styled Maps Mapbox Studio Styles Reference Overriding Map CSS Translation Support WPML Settings Shortcode Parameters Filters and Actions Frontend Forms Advanced Custom Fields (ACF) Formidable Forms Examples Open a POI Using Javascript MapPress Compatibility and Installation MapPress is compatible with WordPress 5.0 and higher. See the Installation Instructions for information about installing the plugin. Picking a Mapping API MapPress supports two mapping APIs: Google Google has very accurate geocoding and great-looking maps Requires billing information and an API key Free usage is limited. Leaflet Completely free and open-source Comparable functionality to Google if Mapbox is used Traffic, bicycling and transportation overlays and shape drawing tools are not available Mapbox and Leaflet If you’re using Leaflet, it’s strongly recommend to sign up with Mapbox. The default map tiles for Leaflet are from OpenStreetMap. They’re plain and unattractive, and the default geocoder is Nominatim, which isn’t very accurate. . Mapbox provides: Detailed map tiles, An accurate geocoder Styled maps To use Mapbox, just get a Mapbox access token and enter it in the MapPress settings. Mapbox services are free for most sites because they offer a generous free usage tier. Google API Keys Google Maps require a Google API key. Click the link to learn how to create one: How to Get A Google Maps API Key For Leaflet maps, no API keys are needed, unless you’re using the Google geocoder. Google API key issues If maps aren’t displaying after entering the API key, check the browser’s JavaScript console for any errors (F12 for most browsers). If there’s a message saying the API key is invalid, get a new one using the steps in Get a Browser API key A common error is having the maps API loaded multiple times. See the Troubleshooting FAQ section if there are console errors indicating the API has been loaded more than once. Geocoding A geocoder is a web-based service that translates addresses like ‘200 Main Street’ into latitude and longitude coordinates that can be displayed on a map. The Google API always uses the Google geocoder. This is the best available geocoder and it has very precise results. For Leaflet, there are a variety of geocoders available. If you’re using Leaflet, it’s strongly recommend to sign up with Mapbox. The Google geocoder is excellent, but requires setup of a Google API key MapBox is also excellent. It requires a Mapbox access token, which is easy to set up and has generous free usage limits. Nominatim is the default geocoder. It’s free and has no usage limits but the geocoding is poor. In many locations it only provides ‘street level’ accuracy: if a house address is entered, it will return the middle of the nearest street. Service Terms of Service Free Registration Usage Limit Accuracy MapBox Link No Yes 100,000 per month Exact Google Link No Yes Yes Exact Nominatim Link Yes No None Exact in some Locations, street elsewhere Creating a Map MapPress supports both the Gutenberg Editor and the Classic Editor, making it easy to create a map while editing a post. Maps created in this way are linked to the underlying post, and can be displayed in ‘mashup’ maps. When MapPress editing popup opens, it displays the Map Library, a list of all maps and which post they’re linked to – it’s similar to the Media Library in WordPress. From the Map Library, maps can be selected to edit or delete. The Map Library can also be opened directly from the MapPress menu, without first going to the WordPress post editor. Create a Map with the Gutenberg Block Editor Select the ‘MapPress Map’ block type to insert a map into the post. Settings can be controlled from the WordPress inspector toolbar. To insert an existing map, use the map library button in the MapPress block. To insert an existing map, or replace a map with another one, use the Map Library button in the block toolbar. This opens the Map Library popup with a list of all existing maps. The list can be filtered to show only maps attached to (created in) the current post, or all maps. It’s also possible to search by mapid, map title or post title. Create a Map with the Classic Editor MapPress adds a map editing meta box to WordPress classic editor. The meta box is only present for the post types selected in the MapPress settings Click an existing map to edit it, or click the “new map” button to create a new map. Editing a Map Map ID: when a map is saved it is assigned an ID number. You can use this ID in the [mappress] shortcode to display a specific map. Map Title: enter a title for the map Size: This setting only appears in the classic editor – for Gutenberg, it’s in the inspector sidebar. Click one of the links to choose a default size or enter a custom size. Search box: enter an address or place to search for (see below) Insert into post button: insert the MapPress shortcode for this map into your WordPress post. Click the cursor in the post where you want the shortcode inserted before pressing the button. Save button: save the map Cancel button: cancel any map edits Geolocation icon (right side of search box): click to enter your current location into the map. Creating a POI To create a new POI, enter an address, place, or business into the search box. Latitude/longitude coordinates may also be entered as decimals. For example, enter “1600 Pennsylvania Ave NW, Washington, DC” for the White House, or “38.8792,76.9818” for the corresponding coordinates. By default, Leaflet locations are only precise to the nearest street. See the MapPress Pro section on geocoders for details. Click the POI to edit the popup text and title. Then save the POI. Title: enter a title for the POI. Body: enter the body for the POI Icon: click the icon to change it (MapPress Pro only) Save button: save your changes Cancel button: cancel your change Setting the Map Type Google has several standard map types which may be selected using the map type control in the upper right of the map editor. Leaflet has only one map type, so the map type control is not displayed by default. However, if a Mapbox access token is entered in the MapPress settings, the control will appear and several Mapbox types may be selected. Creating POIs Using Shapes (MapPress Pro only) The shapes toolbar on the map can be used to create lines, polygons, circles and rectangles. When drawing a line (called a polyline) or polygon, the shape can be completed by clicking on its last point. Polygons and polylines can also be edited. Add a new vertex Click a transparent handle between the existing vertices Delete a vertex Google: right-click the vertex Leaflet: click the vertex KML Files To add a KML file to the map, enter its URL in the ‘search’ field (where the POI’s address would normally be entered). Most KML files are protected by CORS, a security feature that prevents resources from being loaded by other domains. If you see an error when reading a KML file on a remote server, it’s almost certainly due to CORS restrictions. To use a KML, you’ll need to save it on your computer, then upload it to your blog using the WordPress media uploader. Here’s a sample file you can use for testing: https://developers.google.com/kml/documentation/us_states.kml Save the file to your computer, then upload it to your blog. Copy the URL on your blog, and enter it in the MapPress search box. You should see the outlines of US states. Google KMLs Google has strict limits on KML files: Maximum file size <= 3MB Maximum uncompressed KML file size <= 10MB Maximum number of features <= 1,000 There is also a limit on the number of KML Layers that can be displayed on a single Google Map. If you exceed this limit, none of your layers will appear on the map, and an error will be reported in the browser’s JavaScript console. Full limitation details are available here Leaflet KMLs Leaflet KMLs are processed using the Omnivore library from MapBox. There are some important Omnivore features to be aware of: Files can only be read from CORS-enabled web sites. In practice, there are few KML sources available like this so it’s usually best to save the file locally and then upload it to your own server. KML/KMZ files can be uploaded to your server using FTP or the WordPress media uploader Omnivore can read KML files from localhost without any issues State KML Files For US state outlines, the census has a complete set of KMLs at various resolutions (and various file sizes): https://www.census.gov/geographies/mapping-files/time-series/geo/kml-cartographic-boundary-files.html Sorting POIs can be dragged in the Map Editor to change their sort order. There is also a checkbox on the MapPress settings screen to sort POIs alphabetically by default. Dragging POI Markers Sometimes it’s impossible to exactly locate a POI using a street address. In this case the POI’s marker can be dragged to the correct location. Note that POIs that have been dragged do not have a street address, they have only latitude/longitude coordinates. Shortcodes The simplest form of the shortcode displays the first map for a post: [mappress] A map ID can also be specified to display a specific map: [mappress mapid="2"] Many other parameters are available – see the “Reference” section. For example, this will open 400×400 map with mapid “1234”. It will also open the first marker immediately: [mappress mapid="1234" width="400" height="400" initialopeninfo="true"] Converting Existing Shortcodes in the Gutenberg Editor Existing MapPress shortcodes must be converted to blocks in order to edit the underlying map. If the post hasn’t been converted to Gutenberg already, the shortcode will be in a ‘classic block’. Select the block and choose ‘convert to blocks’ from the block menu. Shortcodes must be on a separate line, with no adjacent text or punctuation. If the post has previously been converted to blocks, the shortcode will be in a ‘shortcode’ block. Select the block and use the ‘change block type’ button to convert it to a Map or Mashup block. Map Sizing For responsive maps, set the map width to a percentage. 90% works well because it leaves space along the side of the page for scrolling on mobile devices. Map height usually works best as a fixed pixel size, but it can also be set to a percentage. The percentage is based on the map’s width. For example a map with 100% height is as tall as it is wide. Similarly, a height of 56.25% corresponds to a 16:9 aspect ratio. Maps can also be set to a percentage of the viewport width or height. For example 50vw will size the map to half the width of the browser window, at 50vh will do the same for the height. Template Tags Maps can be displayed by adding PHP template tags to theme template files. MapPress loads all of the required JavaScript and CSS only when a map is being displayed. The easiest way to add a map to your template is using the do_shortcode() statement. For example, this will display the map with mapid=20: <?php echo do_shortcode('[[mappress mapid="20"]]'); ?> Put the whole shortcode in single quotes, but the shortcode arguments in double quotes Backing Up and Copying MapPress Data MapPress stores all of its data in two tables: mappress_maps and mappress_posts. Options are stored in the standard WordPress options table. The MapPress tables will normally be included if you’re backing up your entire WordPress database, or you can export them using MySQL. If you copy your blog from one place to another you will also need to copy the MapPress tables. If for some reason you renumber of change your post IDs you will also need to update the mappress_posts table with the new post IDs. MapPress Pro Overview MapPress Pro is the premium version of MapPress. It contains additional features that are described below. Icons MapPress Pro includes an icon editor that can be used to create millions of custom icons. The editor is available in the MapPress settings screen and in the map editor. To set the icon for a POI, edit the POI in the map editor. In the upper-right corner you should see the current icon. Click on it to change the icon. Click on an icon in the popup list to select it. Click the link ‘use default icon’ to select the default icon. The default icon can be assigned in the MapPress settings screen. Creating New Icons Click the ‘new icon’ button to open the icon editor. Here, you can select one of the predefined shapes, a color and an (optional) icon to show inside the shape. Two fonts are supported for icons: ‘Map Icons’ (a set of default icons) and Google Material Icons. Uploading Custom Icons Click the ‘upload icons’ link in the bottom-right of the icon editor to upload custom icons. FTP Custom Icons It’s usually easiest to upload icons using the icon editor, but it’s also possible to upload using FTP. Standard icon .PNG files are located in the /pro/standard_icons/ subdirectory of the MapPress plugin. When MapPress is activated it also creates a directory for custom icons in the WordPress uploads directory: /wp-content/uploads/mappress/icons Some themes change the upload directory. The correct location is shown in the MapPress settings screen. To add custom icons, copy them to the upload directory. Icons may be .jpg, .png or .gif files. They are usually 32×32 pixels. There are many web-based icon generators and custom icon collections. Automatic Icons Icons can be automatically assigned to maps using the Automatic Icons setting in the MapPress settings screen. Select a taxonomy (categories, tags, or a custom taxonomy) to use. For each taxonomy term (the ‘key’ column) an icon can be selected. For maps attached to posts with that term, all POIs will show the selected icon. Automatic icons only show in the blog front-end. In the editor, you’ll still see whatever icon the POI was saved with. Mashups Mashups combine multiple maps into a single larger map. Mashups are based on a query, which specifies which posts to display. MapPress reads all of the matching posts and combines the map locations from those posts into a single mashup map. The mashup query can find a single post, all posts, or posts matching certain post type, author, tag, category, taxonomy, or custom field. Mashups in the Gutenberg Editor To create a mashup in the Gutenberg editor, just select the MapPress Mashup block. The mashup query parameters can be set in the Gutenberg inspector control. In the example below, a mashup is added to a post and the query is set to select only posts with the tags ‘blue’ and ‘green’. The posts each have a blue or green marker. Mashups in the Classic Editor In the classic editor, mashups are created by typing a shortcode directly into the post content. The most basic version of the shortcode is: [mashup] This will create a mashup map of all posts. WordPress shortcodes must be on a separate line, or they won’t work Mashup Queries More advanced mashups requires a query attribute to specify which posts to read. The query is in the same format as the WordPress query_posts function, so query examples are available in the WordPress Codex for WP_Query. Query Examples Show a single post with post ID = 5: [mashup query="p=5"] Show a single page with page ID = 5: [mashup query="page_id=5"] Show map locations from the currently displayed posts (you may also just omit the query parameter): [mashup query="current"] Show all pages with maps: [mashup query="post_type=page"] Show the posts (or pages) with post ID = 3, 4 and 5: [mashup query="post__in=3,4,5"] Show the posts in category “mycat”: [mashup query="category_name=mycat"] Show posts for custom post type “business”: [mashup query="post_type=business"] Shows posts for tags 37 and 47: [mashup query="tag__and=37,47"] Show posts assigned to category 1 or category 3: [mashup query="category__in=1,3"] Show posts assigned to both category 1 and category 3: [mashup query="category__and=1,3"] Show posts that have the custom field ‘color’, regardless of the field value: [mashup query="meta_key=color"] Show posts that have the custom field ‘color’ set to the value ‘blue’: [mashup query="meta_key=color&meta_value=blue"] The order and orderby parameters can be used to sort the query results by various fields including author, date, etc. For example to sort all posts by date, descending: [mashup query="orderby=date&order=desc"] Show posts with custom taxonomy ‘hotels’ with term value=budget: [mashup query="hotels=budget"] Posts having custom taxonomy ‘hotels’ with value ‘luxury’ AND custom taxonomy ‘rating’ with value ‘5star’: [mashup query="hotels=luxury&rating=5star"] This excellent article has additional examples about custom taxonomy queries: https://thereforei.am/2011/10/28/advanced-taxonomy-queries-with-pretty-urls/ Queries Using Arrays WordPress expects an array value for some parameters. For example dates are specified with a date_query array. This array would show posts created before yesterday: 'date_query' => array( array( 'before' => 'now-1day' ) ) WordPress shortcodes don’t support arrays directly, so arrays must be converted to a URL string notation, where [0] is the first array element, [1] is the second, and so on: date_query[0][before]=now-1day Unfortunately, WordPress also prohibits braces in shortcodes! To work around this, MapPress allows the parameters to be enclosed in curly braces. instead (you may also use the HTML codes %5d and %5e instead of braces). For example, the query above is written like this in the mashup shortcode: [mashup query="date_query{0}{before}=now-1day"] or: [mashup query="date_query%5b0%5d%5bbefore%5d=now-1day"] Queries Using URL Parameters WordPress parses the URL for various parameters. For example, category archives are displayed with the following URL format: https://myblog.com/category/mycat When the page is displayed, WordPress places the current category name in the ‘cat’ parameter (in this case, it’s category ‘mycat’). To create a mashup that displays the current page category, no matter what it is, specify the ‘cat’ query parameter as ‘@cat’: <?php echo do_shortcode('[mashup query="cat=@cat"]'); ?> Mashup Template Tag Adding a mashup to your template is easy. Just add a few lines of PHP code: <?php echo do_shortcode('[[mashup]]'); ?> For example, this will display a mashup of all maps: <?php echo do_shortcode('[[mashup width="425" height="350"]]'); ?> Be careful to put the whole shortcode in single quotes but the shortcode arguments in double quotes It’s also possible to use variables in the query. For example, adding this code to the category archive template will show all posts in the current category: <?php $cat = get_category( get_query_var( 'cat' ) ); $cat_id = $cat->cat_ID; $query = "cat=" . $cat_id; echo do_shortcode('[mashup width="425" height="350" query="' . $query . '"]'); ?> Mashup Search A search box is present at the top of every mashup. Users may enter an address, business or place to center on a particular area. As the map is panned or zoomed, the POI list is updated to show results from just the current area. By default, markers are shown within a 200km radius the search result, but this can be changed in the MapPress settings. Search Biasing Search results are always biased towards locations within the current viewport. For example, if a map of the world is displayed searching for “Paris” will show “Paris, France” as the first item in the list. If the map is zoomed in on Texas, the first result is “Paris, TX”. Search Restriction Searches can be restricted by country, in which case only results from that country will be displayed. For the Mapbox and Nominatim geocoders, a bounding box can also be set to restrict searches to a specific geographic area. For example, to restrict searches to only the New York City area, enter “-75.32776,40.12009,-72.66632,41.31289”. MapPress Templating MapPress maps are displayed using customizable map template files. Each file controls a part of the map output. JavaScript Templates JavaScript template files are used to render parts of the map dynamically. The templates are: map-popup.php – map POI popup map-item.php – map POI list row mashup-popup.php – mashup POI popup mashup-item.php – mashup POI list row Customizing JavaScript Templates JavaScript templates can be edited directly in the MapPress settings screen, using the template editor. The editor shows either the default template file (from the plugin directory /templates) or a customized file (if one exists). Customized template files are always saved to the theme or child theme directory. JavaScript templates contain a mix of HTML, PHP, template variables, and JavaScript. PHP Code PHP is used in the default templates to output text strings. This allows the strings to be translated by multilingual plugins. For example, the map-tmpl-popup template file contains this line, which outputs the string ‘Directions’: <?php _e('Directions'); ?> Template Variables Template variables are output using the underscore.js template library that is included with WordPress. The following delimiters are used: {{ ... }} : HTML-escaped variables (for example character ‘&’ will be escaped to ‘&amp;’ {{{ ... }}} : Variables without HTML-escaping The available POI fields are shown above the editor. Click a field name (such as ‘title’ or ‘body’) to insert the template variable and the correct delimiters. Custom Fields To add a custom field to a template, use this syntax: {{poi.props.myfield}} MapPress will automatically include that custom field when the template is output. Custom Properties Each POI has a set of standard properties (title, body, etc.). It also has a ‘props’ array that contains custom properties. Filter mappress_poi_props can be used to add custom properties to the props array. For example, adding this code to a theme’s functions.php file will create a ‘message’ property for each POI that shows a ‘hello’ message and the POI’s underlying post ID: <?php function myfilter($props, $postid, $poi) { $props['message'] = "Hello from post " . $postid; return $props; } add_filter('mappress_poi_props', 'myfilter', 10, 3); ?> The new message property can now be included in templates as: {{poi.props.message}} JavaScript Code JavaScript code can be included in a template using the tags <# ... #> For example, adding this tag to a template this would display an alert box every time the template is rendered: <# alert('hello world!'); #> Conditionals are also possible. For example, this will output an HTML message if the POI is attached to post #1234: <# if (poi.postid == 1234) { #> <p>This is post 1234!</p> <# } #> PHP Templates Some of the map templates are PHP files. These templates are static – that is, they’re output only once when the map is first displayed. map.php – the general layout of the map elements map-directions.php – the map directions form map-filters.php – the map filters form map-header.php – the map header (search bar and filters link) map-search.php – the search box Customizing PHP Templates Generally, PHP templates do not need to be modified, so that aren’t supported in the MapPress template editor. If you do need to modify them, the default templates are in the plugin directory /templates. Copy the template to be modified to the theme (or child theme) directory using FTP, then modify the copy using a text editor. WordPress overwrites all theme files when a theme is updated, so always use a child theme. Widgets Mashup Widget The MapPress Mashup widget is available from the WordPress widgets screen. The widget can display a custom query, similar to the shortcode. For example, to show the blog page with ID = 5 the shortcode looks like this: [mappress query="page_id=5"] In the widget the same query is entered like this: page_id=5 Or, to show all posts with category “cat1” enter this in the custom query text box: category_name=cat1 Generating Maps From Custom Fields MapPress Pro can automatically generate maps from custom fields. This is useful if you store address data in custom fields or if you need to import map data from a file. Each generated map contains a single POI. To specify the POI’s location, you must have custom fields with either a street address, or a latitude and longitude, on each post. Select the fields on the MapPress settings screen in the ‘Geocoding’ section, and save the settings. The address fields are concatenated together and become the street address for the POI. When any post containing the address fields is published or updated, a map is generated and attached to the post. You may also specify fields for the POI title, body and icon, but this is often not necessary. If post information (title and excerpt) is being shown in the POIs, there is no need to specify a title and body. And automatic icon assignment by taxonomy is often more flexible than assigning icons explicitly. See the MapPress settings screen for the relevant settings. The dropdown lists of custom fields shows only fields that are used in at least one post. If you’re setting up the fields in advance, you will need to create a dummy post with those fields to get them to show in the list. If errors occur during map generation, they are shown in the MapPress settings screen. Error details are also written to the custom field mappress_errors. Geocoding When maps are generated from custom field data, the address is be ‘geocoded’ (converted to latitude/longitude coordinates). If you are using the Google API, the Google geocoder is used. This geocoder is very accurate, but Google imposes a usage limit of about 2,500 geocoding requests per day. Once that limit is exceeded all geocoding will be rejected, and maps will show a location at lat/lng (0,0) (in the ocean near Africa). Google’s usage limit is by IP address, so on shared hosts, all the sites combined cannot exceed that limit. In other words, another site on the same host may consume the geocoding limit. If you find that you’re exceeding Google’s usage limits: You can purchase Google Maps for Business from Google or contact them for usage-based billing. They will give you an API key that has its own (not shared) usage limit. You can use Leaflet with Algolia or Nominatim, which currently have no usage limits, or MapBox, which has more generous limits. Manually Editing Generated Maps Generated maps can be edited manually. However, the map will normally re-generated if the post is published or updated, overwriting any manual changes. To prevent this, uncheck the setting ‘Overwrite maps when posts are saved’. Events for Generating Maps MapPress generates maps only when a post is saved or published. Some forms and custom field plugins update custom fields directly, without saving the containing post. In this case it is necessary to trigger map generation using some PHP code. See The ‘Examples’ section for code samples. Displaying Maps Using PHP Maps can be displayed dynamically by using PHP code in template files. MapPress uses the classes Mappress_Map, Mappress_Poi and Mappress_Options to define maps, POIs and options settings, respectively. Object constructors accept an array of attributes to override defaults settings. For example, this code creates a new map object. The default map size is 425px by 350px, but in this example the width is set to 600px: $mymap = new Mappress_Map(array("width" => 600)); This creates two new POI objects, specifying the title, body and ‘point’ (the latitude / longitude): $mypoi_1 = new Mappress_Poi(array("title" => "DC", "body" => "Beautiful Washington, DC", "point" => array("lat" => 38.90279, "lng" => -77.037849))); $mypoi_2 = new Mappress_Poi(array("title" => "500 Chestnut St", "body" => "Independence National Park, Philadelphia, PA<br/>19106", "point" => array("lat" => 39.948712,"lng" => -75.15001))); Once the POIs have been defined, they can be added to the map: $mymap->pois = array($mypoi_1, $mypoi_2); Finally, the map can be displayed: echo $mymap->display() Putting it all together gives the following code: $mymap = new Mappress_Map(array("width" => 600)); $mypoi_1 = new Mappress_Poi(array("title" => "DC", "body" => "Beautiful Washington, DC", "point" => array("lat" => 38.90279, "lng" => -77.037849))); $mypoi_2 = new Mappress_Poi(array("title" => "500 Chestnut St", "body" => "Independence National Park, Philadelphia, PA<br/>19106", "point" => array("lat" => 39.948712,"lng" => -75.15001))); $mymap->pois = array($mypoi_1, $mypoi_2); echo $mymap->display(); Setting Center and Zoom If a map has no center and zoom specified, it will be automatically centered and zoomed to show all of its POIs. It’s also possible to set a specific center or zoom. For example, this code will show a map centered over Washington, DC (without any POIs): $mymap = new Mappress_Map(array("center" => array("lat" => 38.90279, "lng" => -77.037849), "zoom" => 12)); echo $mymap->display(); If you specify a center, you must also specify a zoom, and vice-versa. Both parameters are required in order to show the map. Icon IDs Each POI may have its own icon. The iconid property specifies either a standard icon or a custom icon for each POI. For standard icons the icon ID is the image file name without any extension. For example the icon ID for the standard green dot icon green-dot.png is green-dot. For custom icons, the icon ID is the entire filename including the extension, such as myicon.png In the example below the first POI is assigned to the standard green dot icon and the second is assigned to a custom icon called “family.png”: $mymap = new Mappress_Map(array("width" => 600)); $mypoi_1 = new Mappress_Poi(array("iconid" => "green-dot", "title" => "Standard Icon Example", "point" => array("lat" => 38.90279, "lng" => -77.037849))); $mypoi_2 = new Mappress_Poi(array("iconid" => "family.png", "title" => "Custom Icon Example", "point" => array("lat" => 40.7269, "lng" => -74.0087))); $mymap->pois = array($mypoi_1, $mypoi_2); echo $mymap->display(); Geocoding with PHP If POIs are defined by street address (rather than latitude/longitude) the geocode() method must be used before the map is displayed. This method geocodes the address and defaults the POI title and body, if they aren’t set explicitly. For example, to create a POI using the street address “500 Chestnut St” use: $mypoi = new Mappress_Poi(array("address" => "500 chestnut st, phildelphia")); $mypoi->geocode(); The above code geocodes the POI every time the map is displayed, so high-traffic blogs may encounter Google’s geocoding usage limit (see the ‘Geocoding’ section for details). If so, it may be better to generate the maps using custom fields, or use the Nominatim geocoder. Google Styled Maps For Google maps, pick a style from Snazzy Maps and copy the JSON code into the MapPress styled maps settings. To automatically apply the style to all maps, select the style under the ‘default style’ setting. Mapbox Studio Styles For Leaflet maps, use the Mapbox Studio online style editor to create and edit styles. The style can be used in MapPress by entering a name and the style URL (use the ‘share’ or ‘preview’ URL that starts with mapbox://). The new style will appear as a selection in the style control in the map editor. Reference Overriding Map CSS The default MapPress CSS styles are in the plugin file mappress.css. CSS styles can be overridden there, or in your theme’s style.css file, but those files will be overwritten when you upgrade the plugin or theme, respectively. Instead, WordPress recommends creating a child theme, and making any CSS changes there. CSS styles in child themes are safe from both theme and plugin upgrades. To override specific settings, just include the CSS class you want to override in your theme/child theme style.css file. Any settings there will take priority over the MapPress defaults. For example to set a 10px margin around the map place this line in style.css: .mapp-layout { margin: 10px; } In some cases it may also be necessary to override all of the default CSS styles. To do this select the checkbox “Turn off CSS” in the MapPress settings screen – but be sure to copy all of the map CSS styles from mappress.css to your theme’s style.css. Translation Support MapPress is fully translatable. All strings and templates are localized and can be translated using POEdit. A POEdit guide is available in the MapPress FAQ. Leaflet map controls are displayed using the current blog language. For Google, the API defaults to the browser language, but it can be forced to a specific language by entering a value in the ‘language’ setting in the MapPress settings screen. WPML MapPress fully supports the WPML translation plugin. The current WPML language takes priority over other settings, and all controls and texts are localized to that language, including the Google API map controls. When creating a WPML translation, there is an option to duplicate the content from the original post, overwriting the target (translation) post. During duplication, MapPress will: Delete any maps in the target (translation) post Copy all maps from the original post to the translation post Update all shortcodes and Gutenberg blocks to use the new map IDs The new maps can be edited in the translation language and will not affect the originals. This behavior can be switched off in the MapPress settings screen. Learn more about WPML and its Advanced Translation Editor. Settings The settings screen controls defaults for the plugin. Many settings can also be set for individual maps using the MapPress shortcode or template tags. Underlined settings are only available for MapPress Pro. Setting Description Mapping API Select the Google or Leaflet API Google API key In order to use the Google API, obtain an API key and enter it here. Mapbox Access Token If you are using the Leaflet API, optionally enter a Mapbox access token to use Mapbox map tiles and Mapbox Studio custom map styles. Geocoder If the Leaflet API is used, select a geocoder. See the Geocoding section for details MapPress license key Enter your MapPress license key. You can find the key in your account. Beta versions Select this checkbox to allow installation the latest versions of MapPress. It’s best to set this in development or staging systems, but not in live blogs. Post types Select the post types where you plan to use the MapPress Map Editor. This applies only to the classic editor. The MapPress Map and Mashup blocks are always available in the Gutenberg editor. Automatic display Automatically displays the maps attached to each post, without having to add a shortcode or insert a map block. Map alignment Set a default map alignment. This applies only to the classic editor, in Gutenberg the alignment is set with the block controls. Directions ‘Inline’ shows a simple from/to form before opening directions in Google Maps. ‘Google’ sends users directly to Google Maps with the destination already selected. POI list Show a table of POIs under the map POI list layout Select a layout for the POI list. ‘Left of map’ works best in most cases. Mini width Pixel width at which maps with a left POI list should switch to a ‘mini’ layout. In this layout, the map or list are shown separately and can be toggled by buttons at the button of the map. Sort Select the checkbox to sort the POI list alphabetically by title. Default zoom MapPress uses this setting to set the zoom level for POIs entered by latitude / longitude. This parameter is ignored for POIs entered as a street address or place; those POIs have a default ‘viewport’ that is used to set the zoom instead. Open first POI Set this checkbox to open the first POI when the map is displayed. Clustering Set this checkbox to enable marker clustering. Clustering MaxZoom Disable clustering beyond when the map is zoomed beyond this level Clustering Spiderfy Enable or disable the “spiderfy” feature that explodes clusters into individual POIs at the maximum zoom (Leaflet only, this is not supported by the Google marker clusterer). Search Set this checkbox to enable the search box for mashup maps. Search radius Search radius around the searched center. Note that this is the minimum radius. If a larger area is searched, like “USA”, then the radius is ignored. Bounding box Limit searches to the give bounding box (Leaflet only, not supported by Google). Filter Select a taxonomy to use as a filter with mashup maps. POI content Select what to show for the POI title and body in mashups: -the title and body saved with the POI, or -the title and excerpt for the post the POI is linked to. POI click Select what should happen when a POI marker is clicked. KMLs Select whether to include KML POIs in mashup maps (for example, region outlines are often used in individual maps, but do not need to appear in mashups). Thumbnails Check to automatically include featured image thumbnails in mashup POIs. The thumbnails are taken from the post each POI is linked to. Thumbnail size Select an existing thumbnail size for mashup images, or specify a size in pixels. Popup type When a POI is clicked a ‘bubbles’ opens with details about the POI. Select the standard Google InfoWindows or MapPress InfoBoxes. InfoBoxes can be styled using CSS (see the ‘mappress.css’ file) Default icon Select a default icon to use for all maps. Any POI that doesn’t have an icon explicitly assigned to it will use this icon. Custom icons directory Directory for custom icons. Custom icons Click to upload custom icons from your PC. Icon scaling Optionally select an icon size to use in maps and the POI list. Automatic icons Use the dropdown to automatically assign icons by post type, category, tag, or custom taxonomy. Styled maps If the Google API is used, provide a style name and enter JSON directly from the Google Styled Maps Wizard. For Leaflet, enter a style name and URL from Mapbox studio. See the section on styled maps for details. Default style Select a custom style to be used as the default on all maps. Custom styles can also be selected in the map editor ‘map type’ dropdown. Geocoding fields Select which custom fields to use to automatically create maps. The selected fields are combined and the resulting address is geocoded before the map is saved. Overwrite Check this box to overwrite an automatically-generated map when a post is published, even if the map has bee n manually edited. Geocoding errors If any geocoding errors occur, the most recent errors are shown here. The errors are also stored in a custom field for each post named ‘mappress_errors’. Templates Click to open the template editor to edit the templates used for POI popups and POI list rows. Maps and mashups have separate templates. Search language For Google, the language affects map tiles, map type and zoom controls, geocoding (search results) and directions. If no language is specified, Google will use the language setting from the user’s web browser. For Leaflet, the language setting only controls geocoding and search results. The default map tiles are always served in their ‘native’ language, e.g. Chinese for China. Mapbox tiles can be used if you prefer English labels. All other texts come from MapPress. See the FAQ for information on creating and editing translations. Country For Google, the country parameter is used to bias results to a certain country only when geocoding from custom fields. For interactive searches, results are biased based on the current map viewport. For Algolia and MapBox, this parameter restricts geocoding and interactive searches to only the entered country. For example, if the country code is set to “ES”, only results in Spain will be found. Directions server To use a local Google maps server (for example “maps.google.fr” or “maps.google.de”) enter the URL here. Scripts MapPress normally outputs scripts in the footer, and only when a map is being displayed. Uncheck this to output scripts in the header instead. This is usually necessary if you are using third-party plugins (such as infinite scrollers) that fetch content using AJAX. These plugins typically don’t allow script output in the footer. Map sizes Enter up to three default map sizes. These sizes are presented as defaults in the map editor. Force resize Resize all maps from a given size to a new size. Shortcode Parameters Underlined parameters are only available for MapPress Pro. Basic Parameters Parameter Values Default Description center lat, lng blank Specify a center for the map using a latitude/longitude, for example “-32, 22”. If blank, the center saved with the map will be used. For mashups and maps with no saved center, the map is automatically centered and zoom to show all of its POIs. height pixels or % Map height, for example “50%” or “400px” width pixels or % Map width zoom 1-21 Map zoom Other Parameters Parameter Values Default Description alignment center default left right default Map alignment hideEmpty boolean false Hide empty mashup maps (maps with no POIs) initialOpenDirections boolean false Open the directions form when the map is first displayed initialOpenInfo boolean false Open the first POI when the map is first displayed mapTypeId hybrid roadmap satellite terrain blank Map type to display. You may also use a custom style name if you have created custom styles in the MapPress Pro settings. name string blank Set the name for the map. If no name is provided, the first map on the page is automatically named ‘mapp0’, the next is named ‘mapp1’, and so on. poiList boolean false Display the POI list under the map scrollwheel boolean true Enable/disable scroll wheel zoom (Leaflet) scrollWheelZoom boolean true Enable/disable scroll wheel zoom (Google) Filters and Actions Filters mappress_filter_label ( $html, $value, $label, $iconid) Used to override the term labels in the mashup filters dropdown. The parameters are: html – the MapPress generated html for the term label value – the term slug label – the term name (the display label in WordPress) iconid – the icon to display for the term, if automatic icons are configured mappress_poi_iconid ( $iconid, $poi ) Called once for each POI, just before the map is displayed. Used to set a specific icon for each POI. The $iconid parameter contains the icon ID of the icon that would normally be displayed, and $poi contains the POI object. Actions mappress_map_display ( $map ) Called once just before a map is displayed. The map is passed by reference, so it can be modified – for example to add or remove POIs, change icons, etc. mappress_sort_pois ( $map ) This action is called just before a map is displayed. You can use it to apply your own sorting routines. For example, to sort POIs by title in descending order, add the following code to the functions.php file: function mysort($map) { usort($map->pois, 'reverse_sort'); } function reverse_sort($a, $b) { return strcasecmp($b->title, $a->title); } add_action('mappress_sort_pois', 'mysort'); mappress_save ( $map ) This action is called after a map is saved to the database. mappress_delete ( $map ) This action is called just after a map is deleted from the database. Frontend Forms MapPress is compatible with a number of popular front-end forms plugins. Advanced Custom Fields (ACF) MapPress fully supports ACF. There are two ways to handle ACF data: Generate MapPress maps from ACF fields or Automatically include ACF maps in MapPress mashups Regardless of which approach is used, the first step is to set add up your theme to display ACF fields and provide a Google Maps API key to ACF, as described here. Generate MapPress Maps from ACF Fields If you plan to use MapPress to edit maps on the backend, you can generate MapPress maps from ACF text or map fields as described in the geocoding section. For example, a form might contain several address fields, which can be configured to generate a MapPress map when the form is saved. Only text and map fields are supported. Other types won’t work, such as checkboxes, textareas, editors, etc. To use a map field, just link the ACF map field name to the MapPress ‘Address line 1’ field. When the ACF form is saved, a MapPress map will be generated from the map location. Here’s how it would look if the ACF map field is named ‘acfmap’: Include ACF Fields in Mashups If you plan to use ACF to enter and maintain your maps, it’s not be necessary to generate a MapPress map from the ACF form. Instead, the ACF map locations can be included directly in MapPress mashups. This allows you to leave the map data in ACF, while still using the search and filter functionality of MapPress. Just enter the ACF map field name in the ‘Frontend Forms’ part of the MapPress settings. When a mashup is displayed, the ACF map locations for the selected posts will be included. Here’s how it would look if the ACF map field is named ‘acfmap’: Formidable Forms If you’re using the Formidable Forms plugin, you’ll need to use this approach to trigger the map update when a form changes: function my_meta_update($entry_id, $form_id) { // Replace '17' with your form ID if($form_id == 17) { //get ID of post to be created global global $frmdb; $post_id = $frmdb->get_var( $frmdb->entries, array('id' => $entry_id), 'post_id'); // Update the map for that post do_action('mappress_update_meta', $post_id); } } add_filter('frm_after_create_entry', 'my_meta_update', 50, 2); Examples Open a POI Using Javascript The method getPois() can be used to retrieve an array of all of the Map’s POIs. The open() method can be used to open a POI. For example, to open the second POI (1) on the first map (‘mapp0’): var pois = mapp0.getPois(); pois[1].open(); Or: mapp0.getPois()[1].open(); MapPress is the leading Leaflet and Google Maps Plugin for WordPress. Try the free version, or get MapPress Pro for professional maps. © 2020 Chris Richardson and mappresspro.com