Carto documentation

Introduction

Carto is a plugin for WordPress that allows you to create beautiful maps.

With Carto, you can create maps using the WordPress Block Editor, or add them as widgets in your website.

Wait: is this yet another maps plugin that does anything but giving me headaches whenever I try to create one?

The reason for the existence of Carto is the fact that most maps plugins out there are really hard to use, even for simple things. What we wanted to create is something that’s as powerful as it is simple to use.

By default, the plugin works using Google Maps, which is simply put the best map engine out there.

Google Maps has always required an API key to work, and if you ever worked with Google Maps, you’ll probably already know. If you don’t know what an API key is, it’s a code that Google Maps itself generates in order for maps to be embedded in your page.

Our plan for Carto, though, is to make available, within the plugin, other engines as well, ones that are not necessarily dependent on an API key for them to work.

Your first map

First off, if you’re using the default map engine, Google Maps, you’ll notice that you’re going to need a valid API key for the map to work. In order to set the API key for Google Maps, head over to Settings > Carto in the WordPress dashboard, and follow the relative instructions.

To add a map to your page, select the Map block from the Block Editor blocks list, or add a Carto Map widget to a specific widget area, and click on the “Create your map” button.

Clicking on this button will open up a modal window that will display the base status of your map. Please note that you are able to drag the map around to move within its boundaries, but before we dig deep into how creating a map works, let’s talk about the basic controls that are available.

Controls

• Main toolbar, located in the bottom right corner of the modal window. This toolbar features button that allow you to respectively add markers to the map, set the map center location, and access map-specific settings.
• Zoom controls, top left corner. These controls will allow you to zoom in and out in the map. You can also do the same operation by using the wheel on your mouse, or double clicking the map itself.
• Search control, top right corner. Clicking on the search button will expand a search field that will allow you to look up a specific address. More on this in can be found in a specific page of this documentation.

You can discard all changes you may have made to the map by clicking the “x” button in the top right of the modal (you can also use the esc key to do that), or you can confirm your edit by hitting the “Save” button, at the bottom.

After changes are confirmed, a preview of the map will be shown in your page editing screen within the Block Editor. To re-edit a previously created map, just click on the “Edit map” button that’s placed on top of the map preview.

Adding markers

To begin adding markers to your map, click on the Pin icon button in the Main toolbar.

After clicking on the button, you’ll have officially entered the Marker editing mode, and moving your mouse over the map will display a cross cursor, instead of the regular pointer.

This means that if you click on the map, a marker will be instantly added at the specific location you’ve clicked. Easy, right? If you just wanted to add a marker, that’s it: hit the “Save” button on the bottom, and you’re good to go.

However, there’s more to markers than this simple operation, so let’s dig a little deeper into what can be done with the pin you’ve just placed on the map.

Edit a marker

You can edit a marker by simply clicking on its icon, and a panel containing various controls will slide in from the left.

For each marker you add to a map, you are able to modify the following parameters:

• Title and description: on the frontend, filling in these fields will trigger the pin to display its own tooltip. Filling in only the title, or description, the tooltip will be shown when passing over the pin with the mouse pointer; filling in both details, will create a rich popup that’s shown when clicking on the pin.
• The Color setting, will allow you to change the color of the marker. The default marker being used is a SVG element, which means that you can freely choose whatever color you like.
• You can also manually specify the latitude and longitude of the marker. This is particularly useful if you’re given those parameters, and want to make sure to place your pin right.

Center and zoom

To make sure that the center of your map is a specific point of your choice, you’ll have to enter Centering mode. To do that, you’ll need to click the “Center map” button in the Main toolbar.

After entering in Centering mode, a new cursor is displayed on top of the map indicating what the current center is. Drag around the map below the cursor to update its location.

After you’ve found where you want your center to be, you can hit the “Confirm center” button at the bottom to save the center location, or simply discard any changes made to the center of the map by clicking “Cancel”.

Centering around pins

If you have a few pins on the map, it could be a good idea to automatically center the map around those pins, ideally finding a location that’s equidistant from each one of them.

In order to do so, while still in Centering mode, click on the “Zoom map to include all markers” control on the left, just below Zoom controls. Carto will automatically center the map around the pins you’ve added, adjusting the zoom level accordingly.

Address search

Carto uses remote databases to look up for specific locations (a combination of latitude and longitude numbers) from a textual address.

You can use the search control in the top right corner of the map editing modal to enter Searching mode.

Type the desired address you want to look up, and wait for the results to be fetched from the remote database.

Once you select one of the available results, its location will be displayed on the map. You’ll then be able to either automatically add a marker at that specific location, center the whole map around it, or do nothing, and maybe make a different search.

Settings

By clicking on the Settings icon in the Main toolbar, you’ll be able to edit specific settings regarding your map.

Depending on the map engine you’re using, the default being Google Maps, you may see a select control that allows you to choose a specific variant for the map.

Also, these are the parameters you can modify:

• Dimensions, the width and height of the map being displayed in page, for both regular view, and mobile view. The default dimensional values are purely suggestive of the ones you’ll be able to put in their respective fields. Keep in mind that numeric values (eg. 200), will automatically be translated to pixels.
• Display the zoom control; in either desktop and mobile contexts, this option determines whether the zoom control in the upper left corner should be visible or not.
• Choose if the map should or shouldn’t be draggable in either desktop and mobile contexts.
• Choose whether to display attribution information for your map.