Creating Merge tags

This guide is based on the assumption that you’re setting your plugin up using our Kozo plugin template creator.

The first step in setting up new merge tags is registering the merge tag in the constructor of the main plugin file. To do this we need to use add_action to hook into ninja_forms_loaded and register our call back.

Before we go any further you’ll need to create a new folder and two files. First, in the includes folder, create a file called MergeTags.php (you can leave this file empty for now). Next, in the includes folder create a Config folder (make sure to capitalize the “C” in Config, this is so the Ninja Forms file autoloader will know how to access the folder). Lastly, inside the Config folder, create a file called MergeTags.php (this file can be left empty for now as well).

Once we’ve got our Merge Tag file created and registered, let’s take a look at how we need to setup our class. The first thing we need to do is extend the NF_Abstracts_MergeTags class, then we need to add a protected property called $id. Once we have that, let’s look at our constructor.

The next thing we want to do in the constructor is call the parent constructor, then we want to assign a title, this will be what shows up in the merge tag selector menu. The last thing we need to do is connect up our config file.

Now that we have our includes/MergeTags.php setup, and it’s pulling in our config file, open includes/Config/MergeTags.php, Here we will setup the following data for each merge tag.

  • id – this is the programmatic name of the merge tag.
  • tag – What will be output on the backend when the merge tag is selected; this will need to be formatted like so: {merge_tag: example_tag}. All merge tags need to start and end with a curly brace. The first part will need to match the merge tag’s menus name, then after the colon, you’ll want to use something that describes what your merge tag does.
  • label – This is what will appear in the merge tag menu on in the builder in Ninja Forms.
  • callback – The name of the function that will fire when the merge tag is executed on the front end.

Here is an example of a config array that’s been set up:

Now all we have left to do is to set up the call back method for the merge tag in the includes/MergeTags.php file.

Now you will see your merge tag menu item in the selector–in the builder, and you’ll see the data that you set in the callback, now displayed on the front end.

Here is our new merge tag in the builder. 

And here is the output of the merge tag on the front end.

 

Lastly, I created a repo for the project I created while building this walk through. you can find it at the link below.

https://git.saturdaydrive.io/ninja-forms/dev-docs-merge-tag-example