Map Custom Tool

This example shows us how to create a custom tool to render a map using the Google Maps Static API.

Each custom tool is built in its JavaScript file, which is passed to the init code. For example, here is the custom.js file for the custom map tool, which contains the attributes to get it running:

unlayer.registerTool({
  name: 'map_tool',
  label: 'Map',
  icon: 'fa-map',
  supportedDisplayModes: ['web', 'email'],
  options: {
    location: {
      title: "Location",
      position: 1,
      options: {
        "latitude": {
          "label": "Latitude",
          "widget": "text",
          "defaultValue": "37.785343"

        },
        "longitude": {
          "label": "Longitude",
          "widget": "text",
          "defaultValue": "-122.3978088"

        }
      }
    },
    zoom: {
      title: "Zoom level",
      position: 2,
      options: {
        "zoom": {
          "label": "Zoom Level",
          "widget": "counter",
          "defaultValue": "18"

        }
      }
    },
    mapType: {
      title: "Map Type",
      position: 3,
      options: {
        "mapType": {
          "label": "Map Type",
          "widget": "dropdown",
          "defaultValue": "roadmap"
        }
      }
    },
  },
  values: {},
  renderer: {
    Viewer: unlayer.createViewer({

      render(values) {
        console.log(values.mapType)
        return `<img src="https://maps.googleapis.com/maps/api/staticmap?center=${values.latitude},${values.longitude}&zoom=${values.zoom}&maptype=${values.mapType}&markers=color:red%7C${values.latitude},${values.longitude}&size=500x500&key=<<your_API_key_here>>" style="max-width: 100%" />`
      }
    }),
    exporters: {
      web: function(values) {

        return `<img src="https://maps.googleapis.com/maps/api/staticmap?center=${values.latitude},${values.longitude}&zoom=${values.zoom}&maptype=${values.mapType}&markers=color:red%7C${values.latitude},${values.longitude}&size=500x500&key=<<your_API_key_here>>" style="max-width: 100%" />`
      },
      email: function(values) {

        return `<img src="https://maps.googleapis.com/maps/api/staticmap?center=${values.latitude},${values.longitude}&zoom=${values.zoom}&maptype=${values.mapType}&markers=color:red%7C${values.latitude},${values.longitude}&size=500x500&key=<<your_API_key_here>>" style="max-width: 100%" />`
      }
    },
    head: {
      css: function(values) {},
      js: function(values) {}
    }
  }
});

The name, label, icon, and supportedDisplayModes attributes for the custom tool have been specified in the code above. You can learn more about them from the documentation here.

Let's discuss the options parameter now, where we define the tool properties and property editors. We have three property groups for the Map Tool:

1. Location
2. Zoom level
3. Map Type

The property group location has further two properties:

1. Latitude
2. Longitude

We have specified label,widget, and defaultValue for each property. All widgets have been used from the Built-In Property Editors.

We need to make sure that the user can customize the tool according to the specified properties' values. That's where the renderer comes in. A renderer is where you define the content that your tool will create. For example, the Maps Static API lets you embed a Google Maps image on your web page without requiring JavaScript or any dynamic page loading. The Maps Static API service creates your map based on URL parameters sent through a standard HTTP request and returns the map as an image you can display on your web page. The URL is as follows:

`<img src="https://maps.googleapis.com/maps/api/staticmap?center=${values.latitude},${values.longitude}&zoom=${values.zoom}&maptype=${values.mapType}&markers=color:red%7C${values.latitude},${values.longitude}&size=500x500&key=<<your_API_key_here>>" style="max-width: 100%" />`

values contain all the property values set by the user, so we include those as parameters into the URL, and that lets us render the map accordingly.

Exporters define the tool's HTML template passed to your application when you call exportHtml. We'll use the same code for both the exporters as we want to export the same static map for email and web mode.

Let's have a look at how we include the custom JS file in the init code:

unlayer.init({
  id: 'editor',
  displayMode: 'email',
  projectId: << your_projectId_here >> ,
  customJS: [
    window.location.protocol +
    '//' +
    window.location.host +
    '/custom.js'
  ],
  tools: {
    'custom#map_tool': {
      properties: {
        mapType: {
          editor: {
            data: {
              options: [{
                  label: "roadmap",
                  value: "roadmap"
                },
                {
                  label: "satellite",
                  value: "satellite"
                },
                {
                  label: "hybrid",
                  value: "hybrid"
                },
                {
                  label: "terrain",
                  value: "terrain"
                }
              ]
            }
          }
        },
      }
    }
  }
});

We add custom.js file to the customJS field. We also pass values to the dropdown field in the mapType property group in the init code specified above.

Preview

Here's a live running preview of the Map tool. Drag and drop the custom tool with the map icon: