Creating a Pods plugin is a great way to contribute to the Pods project as well as to add functionality to your Pods-powered site. On our plugins page there are many different types of plugins listed. There are three types of Pods Plugins that can be created:
- Plugins that extend Pods’ capabilities, such as Pods SEO and Pods Frontier Auto Template
- Plugins that make it easier to use Pods, such as CodePress Admin Columns and CSV Importer For Pods
- Plugins for implementing Pods functionality in your site– These types of plugins are specific to a site and are used instead of modifying a theme or using the Pods backend functionality alone.
Pods Extend is mainly aimed at creating the first type of plugin on that list, one that extends Pods’ functionality. Still, some aspects of it as well as parts of this tutorial may be useful for creating any type of Pods plugin that you may need for your own Pods-powered site.
When Not To Use Pods Extend And An Alternative
If you are not comfortable with object-oriented php or do not need as complete of a plugin architecture that this starter plugin provides, then Pods Extend may not be the best choice. In many cases you just need a plugin to house custom code for your site that will not be lost when switching themes, which would be the case if you added it to your theme’s functions.php. I have also created a simple Pods plugin starter. The main file simply includes a plugin header and one function to include another file. The file is included conditionally if the constant ‘PODS_VERSION’ is defined. That will evaluate to true if Pods is active and to false if Pods is not. You can place all custom code in the file that it includes. This will ensure that if Pods is deactivated your custom plugin will gracefully stop working, instead of returning fatal errors because of its use of functions and classes from Pods that no longer exist.
Before you begin, you will need your own copy of Pods Extend. I recommend forking the repository on GitHub. That way your plugin is already under version control and ready to be shared with the world when it is done. You can also download the starter plugin as a zip file.
In the plugin’s readme file there are instructions for changing the name of the files, classes, and plugin name. Be sure to follow those steps in order. You will also want to add your own url to the plugin’s header in the plugin’s main file. Be sure to put your name in the copyright line.
Choosing Your Hooks
If you look in the starter plugin’s
__construct() function, you will see that I have provided you with several example hooks. These cover various places to hook into Pods. As of the first version, the examples mainly cover back-end functionality. Example hooks are given for adding tabs to the Pods editor, adding options to a tab in the Pods editor, and adding a submenu page to the Pods admin menu. For most front-end implementation you can use a hook from WordPress core. If you use the included example hooks as starting points for creating your admin interface, be sure to uncomment the ones you need and delete those you do not need. I will cover each one in detail shortly. There is also, in the classes folder, an example class for creating your own field type. Don’t forget to include the file and initialize the class if you plan to use it. Creating custom field types will be the subject of a future tutorial. In the mean time, you can reference how the built-in field types are created as examples of how to create your own.
Removing Code & Resources Not Needed For Your Plugin
Using The Provided Hooks
Adding Items To The Pods Menu Page
One other hook that you should take a look at is the ‘pods_admin_menu’ hook. This allows you to add a submenu page to the Pods admin menu for your plugin’s admin page. This creates a logical grouping of settings pages, with all Pods related settings in one menu. The callback for that hook requires that you add your menu page to the
$admin_menus array. Simply give your menu a name as the new key and then set three parameters. The ‘function’ parameter allows you to set another method in the class for the content of the options page. In that method, you can create an options page just like you would an options page for any other WordPress plugin. For an example of a callback for this hook, see the one in pods-visualize.
Retrieving Pods Settings
Now that you have added these settings you will need a way to retrive them. For this we turn to the Pods API. For each Pod’s settings we can create an instance of the Pods API class. Creating the instance is simple:
$pods = pods_api( 'POD_NAME' ); All of the Pod’s settings will now be available in the array
$pods->pod_data[ 'options' ]. Pods contains a great function,
pods_v(), that among its many uses can be used for safely returning data from this array. Using
pods_v() prevents you from having to worry about any data validation issues. The simplest usage of
pods_v() in this case would be to provide it with the value you are searching for. For example, to get the value of an option called ‘foo’ in a Pods options, you would do this:
$pods = pods_api( 'POD_NAME' ); $foo = pods_v( 'foo', $pods->pod_data[ 'options' ] ); This handy function also allows you to set a default value to return if no value is set. This is very useful, as you can set your default to null or false, and later, you can check that the returned value isn’t null or false before using it. One thing to keep in mind when setting a default value, is that you generally want to set the $strict parameter to true, so that empty values in the setting cause the default value to be returned. For example:
$pods = pods_api( 'POD_NAME' ); $foo = pods_v( 'foo', $pods->pod_data[ 'options' ], false, true ); Now you can safely test if
$foo is false before using it. This strategy eliminates the need to check if a get or post variable is set before setting it in a variable and also ensures that it is safe to use.
What Can You Do?
In this tutorial, I have shown you how to add settings to the Pods editor and how to retrieve them. In the next article in this series I will show you what I did with this basic starting point. Whatever cool thing you create with it, we want to know. You can submit your plugin to be included in our plugins listings. Also, if you have something you want to add to the starter plugin to help others get started with their own projects, please submit a pull request. Here are some ideas for possible plugins to get you started:
- A search widget
- Advanced content type search
- A field type that stored amounts of time
- An incremental number field
- A converter from advanced content types to custom post types