Joomla! is the second most popular content management system in the world.  It powers sites such as the Eiffel Tower, the Guggenheim Museum, the United Nations Regional Information Centre and millions more.  So of course, Mautic integrates with Joomla!

Installing the Plugin

Its a simple process:

1. Download the plugin. (Joomla! 2.5x & 3.x)
2. Install it as you would any other extension (extensions -> manage -> install)
3. Configure the plugin with your Mautic URL.

Once the plugin is installed and configured, you can embed forms anywhere on your site.  You’ll also begin to see contact information populating your leads.

Watch the video.

If you’d like to suggest a topic, please head over to the #support channel and message @imrodmartin.

This second tutorial in creating your Mautic plugin we will start looking at the specifics of some of the files we’re going to write and how we take advantage of both the Mautic API and third party API calls.

Basic Files

There are several basic files we need to write to have our plugin registered within Mautic. We created the files in our last tutorial and this graphic shows them to you again.

The files we are going to focus on today include the config.php file, the MauticDeskBundle.php, and FormSubscriber.php. These are the quickest of the files and so we can cover them quickly. The other files you see in this screenshot are more specific to this particular integration and they will be covered in the next tutorial. For now let’s look at these first three files in more detail and line by line.

config.php

This first file is the config file which Mautic will use when loading the plugin into the system. In this file we are going to name our plugin, provide a description, version and author. Then we need to define the services we want our plugin to use. Here’s the file:

Services: The services are broken into two types, events and forms. Events are those items which you want to trigger as a result of some action within Mautic. Forms are the functions and calls to run when a form is loaded within Mautic.

e.g. Real-life, the form services will allow your plugin to collect more information from forms within Mautic from the business user (not the site visitor).

The Desk plugin that we are writing will need both an event service and a form service. We’ll dig into each of these services later but notice that the class defined for each of these services is the path to the associated file.

MauticDeskBundle.php

This file is the root file that can be used when extending the Plugin base class. In this plugin we do not need to extend anything so the file below is merely a holding file that routes everything to the Plugin Base parent class.

FormSubscriber.php

This file is associated with the event service we defined earlier in our config.php file. This FormSubscriber is the event that gets triggered based on some action within Mautic. Let’s look at the file and then break it down.

Namespacing and used classes are the first thing you’ll find in the file. Here we define what we’ll be using or referencing later in the file.

This class, FormSubscriber, extends a CommonSubscriber class available for all plugins.

The public function onFormBuild accepts a parameter of the FormBuilderEvent (as you can see type-hinted). Here we define the action for this particular service event. We will create the group, description, label, formType, formTheme, and callback function that we want triggered by this submit action. Lastly we add the submitAction to the event.

In this array of actions we have a few special key-value pairs to mention. First, the formType defines the configuration or parameters your plugin will have as part of the plugin configuration fields. (Don’t worry we’ll return to this later when we look at the form service and the plugin configuration).

The callback defines the location and the function you want to be called when the event is triggered.

Don’t let the formType confuse you, at this point in the process, it’s best to consider this merely a way for your admin configuration settings to be added to your plugin when it’s triggered.

Next Step

The next piece in the plugin tutorial will be to focus on the admin configuration for your plugin (see, it’s coming together) and then explore how the triggered response is pushed to the third party. This plugin may be a short series but will add great functionality. I expect after this tutorial series you will have no problem taking this example and building your own plugins easily to push Mautic data to other systems, the Mautic API is a great way to integrate open source marketing automation with everything else.

I’ll be covering how to create a Mautic plugin from start to finish in a series of posts that I hope will bring clarity and understanding to the entire process and answer any questions that arise during the process. If you get stuck I encourage you to jump into the forum to ask your questions and help others too!

Before we begin let’s look quickly at what a plugin is and why we care about creating them. With this idea of plugins Mautic functions very similar to something like WordPress. Plugins allow you to do a number of things from integrating other software systems and software tools to modifying the functionality of Mautic. Plugins let you extend Mautic however you need. This is one of the greatest benefits of an open source marketing platform like Mautic. You have full access to view the source code, examine existing plugins and improve the core by suggesting additional triggers or listener events.

Want a concrete example? A Mautic plugin might let you push data from a lead to an external CRM system. The plugin will listen for a specific action and when that action occurs will trigger an event that pushes data to some other system. Here’s a second example: A Mautic plugin might modify all your landing page URL’s and other external URL’s to use a link-shortening system (like Bitly) before they are rendered and displayed to the end user.

Ok, so that’s an idea of what a plugin might do and a couple of examples of how they might be used. I think that’s enough background. Let’s start planning what our sample plugin will do that we’re going to create together.

Step 1: Plan Your Plugin

Purpose of the Plugin

I want to create a plugin that pushes some information from Mautic to an external service. I have decided for the purpose of this tutorial series that I want to create a plugin that will let me create a form within Mautic and push the results of that form to Desk.com, a ticketing system.

At a high-level review, I am looking to create a plugin that will let me use Mautic to push support tickets into my support system but use Mautic for form collection and submission. By doing this I will be able to do a few different things. First, this will let me demonstrate how to create a plugin that needs additional configuration fields defined. Second, this plugin will add a new form action to standalone forms that will allow me to push my form submissions to some other system via an API. Third, this plugin will give me the opportunity to write a couple different listeners. And lastly, I can show some advanced techniques for field mapping.

Outline Basic Plugin Structure

Now that we have identified the purpose of our plugin this will help me to outline the basic plugin structure I want to use. Here is my basic plugin structure:

Don’t panic we’re going to look in-depth at each folder and file here through the course of this tutorial but for now we’ll just glance briefly at just a few highlights that are important to note.

Form Folder: Because I am creating a plugin that will provide additional features (fields) on a form within Mautic I will need to create a form folder and a FormFieldsType.php file which will define each of those fields. (The FormFields part of the name must match the class name but can be anything you want, and the Type part of the file name is necessary so Mautic will find and autoload this file).

FormSubscriber.php: Again, this file is named related to the class name it contains so that it will be automatically loaded by the system. I have called this one FormSubscriber to help me remember that this is a subscribed event for forms.

As with most parts of the system you will want to ensure that your naming is consistent throughout your plugin. Specifically the classname and namespace of your files as they relate to your config.php file. Don’t worry too much about this for right now as we’ll get into this in more detail in the next post.

Prepare 3rd Party API

I’m going to list this as part of the initial setup because it’s important to have this ready early on in your plugin development process. You will need to find and prepare your 3rd party API. This might involve creating an account, retrieving an API ID and API Key or similar. Basically you want to make sure when you’re ready to make an API call (later in this series) you will have everything ready to go and already setup.

For this tutorial I discovered that Desk.com uses Basic Authentication for handling interaction with their API and I simply needed to know my email address and password associated with my Desk.com account.

Mautic Developer Reference

In addition to the 3rd party API service and knowing what functionality is available from them you will also need to know the various endpoints, listeners, and more available within Mautic. You’ll want to keep a browser tab open with the Mautic Developer Docs loaded up. You can browse that information here: https://developer.mautic.org

Next Step

The next step after defining our purpose and looking at the basic plugin structure will be to begin writing all the necessary files to their respective folders and begin the process. We will get into this in the next article in this tutorial series.