Gutenberg Development with Examples: Google Maps (part 3)

Welcome to the third and last post on how to create a maps plugin for Gutenberg. Our last post was quite dense and we saw a lot of different things: the attributes our block has, how to insert a map using a React component, how to use WordPress components or even create our own components to define the user interface, etc. Today we’ll be discussing something simpler.

In this post we’ll see how to render the Google Maps map in the front-end. To do this, we will take a closer look at save.js and we will make a few changes to the plugin so that everything works as expected. I will also use this last post to comment on any point that may have been unclear until now.

How to Save Our Map Block to Display It in the Front-End

To display the map in the front-end we first have to define the HTML we want to be rendered in the front-end. In a Gutenberg block, this is achieved by defining the save method of the registerBlockType function. As I already mentioned in the previous post, this method is defined in the file save.js in packages/blocks/nelio-maps/.

Again, this is an extremely simple function to understand:

• From line 7 to 25 we extract all the attributes that are relevant to our block. That is, all the attributes that we defined in attributes.js and that tweak the appearance of our map.
• In line 41 we open the div that will serve as a container for the block.
• In line 47 we find a div that will wrap the map itself. Look at something very interesting: this div includes all the attributes object in its definition. This means that all the properties in attributes (for example, 'data-lat': lat of line 34) will be rendered as HTML attributes (for instance, assuming that the variable lat is 2.48171, lat will appear in the final HTML as data-lat="2.48171").
• On line 49, a small div is added containing the coordinates of the marker.
• On line 59, the contents of the RichText that we had defined in edit.js.

So, in essence, the method save generates an HTML that contains all the attributes that are relevant to render a map in the front-end. So, what could go wrong? Well, if you were to open the front-end now, all you’d see would be this:

An empty block that only has some RichText content. What happened?

How to Modify the Plugin to Render a Google Map Created with our Gutenberg Block

To display a Google Map in the front-end it is necessary that we load the Google Maps library and a script that uses it to build the map itself. This is extremely simple and if you have ever developed for WordPress, you should know how to do it.

The first thing we should do is create a script that can build a Google Map using the data we have put in the HTML. This script is in assets/src/js/public/public.js. Take a closer look to understand how it works:

• In line 9 we search all the nodes that contain a map (filtering by one of the classes that we have included in the save method) and, for each of them, we call the initGoogleMap method.
• This method relies on two functions to do its job. On the one hand, it extracts the coordinates of a possible marker with the function extractMarkerPositionIfAny of line 55 and, on the other, it extracts all the properties of the map (center coordinates, zoom level, list of visible buttons, etc) with the function extractMapOptions from line 26. Note that both functions are simply dedicated to reading the values of the attributes data-something we had put into the save method.
• Finally, we created a map (line 18) and added a marker (line 21) using the Map and Marker classes, respectively, provided by the Google Maps library.

Now that we have this script, we only need two additional tweaks in our project:

• On the one hand, we must modify the webpack configuration file webpack.config.js so that it transpiles the public.js script that we just created. It might sound difficult, but it’s actually pretty easy: just look at the changes I made to that file in this commit.
• On the other hand, we have to modify the plugin to enqueue this new script (and the Google Maps library!) in the front-end. Again, a very simple change that you can see in this commit.

Once all these changes have been made, this is the final result:

I know what you’re thinking: why, instead of doing all this by hand, didn’t we use the React component we had used in edit.js? Wouldn’t this save some time?

Indeed, using the React component we saw in the previous post would have saved us some trouble… but there’s a catch: it relies on React, which means we would have had to load React in the front-end to use too. And that seems like too much, don’t you think?

Nelio Unlocker

Switch to WordPress safely while keeping your design and content

Improve your SEO today and boost your site speed by converting your pages into HTML, CSS, and WordPress standards. With zero technical knowledge required, you’ll only pay for what you need.

Try It Now

Pending Details

Finally, let me briefly discuss one aspect that’s very important, or else your plugin won’t work: the Google Maps API Key.

The Google Maps API Key

In order to use Google Maps you need to have an API key. How to get it is something Antonio explained to us a few days ago. Now, how do we use it?

One option would be to hardcode our API key in the plugin. If you’re the only one who’ll be using the plugin, that would do the trick. But if you plan on distributing your plugin to real users, it’s a very bad idea, because not all Google services are free—some are paid, and the costs can be quite expensive if everybody uses your key.

What to do in these cases? The idea is very simple: just add a configuration option in the plugin for people to enter their own API key.

In our case, if you add a map without API key, you will see the following warning message:

urging you to add the API key.

Usually, you’d create a special page to manage your plugin’s settings. But for a plugin as easy and simple as the one we’re creating, I thought it be easier if we opted for a different solution.

In WordPress there is an options screen in /wp-admin/options.php that looks like this:

It is a kind of “nice interface” to edit (almost) all the options that have been registered in WordPress and are in the table wp_options. So, all our plugin has to do is make sure that this option always exists in the database (even when there’s no API key set yet) and we will have a “nice interface” for the user to paste their API key without our doing anything!

To achieve this, use the init hook (see line 73 of this commit) with a function (line 134) that always sets a value to your key option. If the option does not exist yet, this function will set its value to the default value (an empty string) and save the option. If it already existed, the new value will be the same we already had, and so the update function won’t do anything. A clever and efective hack!

In Summary

In this post we have overcome the last barrier in our project: how to save the map and how to display it in the front-end. Basically, all we needed was a div with all the relevant information about the map (its center, options for displaying the buttons, the marker, etc.) and a small script to rebuild it in the front-end.

I hope that this tutorial has pleased you and serves as an example to undertake your own projects. As you can see, if you start a new project with a good foundation like the one we have created in Nelio with the boilerplate for Gutenberg development, materializing your ideas into real projects will be way easier.

If you have any questions, let us know in the comments section below. Good luck!

Featured image by Artem Bali on Unsplash.