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?

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.

Hi there! We’re back with our tutorial to develop in Gutenberg. Last week we started a project that added a map block in WordPress. In that first post we defined what the requirements that our plugin has to meet were and we prepared the skeleton of what will end up being the final product, starting with the fantastic plugin boilerplate that we have created at Nelio.

Today comes the second part of the tutorial on how to create the map block. In this post we will see how to add a Google Maps map inside the WordPress editor and how to implement a user interface that allows us to manipulate its behavior.

A Quick Look at the Current Status of the Project…

In the current state of the project we have a simple Demoblock defined in packages/blocks/demo/. This small block is the one that comes as an example in Nelio’s plugin boilerplate and looks like this:

Obviously, this isn’t what we want. We’re not interested in a heart icon followed by some text, but in something like this:

That is, we want a Google Map block with an optional marker in it. How can we move from the original example block that our boilerplate had to this other, more powerful block? Well that’s what we’re going to answer today!

But before that, let me invest a couple of minutes explaining what we have right now and how we’re going to move forward. I think that, if you understand the current state of the project, you’ll have an easier time following what will come next.

Understanding the Demo block…

As I’ve already said, the demo block is defined in packages/blocks/demo/. In this folder you’ll find the styles of the block, its icon, and several files with the code that implements its operation. Let’s see the most important files.

On the one hand, there’s the main file: index.js. This file exports three variables: the name of the block (name), the definition of the block (settings), and the styles that the block supports (styles). These three variables are those used in packages/blocks/index.js to register the block in Gutenberg (with registerBlockType) and thus make it available to final users.

This main file, then, serves as an entry point to understand the block we are creating. In the object settings (settings), we see three important properties: attributes, edit, and save. Each of these properties has its own JavaScript file (for the sake of simplicity and ease of understanding), each named after their corresponding property. Let’s take a quick look at all of them:

• The attributes.js file defines all those properties of our block that are dynamic and, therefore, should be tweakable by our users. In the case of our Demo block, the only attribute that exists is the text the user has written, but the map block will have many more options: the coordinates of the center of the map, the default zoom level the map should use, what buttons (if any) should be visible to interact with the map, etc.
• The file edit.js is the one that defines how the block is displayed in the WordPress editor and what settings are offered to the user (both in the toolbar and in the sidebar of the block’s settings). In Demo, the edit simply includes the RichText component of WordPress to write the content. As we will see, the map block will be more complex and will also include additional settings.
• Finally, save.js defines the method that will convert the block we were editing in Gutenberg into the HTML that must be rendered in the front-end. Again, in Demo we see that this function simply saves the contents of a RichText using RichText.Content, but it could be anything else (as we will see next week in the third and last part of this tutorial).

Creation of the Map Block Based on the Demo Block Included in the Plugin Boilerplate

Once we understand exactly how the Demo block works, it’s time to ask ourselves: how do we create ours? Well, very easy: as Toni told us a few days ago, we simply have to duplicate the directory packages/blocks/demo/ into packages/blocks/nelio-maps/ and start to modify everything necessary. I know, it’s easier said than done.

Let’s start with something easy: attributes.js. This file contains all the properties that should be modifiable by our final users. In the previous post we specified what requirements our plugin should meet and, therefore, we outlined what things should be tweakable. Well, taking a look at the resulting attributes.js you’ll clearly see what can be tweaked from our map block: zoom level, map center, visibility of different buttons… Super simple stuff!

The next point to modify is all that concerns the edition of the block in Gutenberg. To do this, we must dive into edit.js. If you look closely, you will see that it is not much more complicated than what we had in our original Demo block.

The most important thing is in the block’s render method (line 33), where we retrieve the attributes we just defined from an object named this.props. We’ll use this properties to render the block and its setings, of course. This is what we have:

1. A toolbar ToolbarControls (line 66), which we defined in an external file named toolbar.js (don’t worry, we’ll see its content in a minute).
2. The block settings that appear in the editor’s sidebar (line 68), which we find in a component called Inspector that we defined in inspector.js.
3. The content of the block itself, which has two states:
   • If I do not have a Google Maps API key available, we show a user notice (line 122).
   • If we have this key, we show the map using MapBlock (line 83). The map might include a Marker (line 97), which is only visible when the option is activated, and might also be accompanied of a div (line 104) with additional information about it.

Google Maps as a React Component

If we want to put a Google map in our editor, we must use a component that allows us to use the Maps API of Google Maps. Considering that Gutenberg is built on top of React, the logical thing to do is to find out if there’s a React component of Google Maps. And, sure thing, there’s one!

As you can read in the project’s documentation, first we have to add the component into our project. Just install and add the dependency running the following command:

npm install react-google-maps --save-dev

which adds a new entry in our package.json and downloads the package into node_modules.

How to Create a WordPress Component that Encapsulates a React Component

If we continue looking at the documentation of this React project for Google Maps, we will see that they recommend us to wrap their GoogleMap component with our own component. Once it’s encapsulated, we will have to use our component in our plugin.

Well, let’s follow their lead and create a component called MapBlock in its own file map-block.js. And that’s it! We now have a map component ready that we can use in our Gutenberg block.

How to Add Block Settings in WordPress Editor’s Inspector

The next step is to configure how this map should look in the editor and add a few settings to tweak its appearance. To do this, we must add several settings sections in the Gutenberg sidebar. As I have already advanced, we achieve this with a component that we have called Inspector and that we have defined in the file inspector.js.

If you take a look at this file, you will see that it follows the same pattern as always: we are defining a Component with a render method. This method pulls the relevant attributes in this.props and returns the JSX with all the controls. In this particular case, it returns an instance of InspectorControls (this tells WordPress that this content goes to the sidebar) with several PanelBody sections. Let’s see each section in detail.

Basic Map Settings

The first PanelBody we found (line 47) has no title and, therefore, always appears as a section that can not be closed:

The section defines a pair of RangeControls, whose result you can see in the previous screenshot. These two controls allow us to modify the height of the map and its zoom level.

Another interesting and simple section is the one found on line 121. Here we add a few options to activate or deactivate the buttons that should be shown on the map when displayed in the front-end :

To do this, we simply have to use the default WordPress component CheckboxControl.

How to Add a Custom Style Section for Our Map Block

Another interesting section of our block is the style section (line 68). You can see the final result in the following screenshot:

It’s a special section because the component we use (MapStyles) is not something that exists in WordPress by default, but something we have created for this block in particular. As you can see in the previous link, it is a component that loads a set of predefined styles in a component of type ImagePicker (which, incidentally, does not exist by default in WordPress either—you can find it in packages/components/image-picker/).

When the user selects any of the styles included in ImagePicker, the MapStyles component invokes the onChange function it’s been given (see line 76 of inspector.js) passing two values: the name of the selected style and the associated JSON.

Finally, notice that one of the options that MapStyles includes is a Custom style:

When selected, the component renders an additional text box (line 45) so that the user can enter their own style in JSON format. In case you did not know, the maps of Google Maps can be customized a lot!

How to Add a Marker into Our Map

The next section we have is the one that controls our marker (line 81). This section allows us to show or hide the marker (line 86) and, when active, gives us some additional settings:

As you see, a search box appears to search for locations in Google Maps (which we have implemented, again, with a custom component called AddressSearch) and the ability to show or hide the text block in which to put additional information about the marker .

By the way, notice that the AddressSearch component is based on a component called StandaloneSearchBox, which is also part of the React project . What a pleasure it is to reuse the work of others!

How to Configure the Toolbar of a Block

The last thing we have to discuss is the toolbar. If you have understood how the sidebar works, the toolbar is a piece of cake.

The toolbar of our plugin is represented by the ToolbarControls component defined in toolbar.js. Here we simply add a component to define the alignment of the block (BlockAlignmentToolbar, on line 42), a pair of dropdowns to center the map (line 50) and to modify the location of the marker (line 79), and a couple of extra buttons to change the location of the text box in which we can put additional information about the marker (lines 107 and 120).

In Summary

Today we have seen how to create the entire editing interface of our map block. As you can see, it’s a process that might seem complicated at first glance, but becomes pretty natural quickly. In the end, the secret is to start from an example that is well organized (as our plugin boilerplate is) and build the interface step by step, reusing the components that WordPress offers or that already exist, or even creating your own.

See you next week with the last part of this tutorial, where we’ll see how to save our map and how to view it in the front-end.

Featured image by rawpixel on Unsplash.

A few days ago we published a new plugin in the WordPress.org plugins directory: Nelio Maps. As the name reveals, it’s a maps plugin that adds a new type of block in the WordPress editor. With it, we can easily add a Google map on our pages or posts. Here’s how it looks:

Nelio Maps is one of our first plugins entirely designed for Gutenberg. Despite being a relatively simple plugin, it is a very useful product. On the one hand, because any user who wants to add maps to their website can now do so by installing a simple and lightweight plugin. On the other hand, because any developer that wants to develop in Gutenberg now has a real example of how to create a plugin “from scratch”, simply by reading this post.

As I am aware that the development of a plugin like this is not the easiest thing in the world, I have organized this tutorial in three different parts. Today I will explain how to create the plugin “from scratch” so that we end up with the skeleton we’ll use to build the final product. In the second post I will explain how to get an interactive map in the WordPress block editor and we will see all the components that I have created to make the plugin. Finally, in the third and last post we’ll see how to save the map in the database and how we can show it in the frontend.

Defining our Project and the Plugin We Want

It may seem like a truism, but before embarking with any new project, the first thing we must do is define what we want to achieve with said project. Depending on the functionalities we want to include, we will have a different set of requirements. So let’s define what kind of map plugin we want to implement in this tutorial.

These are the requirements of the project:

1. One should be able to add a map (or more than one) to their pages or posts.
2. It should be possible to center the map anywhere by
   
   • either dragging the map with the mouse
   • or looking for the location in a search box.
3. The size of the map should be adjustable, both in width and height
4. The map should include different styles (black and white, custom color palettes, etc.)
5. The user should be able to add a marker in the map.
6. If there is a marker, the map must be accompanied by a text box with additional information about the marker.

Ambitious, right? Well, let’s get started!

How to Create a Gutenberg Plugin “From Scratch”

If you follow our blog, you’ve probably seen that a few days ago Antonio published a post explaining how to create plugins using a plugin boilerplate that we have created in Nelio. If you have not read his post yet, I recommend you read it first, because our plugin will be based on the plugin boilerplate wp-beb that Antonio explains there.

To start our project, the first thing we will do is mirror Nelio’s boilerplate plugin. First, create a new repository in your GitHub account. Then, follow the steps described in Github’s help pages to mirror our boilerplate:

git clone --bare https://github.com/avillegasn/wp-beb.git
cd wp-beb.git
git push --mirror https://github.com/your-username/your-repo.git

Once your project is ready, follow the instructions found in README.md to compile the project and thus be able to see it in your WordPress site.

How to Transform the Plugin Boilerplate into Your Plugin

As it appears in the plugin boilerplate documentation, the first thing we have to do is change the project’s name in the source code. That is, you have to change all occurrences of wp-beb (both uppercase and lowercase, with hyphens or underscores) by the name of our plugin (in my case, nelio-maps).

For this, we can use the following script:

Just keep in mind you’ll have to replace the string nelio maps int lines 5, 8, 9, and 10 to whatever your plugin’s name will be.

On the other hand, now is also a good time to change the plugin documentation. On the one hand you have to edit the files README.md and readme.txt to reflect the purpose of your new plugin (without forgetting to mention the fact that you are using our boilerplate as a base, of course). On the other, you should change the first comment in the main PHP file, as it’s the data WordPress uses to display the plugin in the Plugins screen.

You can see how I made all these changes in the first commit of the Nelio Maps project.

How to Clean the Plugin Boilerplate of Unnecessary Stuff

Nelio’s boilerplate plugin includes, by default, a couple of components: (a) a demo block and (b) a Gutenberg plugin. Since we are only interested in creating a block (the map), we are going to eliminate everything that is left over (the Gutenberg plugin).

This step is quite simple, since basically it is based on “deleting” unnecessary things from the plugin. Specifically, we should:

1. Get rid of all the content that appears in the assets folder (which is where the Gutenberg plugin was added, its style, and its icon).
2. Clean the file webpack.config.js, since there are a couple of rules that used the files in assets we just removed.
3. Clean the main file of the plugin, since it enqueues a stylesheet and a JavaScript file that no longer exist.

You can see all the changes in this commit. If you compile the code again, you will see that the Demo block still exists, but the Gutenberg plugin that appeared in the upper right corner of the screen doesn’t.

Summary

In today’s post we have seen how to create a plugin for Gutenberg. First, we have defined the type of project we want to create and we have identified its requirements. Next, we have seen the steps needed to adapt the boilerplate plugin from Nelio to a new project. That is, we have seen how to clone Nelio’s boilerplate project and clean it to meet our particular needs.

See you next week with the second part of this tutorial, where we will modify the Demo block so that it performs all the functions we have described at the beginning of this post.

Featured image by Brett Zeck on Unsplash.