# About Welcome to Mapster WP Maps! **Mapster WP Maps** is a Wordpress mapmaking suite that makes things straightforward for you and can even turn your Wordpress installation into a full geographic backend. You can create geographies to use across multiple maps, style popups in totally customizable ways, create and use custom base maps, and set up category filters and more. We provide a free, no-API-key-required mapping service ([MapLibre](https://maplibre.org/)) as well as giving you access to the powerful [Mapbox GL JS library](https://www.mapbox.com/mapbox-gljs) in its latest version. We also integrate the [Google Maps API](https://developers.google.com/maps). If you need more features, take a look at the existing [Pro Features](https://wpmaps.mapster.me/pro) and don't hesitate to get in touch with us. We also have a [site with lots of examples](https://wpmaps.mapster.me/examples/) you can poke through and see in action! # Installation Install like any other Wordpress plugin. [Download the zip](https://wordpress.org/plugins/mapster-wp-maps/) and upload to Plugins, or install using the Wordpress Directory in your Admin panel. {% embed url="" %} Basic Installation Instructions {% endembed %} # Key Concepts Learn about how to understand the Mapster plugin if you're having trouble getting started. Because the Mapster WP Maps plugin is quite extensive, it can be a little overwhelming at first if you just want to create a really simple map. If you're struggling, understanding a few key concepts might help. ### Maps [Maps](/maps/map-tiles) are like the canvas upon which you place your geographies. You don't *create* geographies in maps, though. This is so that the options don't get too overwhelming! There are a ton of options for how to style, load, and add controls to your maps, which you can explore by just clicking around and trying things out, or using this documentation alongside the Map editor to learn about each individual option. ### Geographies Geographies are the things that go onto the map. These come in a few forms: * [**Locations**](/locations/markers) (AKA Points) - includes markers, circles, icons, and labels. A single coordinate pair of longitude and latitude. * [**Lines**](/lines/lines) - An array of coordinates that make up a continual line * [**Polygons**](/polygons/flat-polygons) - A set of coordinates that create an area ### Popups Popups can be attached to any geography. They can be opened through clicking, hovering, or some other ways that you'll discover (such as opening on load or by clicking on a list). Because the ability to style your popups is usually really important to your map and cohesive site design, we created a system that lets you completely customize popup structure and where certain information, like the title, link, or descriptive information, appears. There are also options to display popup information in modals or sidebar displays. * [**Popup Templates**](/popups/popup-templates): this is where you create "templates" for popups that you can then assign to specific geographies * [**Popup Contents**](/popups/popup-content): on each individual geography, you can specify the content that should appear in the popup. This can also be done dynamically with custom fields. ### Importing Mapster WP Maps incorporates a lot of different ways to [import data](/import), whether from GeoJSONs, shapefiles, KML files, GPX, CSV, and more. You need to use Web Mercator projection. You can also import CSVs that will refresh imports on a regular basis. There are very extensive importing options available that take some time to learn if you want to deal with a lot of points. # Importing/Exporting There are a ton of options for importing your data to Mapster. [Head to the Import page to see details on how to do so](/import)! # Guides # Your First Map ## Creating Geography Features You can create a map without any geographies, but you probably want to at least show a point or an area on your map. To create a geography, select a Location (point), a Line, or a Polygon from the left hand side under "Maps" in your Wordpress menu. ![](/files/hoamrQk6JP3UmLdCt3o2) For the sake of simplicity, let's create a single Location for this map. Locations come in a few flavors: circles, markers, and labels/icons. We'll just create a simple Marker. Click on Locations and you'll see the screen below. ![](/files/lasLp6Q3KqvdypbZLUvs) Click to add the marker to the map, or just search an address anywhere on Earth in the search bar. Your marker will appear. Make sure you give a title to this post so you can find it later. You can adjust some settings below the map, such as color, opacity, etc, and then save the Location post. {% hint style="info" %} Learn more about [Creating Locations](https://wpmaps.mapster.me/documentation#0). {% endhint %} ## Adding Locations to a Map Now, you'll have to create a map to show this location on. Click on Maps on the left and add a new Map. ![](/files/EXM7k4ZDBNwEWAvBl2q6) To keep it simple, let's just keep all the settings as default. Go to the "Features" tab under the map, and click on the Locations input. There, you'll see the title of your marker Location appear. Once you click it, it'll appear instantly on the map. ![](/files/BTwLCgsKulsSOtBo16ve) Now you can try viewing this post directly to see the map with your Location on it. Or, go back to the main list of maps and get the shortcode for the map, and place it on any Page or Post in your site! ## Defining Access Tokens / API Keys To use Mapbox GL JS instead of MapLibre, you'll need to get an access token from Mapbox. [Read more about that here](https://docs.mapbox.com/help/getting-started/access-tokens/). This access token is also needed for certain controls, specifically geocoders. If you're using Google Maps, you'll need to enter [an API key](https://developers.google.com/maps/documentation/javascript/get-api-key) into the Maps > Settings page. ![](/files/IpZNhYmeWxFprzEm3DVH) Once you have the access token or API key that you need, enter it into the Settings screen, or into a single Map if you don't want to set a default settings token for the whole plugin at once. # Creating a Crowdsourced Map Coming soon. # Set Up Recurring Import Make an import that comes from some other data source and regularly updates your WP installation. A recurring import can be a great way to sync some external database or data source with your WP installation. That way, you can style things the way you want through Mapster, have popups open and managed there, but still have your core geographic data updated however often you like. Here's a walkthrough on getting it working. ### Get Familiar with the CSV Format for Mapster The CSV format is quite deep. You can see a [sample spreadsheet here](https://docs.google.com/spreadsheets/d/1RQ4PzT4g5bjmY0dwiOfJ3YUgThnM4ZJuVSU-6rWQM1Y/edit?gid=762889436#gid=762889436) . The first tab of this spreadsheet explains a little bit about the format, and the second page is the actual example. The best way to understand this is to look at the sample spreadsheet and see which values you need to enter. For example, say I had a list of points and wanted to simply add those points and titles. The only fields I would need are: * `spreadsheet_id` (a unique ID that you choose for each point. This allows the program to overwrite the point when importing again, instead of just making a new point) * `post_title` * `lat` * `lng` That's it for a really basic import! Let's say you wanted to add something into the content area of the popup. You would add a column with this header: * `mapster_popup_popup_body_text` How did I find this? Well, in the Import section of the Mapster plugin (Maps > Settings, then click Import, then Live CSV) you can see a button that says "See all Mapster property fields".
If you click on this, you'll download a CSV file. If you open this, you can see ALL the available fields that you can set as column names. There are also some hints as to the kind of value you can put in them — some are numbers, some are strings, etc. This gets complex but for most fields, it should be fairly easy to figure it out. ### Do your first import Next, you need to create some way to get your data from whatever source you're using into Google Sheets. We need to use Google Sheets for recurring imports that happen automatically, because they are hosted online and therefore are always available. This might involve some more complex stuff, or just copy-pasting values, depending on your workflow. But once you have a Google Sheet, you have to make it public and get the right URL. {% hint style="info" %} To get the URL from your Google Sheet, you must go to File > Share > Publish to Web. Select "Comma-separate values (CSV)" from the dropdown under "Link" (by default, this says "Web Page"). Press Publish and you will recieve a URL. {% endhint %} Once you have that URL, enter it into the Enter URL input in the Import section and see if Mapster gives you any warnings. If not, give it a try! See if your shapes imported. If not, try to see where the error might be, or get in touch with us for help. ### Make the Import Recurring Next up, after you're verified that your format works, you can set up a recurring import to happen every X number of minutes, hours, or days automatically. This is controlled by [WP Cron](https://developer.wordpress.org/plugins/cron/), a Cron system inside Wordpress that runs tasks on a regular basis. By default, there aren't a lot of options for the timing of the Cron jobs. However, we'd recommend installing [WP Crontrol](https://wordpress.org/plugins/wp-crontrol/), a pretty straightforward plugin that lets you set your own cron job intervals. Once you've set it up, they'll all appear in the dropdown after you paste a particular CSV file.
Just select the one you want, hit Create Recurring Import, and you're all set! # Adding a Custom Style Coming soon. # Building a Custom Popup Coming soon. # Creating Shapes Learn about creating features for your maps In Mapster WP Maps, we classify geography types in three ways: [Locations](/locations/markers), [Lines](/lines/lines), and [Polygons](/polygons/flat-polygons). All features are set in Wordpress as different custom post types, so they can be fully SEO-compatible (if you wish) and can live as their own posts. You can also reuse them across multiple maps, so you don't have to create any shapes twice. ### Add / Edit / Delete Adding Locations, Lines, or Polygons is done by simply clicking on their menu item and pressing "Add New" on the post listing screen. Inside each geography post type, you'll find a plethora of options for how to customize and modify each type of geography. You can easily Duplicate any created Location, Line, Polygon, Map, or Popup Template by hovering over the post in its list, and clicking the "Duplicate" link. For every type of Geography Type, you can create it and edit it by drawing directly, or by uploading a pre-created geoJSON for that geography type. If you assign a shape a category, you can add shapes en masse to a map using that category, too. {% hint style="info" %} Please note that the *oldest* shapes will appear on top, so if you want to make sure your features are layered properly, edit the published date of your shapes. {% endhint %} ### Fullscreen Editing You can expand the size of the Editing map by pressing "Expand" in the corner of the map. ### Download GeoJSON You can also download the geoJSON from any geography type, in case you need to use it in another application. ### Custom Editing Basemap You can also set a custom basemap to use for editing, such as your own Mapbox Style, if you prefer. This is available only in [Mapster Pro](https://wpmaps.mapster.me/pro). To set this, add a Mapbox Token and then in Settings > Advanced Options, set the style URL in the "Editing Map Style" textbox. ### Post Display Options You can choose to show individual maps on the posts for each geography type by turning on "Show Map in Post" in the sidebar. You will then need to select a **Template Map** from your existing Maps. This map will have all its default features removed and will just be used a base for your single feature.
# Displaying Maps Learn about the options for displaying your map to users. After you've made your map, you've got to show it off to everyone! There are a few ways to do this with Mapster WP Maps. * If you use Gutenberg, there is a "Map Select" block, where you can choose from the maps you've created, and everything will be automatically taken care of for you
* If you want to use Shortcodes directly (as in a widget, or on a post), you can find the shortcode on the Map Editing List (on the right-hand side, near the date you created the map) and copy-paste that shortcode where you like The following parameters are available for the shortcode `[mapster_wp_map]`: * `id` -- this specifies the Wordpress ID of the map to be displayed * `zoom` -- this specifies a custom zoom level that will override the one set in the map options * `latitude` -- specifies a custom starting latitude, overriding map options * `longitude` -- specifies a custom starting longitude, overriding map options * `single_feature_id` -- used to display a single feature (a Location, Line, or Polygon), using the `map_id` as the base template (without any of its default features showing). Use the Wordpress ID for the feature * `feature_ids` — similar to single\_feature\_id, this allows you to load multiple features manually into your shortcode. Just separate the IDs with commas.
* You can use the map post directly and view it as a post, and it will automatically contain the map you created for it Please let us know if you need more options! # Map Tiles Details on the options available in the Map Tiles section of the Maps edit page. ### Map Provider You must choose a **Map Provider**. This is the only setting that requires an "Update" of the post and reload in order to change. This is where the map tiles will be loaded from and affects the general map functionality available to you as well as the basic look of the map. {% hint style="warning" %} You need to enter a [Mapbox Access Token](https://account.mapbox.com/access-tokens) in order for the "Mapbox" option to work! If you're using Google Maps, [you'll need an API key](https://developers.google.com/maps/documentation/javascript/get-api-key). {% endhint %} ### Access Token *\[Mapbox]* You can set an **access token** for a map specifically, or, if you've entered a Default Mapbox Access Token in your settings, it will automatically appear when you create a new map. {% hint style="info" %} For Google Maps API Key, you need to enter that in the **Settings** area of the plugin. {% endhint %} ### Map Tile Style *\[Maplibre, Mapbox]* Click the button to open a selector for many different map styles. There are **Free Styles**, which are usable with Maplibre with no access token. Then there are **Mapbox Styles**, usable with an access token from Mapbox. Finally, there are **Mapster Pro Styles**, which are available in the [Pro version](https://wpmaps.mapster.me/pro/) of the plugin. If you have any suggestions of more styles to add, please let us know. ### Snazzy Map Style *\[Google Maps]* Then you can enter in a string from [Snazzy Maps](https://snazzymaps.com/) here to style your Google Map the way you want. ### Custom Style URL *\[Maplibre, Mapbox]* If you're using Mapbox and you've created your own Style that you want to use, enter the style URL here. You can find this from the Styles page or when editing/saving a Style in Mapbox.

Finding a style in Mapbox.

### Custom Style JSON *\[Maplibre, Mapbox]* This is for adding other providers, including custom tilesets, maps from Maptiler, or other sources. Make sure that you understand the [Mapbox Style JSON](https://docs.mapbox.com/style-spec/guides/) and replace the elements you need and paste into this box. ### 3D Terrain *\[Mapbox]* Add Mapbox [3D Terrain](https://docs.mapbox.com/mapbox-gl-js/example/add-terrain/) to the map. ### 3D Buildings *\[Mapbox,** **Pro**]* Add Mapbox [3D Buildings](https://docs.mapbox.com/mapbox-gl-js/example/3d-buildings/) to the map. ### Globe *\[Mapbox,** **Pro**]* You can display the map as a 3D globe here. You can also select the **Globe Background** and make it transparent or a Stars & Fog look. ### Projection *\[Mapbox]* You can choose from amongst a variety of Mapbox-supported projections. ### Language *\[Mapbox,** **Pro**]* You can select from amongst a set of Mapbox-supported languages. ### Duplicate Horizontally By default, the map will scroll infinitely to east and west. If you only want one copy of the map, adjust here. # Initial View Select from the options available for initial load of your map. # Fit to Features Automatically zoom and center the map so that all of the geographic features you've added to it appear visible, regardless of the device being used. ### Manual Pitch You can still adjust the pitch, or angle, of the map. ### Manual Rotation Adjust the bearing, or heading, or rotation, of the map. ### Padding Around Bounds To make sure your geographic features aren't butted up against the edge of the map, enter a padding. # Manual Values Customize the starting point and view of your map completely. ### Set From View Zoom and adjust the map and then press this button to automatically set all of the values below with values that represent the current map. ### Manual Latitude Adjust the center latitude of the map. ### Manual Longitude Adjust the center longitude of the map. ### Manual Zoom Adjust the zoom level of the map. ### Manual Pitch You can still adjust the pitch, or angle, of the map. ### Manual Rotation Adjust the bearing, or heading, or rotation, of the map. # User Location Use user IP to roughly set the start of the map. ### About User Location *\[Pro]* It is fairly imperfect as it only uses the user IP using a free service to set the rough user location, and can easily be wrong or misled by unusual IPs. There are also technical restrictions (the free IP checker service won't work on HTTPS sites). For best results for opening the map on the user location, look at the [Geolocation Control](/maps/controls/geocoding-and-geolocation). ### Manual Zoom Adjust the zoom level of the map. ### Manual Pitch You can still adjust the pitch, or angle, of the map. ### Manual Rotation Adjust the bearing, or heading, or rotation, of the map. # Map Size Set the layout specifications for how your map appears on the page. ### Height & Units Select a numeric value and a unit. ### Width & Units Select a numeric value and a unit. ### Add Mobile Breakpoints *\[Pro]* In [Mapster Pro](https://wpmaps.mapster.me/pro/), set up to two breakpoints for resizing the map to specific widths and heights in different screen sizes. First set the **Breakpoint pixel width**, then the adjusted height and width of the map. ### Full Page Make your map take the full width and height of the user screen size. It will still be constrained by any container the map is placed in on the page. ### Ignore Container The map will sit outside of any container and take up a full height and width on the page, making it a truly full screen map. ### Map Only Remove all other HTML from the page so it's only the map visible. # Points, Lines, Polygons Add geographic features to your map. ### Locations, Lines, & Polygons (Adding Individually) To add individual geographic features one-by-one, make sure you first create them in the appropriate section of the WP Admin (under Locations, Lines, or Polygons). Then, when you click these dropdowns, you can select specific posts or type their titles to find them and add them. If you've created a 3D Location, please make sure to turn on the **Load 3D Model Libraries** button if you are adding one to this map. ### Add By Category If you have assigned shapes to categories, you can add them en masse to a map using that category. These will update automatically as new features get added to those categories. ### Add Custom Posts *\[Pro]* If you've added the [Mapster Map ACF Field](/developer/mapster-map-acf-field) to any other post types in your installation, you can add those individual posts here! ### Add Custom Categories *\[Pro]* If you've added the [Mapster Map ACF Field](/developer/mapster-map-acf-field) to any other post types in your installation, you can add posts by choosing categories across any taxonomy on your Wordpress site, instead of adding posts one-by-one. # Clustering Group points into clusters for easier navigation and viewing. ### Feature Clustering Different kinds of Location Styles (Circle, Marker, Label & Icon) will not cluster together. To enable clustering for the types of locations you've added, **please make sure you select the correct type of clustering**. ### Cluster by Category *\[Pro]* Cluster by Category allows you to break up clusters into totally different groups depending on the categories of the Locations you've added. You'll want to make sure that Locations are exclusive -- otherwise, the system won't know which cluster to assign a Location to. Select the **Categories to Cluster.** Categories you don't select will still be broken into individual features on the map. *Please note: currently this only works with Marker type locations.* Then, you can give the color for these clusters in the text box below. You need to enter a different hex code on each line, in the same order as the categories you selected above. ``` #FFFFFF #1b6a3d #000000 ``` The clusters will be the same color regardless of how many features are in the cluster. ### Cluster Coloring & Sizing *\[Pro]* Cluster Options allow you to change styling information, in close detail, on your map. This applies globally -- ie, *all* clusters on the map will be styled the same way. Clusters are broken into three sizes: **Small, Medium**, and **Large**. For each of these cluster sizes, you can define the **color**, the "**count**" that defines how many points means a given cluster is Small, Medium, or Large, the **border color**, and the **border width**. This allows you to make clusters really work with your overall style and layout. ### Image on Cluster *\[Pro]* Add an image for your cluster instead of the default coloured circle. The image should not be more than 150x150 pixels in size. The number associated with the cluster will still appear in the middle of the image. # Interactivity Define how users can interact with your map. ### Zoom on Scroll Users can use their mousewheel or touch to zoom the map. Turn this off to prevent users from getting "stuck" on the map while scrolling through a page. ### Interactivity Turn off all interactivity with the map (zooming, panning, clicking, etc). ### Cooperative Gestures *\[Pro]* Cooperative gestures require the user to press a button or use multiple fingers to scroll. ### Allow Rotation and Pitch Modify the ability for users to rotate and angle the map without affecting other interactivity. ### Open Popups in Sidebar Instead of popups opening in their little popup windows, open them in an HTML sidebar instead (which will be placed on top of the map. You can set the **Minimum** and **Maximum** sidebar width. ### Restricted Movement *\[Pro]* Restrict the ability for users to move beyond a certain **bounds** (defined by a set of corner points) and/or restrict their zooming between two given zoom levels. # Controls # Basic Controls Standard controls for your map. ### Zoom Control Adds a +/- button, along with a small compass that allows users to quickly revert to north if they've rotated the map. ### Scale Control Adds a [translucent scale](https://docs.mapbox.com/mapbox-gl-js/example/navigation-scale/) onto the map. ### Fullscreen Control Add a button that allows users to make the map cover the entire screen. ### Attribution Control Move around the required attribution text for your styles. ### Logo Modify the position of the logo included with Mapbox or Maplibre. ### Map Type Control *\[Google Maps]* Allow users to switch between satellite, street, and other map types. ### Street View Control *\[Google Maps]* Allow users to access Street View. # Geocoding & Geolocation Controls for making it easier for your user to locate places on the map. ### Geocoder Control *\[Requires Mapbox access token]* Allows users to search for real-world locations and zoom to them quickly on selection. * **Limit results** by country code (use [2-letter country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) * **Limit results** by bounds * **Allow users to enter coordinates** directly when searching for a place *\[Pro]* * **Modify the search placeholder text** * **Change the marker color** automatically placed *\[Mapbox]* ### Geolocation Control Allow users to quickly find themselves on the map by pressing a button. * **Geolocate on map load** *\[Pro]* * **Show a circle around the user point** that represents accuracy of the geolocation *\[Pro]* * **Show user heading** (direction the user's device is pointing) *\[Pro]* * **Track user location** by updating the position automatically as the user moves *\[Pro]* * **Enable highest possibly accuracy** of the user's device (browsers are less accurate than mobile devices) ### Directions Control *\[Requires Mapbox access token]* Add a directions interface for entering start and end locations. * **Change units** between metric and imperial * **Change default directions type** between Driving/Traffic, Driving, Walking, Cycling * **Change placeholder text** # Togglers Controls that enable and disable certain effects on the map. ### 3D Control Quickly change the map from a top-down view to an angled view to leverage 3D layouts. ### Layer Control *\[Mapbox, Maplibre,** **Pro**]* Adds an area for users to turn off and on different layers on your map, as defined in your Mapbox Studio Style or in your Custom Style JSON. [See an example here](https://wpmaps.mapster.me/examples/mapster-wp-map/layer-control/).

Simple Layer Control.

In the left-hand side text area, you can enter layers on each line that you want to turn off and on when the user toggles them. You can add multiple layers to each line by separating them using commas, such as ``` country-label, admin-0-boundary ``` Make sure these layers correspond correctly to the layer names you've given in Mapbox Studio -- otherwise your map will have an error! On the right hand side, add the text that you want to show for each of the toggles. Choose the **Checkbox Type**, which can be switches, checkboxes, or radio buttons. Radio buttons mean that only a single set of layers can be shown at once. If you select this, make sure that only one of your layers is visible on the map load, otherwise the control may turn layers off by accident. {% embed url="" %}
Screenshot examples of entering layers into editor

A simple layer control toggling single layers by checkboxes.

A more complex layer control, with some buttons toggling multiple layers.

### Style Switcher Control *\[Mapbox, Maplibre,** **Pro**]* This adds an area on the map with a list of styles that you choose that users can toggle between. [See an example here](https://wpmaps.mapster.me/examples/mapster-wp-map/style-control/).

Simple Style Switcher Control.

To set this up, go to Controls when creating your map. Make sure you are not using a Google Map, and turn on the Style Control. Then, enter in each Style URL or Custom JSON in the left-side textbox, and titles on the right-hand side. Each entry should be on a different line so that the plugin can associate the correct style with the correct title. If you are using a Custom JSON, make sure to use a tool like to remove all line breaks from your JSON before pasting it in. A couple examples of this are shown below! {% embed url="" %}
Screenshot examples of entering styles into editor

A simple Style Switcher using Mapbox Style URLs.

A more complex Style Switcher with custom JSON data.

### Control Menu *\[Pro]* Put controls into a toggleable menu in order to preserve space on the map. Controls you've added will be visible here and you can reorder them as desired. # Other Controls Controls that are hard to categorize :) ### Download Control *\[Pro]* Adds the ability for users to download the current data visible on your map as a CSV. * **Let category filters affect data download** or not * **Notify specific users when download occurs** via email * **Include only the fields you prefer when users download data**. To find the names of the fields, download the full CSV and use the header names you see there to exclude them using comma separation ### Print Control *\[Pro]* Allow users to export a quick PNG of your map for use in other applications or to print. {% hint style="info" %} We are looking into adding more customization to this control, such as different formats and 300 DPI exporting. Please get in touch if this is an important feature for you and we will try to accomodate! {% endhint %} ### Custom HTML Control *\[Pro]* Add totally custom HTML. This is suitable for a legend or any custom interactive material you might want to show. [See an example here](https://wpmaps.mapster.me/examples/mapster-wp-map/custom-html-control/). You can enter HTML and CSS if you put it into a style tag, like the image below.
# Control Render Order Take control of how your controls appear on the map. While you can position controls in different areas around the map in the free version, in Pro you have access to: ### Control Order *\[Pro]* All the controls you've added to your map will appear here. **You must save your map first before they show up**. Once they are visible, just drag and drop them to reorder the render order. If you have multiple controls in one part of the map, they will then be changed to the order you've given. # Filters # Category Filter Allow users to toggle features on and off based on different categories. The Category Filter creates a toggleable list of Categories that you have associated with your Locations, Lines, and Polygons added to the current map. These are presented in a list, and include parent and child relationships. Users can toggle checkboxes on or off, thereby adding and removing different features from the map. You can initialize features as on or off depending what you require. Categories will also display hierarchically if you have child categories. {% hint style="warning" %} Any feature that has a child category should **also** have its hierarchical parent categories, otherwise the layout may not work properly. {% endhint %}

A basic example of the category filter.

### Category Display Select if categories will show colors, icons, or nothing beside them. These colors and icons can be defined in the *Categories* section of the Wordpress plugin (inside Maps > Categories). ### Checkbox Display Pick whether your categories will be toggled with switches or checkboxes. ### Advanced Features *\[Pro]* {% embed url="" %} ### Show Number of Features *\[Pro]* Display the number of features included in a given category in parentheses. ### Functionality *\[Pro]* This applies to cases in which features may have more than one category or filterable property. Filters are *exclusive* when any of the properties or categories being turned off means the feature disappears. *Inclusive* means that all of the properties or categories must be turned off before the feature disappears. ### Independent Children *\[Pro]* Child categories will function independently of whether or not their parent category is turned on. For this, you'll want to make sure that your child categories don't have the parent category clicked on (or, use inclusive filtering). ### Parent Category Display *\[Pro]* Choose whether you want parent categories to show checkboxes or only be used for visual structural organization of their child categories. ### Excluded Categories *\[Pro]* Select any categories that should not be shown in the category filter. ### Initial Visibility *\[Pro]* Set whether categories should be on or off when the map first loads. ### Preselected Categories *\[Pro]* If you turn initial visibility off, you can still choose individual categories that should be started as visible. ### Category Order *\[Pro]* Allows you to have the categories appear, both parents and children, in whatever order you want. ### Reset Button *\[Pro]* Adds a button to reset all categories to their original loaded state. ### Additional Filters *\[Pro]* Use properties from your geographic data (imported or added onto posts), or ACF data, to create additional filters. First, you'll need to make sure your features actually have the data. You can see properties from geographic data in any given feature under "Custom Properties", and ACF fields will show up in the appropriate post types.
Next, you'll use some special syntax to tell the Category Filter which properties to include under which headers. The syntax looks like this: ``` property_name : Label acf_property_name : Label 2 ``` If you are using a Custom Property, enter the property name only (no acf\_ required) and then the label you want to show for that property heading, separated by a colon. Unlike the Advanced Popup, you don't need to get the field ID from ACF, and you don't need to use curly braces. Just enter the "name" of the ACF field, or the name of the property. This feature will run into problems if you have a property and an ACF field with the same name, though. If you've added these correctly, they will now show up alongside your categories in the Category Filter, and will integrate completely with the Inclusive and Exclusive filtering. ### Render in External Div *\[Pro]* The category filter will render into a div of your choosing on the page, instead of appearing directly as a control on the map. This can free up space in the appearance of your map. ### Accordion Layout *\[Pro]* Makes a neater appearance by having categories render in dropdown expandable rows. Nested categories can be rendered as an accordion, which will open the first parent automatically and then only open other parents when they are clicked open by the user. This is great when you have a lot of categories. # Custom Search Filter Let users search through your features in a list dropdown. The Custom Search Filter will give the user an input box to type into, and using their text, it will search through the post titles and popup text you've added in order to present clickable results that will zoom to the relevant feature. If you want, you can include a geocoder with this -- meaning that users will be able to search both the features you've added *and* real-world locations together. Your features will always appear first in the list if any match is found.
### Include Geocoder *\[Requires Mapbox access token]* Allow users to search both general address and your feature information at the same time. * **Limit results** by country code (use [2-letter country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) * **Modify the search placeholder text** ### Number of Results *\[Pro]* Adjust how many results are returned maximum ### Search Type *\[Pro]* Adjust whether search results must find an exact match, match any term, or match all terms entered. [You can see examples here](https://wpmaps.mapster.me/examples/#controls-filters). For instance, if you have three points, and they have the titles: * Bear Lake Station * Station Grudge Bear * Lake Bear Station And someone searches "Bear Lake", then: * With Exact Matching, "Bear Lake Station" will show up * With Any Term, all three will show up (all match "Bear") * With All Terms, "Bear Lake Station" and "Lake Bear Station" will show up ### Embed on Separate Page *\[Pro]* To make a unique landing page that users can use as a portal to search your map like on popular real estate websites like AirBNB, use the shortcode generated in this section. You can then style the front-end search form to make it look how you want and have it direct users to specific popups, locations, or shapes on your map. # Filter Dropdown A simple list of features on your map presented in a clickable set. The Filter Dropdown is a simple list of the features on your map, through which users can scroll in order to find a specific feature. Use this if you don't have a huge number of features on your map. ### Display Images *\[Pro]* Show the featured image from the popup in the list above the title. # Lists Make a clickable list of all the features shown on your map. The List is an interface that will present locations to your users as a list on your map. This is perfect for creating a [Store Locator](/maps/lists/store-locator).

Simple list with geocoder.

### Include Geocoder If you want to include a location search on top of your list, use the Geocoder Control in the "Controls" section, and it will interact naturally with the List. ### Sort by Distance Sorts by the distance of the current map's center (adjusting as user searches or moves). ### Show Distance Show distance from the map center to the shape's center. You can also choose the **units**. ### Listing Type You can make the list eternally scrollable, or have it break into paginated sections. If paginated, you can choose the **number of locations** to show on the list at a single time. ### Render in External Div If you want the list to render outside the map in a custom div, put the div ID here. ### List Order *\[Pro]* Automatically sort the items in your list by menu order, title, slug, or ID. By default, they render by date. ### Display Images *\[Pro]* Show thumbnail images above the title in the list. ### Group by Category *\[Pro]* You can group items together by their categories into individual accordion lists, further compressing your list. # Store Locator An advanced List that creates a customizable list of locations. Store Locators are one of the more complex and useful pieces out there for everyday mapmaking. We've added a lot of features into this addon to help you get started making a pretty and functional Store Locator for your site. [See an example here](https://wpmaps.mapster.me/examples/mapster-wp-map/sample-store-locator/). {% hint style="warning" %} **When you've installed Pro, first, go to Settings and turn on the Store Locator**. Then proceed to the rest of the instructions. {% endhint %} {% embed url="" %} ### Adding Locations With the Store Locator, you add Locations the same way you normally would with any Mapster map. Add Locations by going to Maps > Locations, and adding them one by one. There will be a new set of fields under the content in the Locations, called "Additional Details". You can turn this on to add more information about any given location. This includes entering an **address**, **phone number**, **hours**, **website***,* and **social media links**. For every type of Geography Type, you can create it and edit it by drawing directly, or by uploading a pre-created geoJSON for that geography type. You can also enter a short description that will appear when a user clicks on a specific location. To make it easy for yourself, create a category and add all your Locations to that category, so you can add them easily and quickly to your map later on. ### Making the Map Once you've created your Locations, create a new map. Add your locations inside the Features tab by selecting the category you created to hold the locations, and all your locations should be added to the map. Now, to add the sidebar that allows users to search for locations, click on them, see hours, and more. Go to the Filter & List tab, and scroll down to List. Enable this, and then scroll down more and you'll see "Store Locator Options". Turn on "Enable" to turn on a special interface more appropriate for Store Locators. You can see an example in the screenshot below. You can also sort the hours you assign to locations by days rather than having them appear from the beginning to the end of the week. This means that, based on the current day, the hours for today will show up first in the store locator listings. {% hint style="info" %} You may want a full-screen Store Locator. To do that, turn on the full screen replacement in your Map by going to Setup > Layout, and selecting the Full Page and Ignore Container options. {% endhint %} # Specialty Maps # Map Comparer Show two maps at once with a slider, allowing exact comparison. Creating a map that shows two different maps at once, with a slider between them, is a great way to show change over time in a map. Creating this is quite straightforward when you're using Mapster WP Maps. This works in both Maplibre and Mapbox maps -- but you can't mix them. You must compare two Mapbox maps or two Maplibre maps. [See an example here](https://wpmaps.mapster.me/examples/mapster-wp-map/map-compare-example/). {% embed url="" %}

Users can slide back and forth or move around the map to see changes over time.

First, you will need to create your two maps. These are created as normal in Mapster WP Maps. However, you should bear in mind that it's probably best to make sure both maps have the same starting zoom, center, pitch, and rotation. That way, when the map comparer loads, it will be in the same place for both maps. It's also best if you make your more heavily featured map as your base map, so that loading will happen efficiently. You can make sure your maps have different Styles loaded, or just maps with different markers and geographical features loaded in. Anything normally added to your map will be visible in the comparer. Next, in the map you want to appear on the left-hand side, go to your Map edit page. Go to Specialty Maps > Map Compare, and turn it on. Then select the map that will appear on the right side of the map slider. Voila! # Heatmaps Heatmaps are a great way to show large amounts of data. Mapster WP Maps Pro offers a lot of options when it comes to creating a heatmap and managing it directly inside Wordpress. This requires a Mapbox or Maplibre map. [See an example here](https://wpmaps.mapster.me/examples/mapster-wp-map/heatmap-example/). {% embed url="" %}

Map with some simplified earthquake data.

The functionality of the heatmap in Mapster WP Maps Pro is very similar to the [example shown here](https://maplibre.org/maplibre-gl-js-docs/example/heatmap-layer/) in the Maplibre documentation. First, you need to create the Locations for your heatmap. This would be done most efficiently by [importing](broken://pages/MauPr4OctdMGXj1MWFKN) many features at once and assigning them a common category. Once they are imported, create a new Map and add those features to the map. After you've added the features, go to Specialty Maps > Heatmap and enable the heatmap.
You'll need to choose the Location Type to turn into a heatmap with **Heatmap Layer**. All of the geographic features of that type will be substituted with a heatmap. **Layer Visibility** allows you to cause the original features (markers, circles, or icons) to reappear once the user zooms in far enough. This can allow users to open popups or see the exact location of data once they are zoomed in to a certain level. If your data has a specific property you'd like the heatmap to cluster with, enter the property name in **Weighted Property** field. This should correspond to metadata that you uploaded or created with your locations. Otherwise, your heatmap will cluster strictly by proximity. You can use ACF fields as well -- just make sure you give the full ACF field name. **Intensity** works with the Weighted Property to increase the overall intensity of your heatmap. Play with this to get a broader range of colors. For the **color range**, you can enter as many colors as you like, from low to high intensity. You may enter hex values, RGB, or RGBA. Be aware that every color should be on a separate line! You can change the **Point Radius** to change the overlaps of the points when the heatmap is generated. A larger number will generally create more overlaps, causing a more intense but less geospecific heatmap. Finally, modify the **opacity** to change the overall transparency of the heatmap layer on your map. # Elevation Profile Show the elevation of a line over its distance. Elevation maps can be great for showing more information about trips, runs, or other information concerning paths where elevation change is a factor. With Mapster WP Maps, you can create elevation profiles for single-line maps or multiple-line maps, depending on what you need. [See an example here](https://wpmaps.mapster.me/examples/mapster-wp-map/elevation-chart/).
The elevation chart will show the corresponding dot on the map as you mouse over the chart, so you can see where the elevation changes with ease. ### Single Line Maps To create an elevation profile for a single line, first, create that line as a geographic feature. Style it however you like. Then, create a new Map and add that single line as the only Line feature in the map (if you add other lines, this will likely cause issues). Once you've added that, go to Specialty Maps > Elevation Line Chart and click Enable. Then choose the Single Line option, and decide if you want the elevation profile to load immediately on the map load, or whether it should only be accessible by the user clicking the small "mountain" icon control that will appear on the map. You can also select the profile line **color**, as well as the **units** (feet or meters).
### Multiple Line Maps Multiple line maps work in a similar way, only you can add multiple lines to your map and they will each cause the elevation chart to open and be generated on click. Disable the **Single Line** option. ### Additional Features Some additional features we are considering include: * The ability to upload GPX elevation data to allow higher accuracy * Showing multiple elevation profiles at once Please get in touch if these features are valuable to you and we can work on them with more urgency. # User Submission To see details on user submission, see the [relevant doc page here](/pro-sections/user-submission). # Listing Page Map Make a page with locations or areas listed and interactable between the map and your posts. With Mapster Pro, you can create a page that will list the posts that you've attached to a map beside them, and allow users to interact with the post listings and have things change on the map. This is easiest to see in an example like the one below. This type of map can be a little tricky to set up, but these instructions should help you to get going. [See an example of the Listing Page Map here](https://wpmaps.mapster.me/examples/mapster-wp-map/listing-map/). ### Make Your Posts, Then Geographies, & Associate Them This type of map was originally built for polygons, but it should work equally well with other types of geographies. The idea is that you create a geography in Mapster, and then "associate" that geography with another post in your Wordpress installation. It doesn't matter what post type your other post is, you can associate it in the sidebar area of any geography that you create.

Here, you can select the post to associate with your geography.

This associated post will be used to create the "Listing" side of the Listing Map. It will use the Title and Featured Image of this post in order to create the listing itself, and when the user clicks on the listing, they will be directed to the post's URL on the frontend. ### Create the Listing Map For the listing map, not every geography that you add will be shown in the Listing area. Only those geographies that are "associated" with other posts in your installation will be shown. So, feel free to add any geographies you want as if you were creating a normal map! This can be handy to add labels on top of polygons, for instance, if you want to only associate posts with polygons but still show neat labels on top of them. Make sure to go to the "Specialty Maps" section and select "Listing Page". You can choose a few options: * Lazy load (still in development) * Center on hover -- when a user hovers over one of the listings, the map will automatically center on the associated geography * Listing style -- choose between an image grid (great if you have featured images) or just a simple list * Sticky map -- if you have a long set of listings, the map will move smoothly beside the listings as the user scrolls down the page ### Adding the Shortcodes The best way to add the Listing Map and the Listings into your installation is to use the provided shortcodes in different container \
. You can find the Map shortcode on the "Maps" page in Wordpress, and the Listing shortcode in the "Specialty Maps" > Listing Page area of the specific map you created.
Put these shortcodes into the areas you want them to appear on your page -- usually best as two columns -- and you should see your listing map appear! # Preloader Select from a few different presets to show when your map is loading. The preloader graphic appears before your map is fully loaded. ### Loading Graphic By default all of the loaders visible at [Sam Herbert's SVG Loaders](https://samherbert.net/svg-loaders/) are enabled. Select from among them here. You can also upload your own by selecting **Custom** and uploading an image. ### Background Color Choose the background color and transparency, which will show as an overlay on top of your map container as it's loading. ### Loader Color If you've selected one of the preset loaders, you can change its color here. # Developer # Javascript Add a custom function. Here, you can add a Javascript function that should be run after the map has done initializing. This is a simple way to hook into any given map and manipulate displays or controls as you need. {% hint style="info" %} If you need more advanced hooks with Javascript, check out the Developer section on [hooks](/developer/hooks). {% endhint %} Enter the name of a function here. For example, let's call our function "myCustomScript". Create a global function with that script name. Your script will automatically receive a "map" and a "features" variable. For Maplibre and Mapbox, this will be a map object matching those libraries; for Google Maps, it'll be a map object matching the Google Maps API. As follows: ``` window.myCustomScript = function(map, features) { console.log(map); console.log(features); } ``` {% embed url="" %} # Embedding Maps Allow other websites to embed your map {% hint style="warning" %} Available in Pro only. {% endhint %} Allowing external users or apps to embed your maps expands the breadth of your creativity hugely. We're also working on API options so you can call your map data from a mobile app! Get in touch if you need this ASAP. **When you've installed Pro, the menu items under "Embed & API" will be visible when editing a Map**. To embed a map, simply go to the Embed & API section when on a given Map edit screen, turn on Allow Embed, and copy the embed code that appears underneath. You can give this to other users or place it on other sites as needed. ### Setting Parameters You can manually set the center and zoom of an embed code according to the URL if you like! Set it using query strings on the URL that's given to you, for example like: ```