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:
- One should be able to add a map (or more than one) to their pages or posts.
- 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.
- The size of the map should be adjustable, both in width and height
- The map should include different styles (black and white, custom color palettes, etc.)
- The user should be able to add a marker in the map.
- 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.gitOnce 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.
Nelio Popups
Fantastic plugin! It’s really easy to create popups as you’re already used to the editor, and all the options it has are really well crafted.
Juan Hernando
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:
- Get rid of all the content that appears in the
assetsfolder (which is where the Gutenberg plugin was added, its style, and its icon). - Clean the file
webpack.config.js, since there are a couple of rules that used the files inassetswe just removed. - 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.
Leave a Reply