MapSVG 3.x tutorial

2. Tooltips and popovers

Let's create a map of USA which would show us a dealer in each state in a popover info box on mouse click.

To do that we'll use new MapSVG 3.x feature: built-in Database.

Create a new USA map, set some colors and switch to Database tab.

You'll see a message that your database has no struture yet. Let's create it! Click on Edit fields button

This is a Form Builder which you can use to create a form which would allow you then to quickly fill your Database with data. There are several field types available. For a dealer we need the next field types:

  • Image: for dealer's photo
  • Text: for e-mail
  • Text: for name
  • Text: for address
  • Region: to connect the dealer with a region (US state) on the map

Add all required fields and change their Labels in the settings on the right side to:

  • Photo
  • E-mail
  • Address
  • Name
  • Region

Click on Save fields and switch back to the Database by clicking on List button on the top toolbar.

Now we're ready to start filling the database. Click on Add button on the top toolbar to reveal the form you've just created with the form builder.

Let's add a photo first. Click on "Browse..." button.

MapSVG uses default WordPress image uploader. You can drag & drop new photos into uploader or click "Select files" to choose from your drive.

MapSVG allows you to choose multiple photos at once from the uploader. But in this tutorial whe need only one photo for each dealer. So click on a photo and then click Choose images button on the bottom.

Fill in all other fields and click OK to add the record into database. Don't forget to choose a Region (US state) for each dealer. Let's add dealers to the next 3 states: CA, TX, FL.

After you've finished adding 3 dealers, click Close button to close the form builder.

To make it easier for user to find a dealer, let's disable states without dealers. Switch to Settings tab and set Disable all regions to On (please note that regions are not being disabled in the preview because you still need to be able to click on them). Now switch to Colors tab and change Disabled color to grey. All map becomes grey because all regions are disabled.

Switch to Regions tab and find Texas state and click on Enable/Disable button on the right to enable Texas back. Do the same for Florida and California.

Now we're ready to define tooltip and popover templates. Switch to Templates tab to do that.

MapSVG 3.x introduced new template engine which is working on Handlerbars. Handlebars has very easy syntax. It is just HTML markup with attributes of your Regions/Database objects surrounded by curly brackets: {{my_field}}.

So how do templates work?

Region templates

If you use a template for regions then Region object is being passed into the template and you can use all its properties there:

{{id}}
{{title}}

And what if you have defined some custom fields for regions? You can access them through data property:

{{data.my_field}}
{{data.other_field}}

How to access Database objects connected with a Region.

{{objects.0.my_field}}
{{objects.1.my_other_field}}

Go through all objects connected to a Region and show their properties:

{{#each objects}}
  {{my_field}}, {{my_other_field}}
{{/#each}}

Marker templates

Parent Database object is being passed into the template and you can use its properties there:

{{my_field_1}}
{{my_field_2}}

So let's create Tooltip Template first. We want to show state name followed by a message "click to see a dealer". State name is being stored in Region's title attribute. So the template would be:

<b>{{title}}:</b> click to see a dealer

For the Region Popover template let's add the next:

{{#each objects}}
  <img src="{{photo.0.thumbnail}}" /><br />
  {{name}}<br />
  {{email}}<br />
  {{address}}<br /><br />
{{/each}}

Let's see what we do here.

1. {{#each objects}}: take all objects attached to a region and start iterating over them. {{#each}}..{{/each}} is called a loop cycle. Parameters of chosen object are passed into the cycle. So inside the cycle you can access all the fields you have created in the Form Builder.

In our tutorial we have just 1 object (dealer) attached to each state so there's actually no need for loop cycle and we could change the template to this:

 <img src="{{objects.0.photo.0.thumbnail}}" /><br />
{{objects.0.name}}<br />
{{objects.0.email}}<br />
{{objects.0.address}}<br /><br />

You may have already noticed that objects.0 syntax. It means "take the first object from the list". If we would need to take second object, we would need to write objects.1, third object - objects.2 etc.

2. {{photo.0.thumbnail}} - here we take the first photo from the list (MapSVG allows you to add multiple photos into the same field, not just one), and then we take a thumbnail version of the photo. There are also other sizes/versions available: full, medium, thumbnail, original.

Go to "Settings" tab and switch Tooltips to On.

Go to Actions tab and select Region click > Show popver for checkbox. Choose Region from the drop-down list as a passing object to Popover template.

Switch the map to Preview mode and click on the Texas state to see the popover!

The design of popover is very basic so you can use built-in MapSVG CSS editor to add some classes and styles.