Writing a WordPress plugin – it’s that easy

Recently I introduced my first WordPress Plugin and said that it would be easy to write one. Let’s take a quick look at how I actually created the plugin.

Some words for the very beginners

When starting to developing something you should have following things ready: A (non-public) WordPress installation for testing purpose, a great code editor (for example Eclipse for PHP or TextWrangler [Mac OS X]). Some knowledge of PHP since WordPress is written in it as well as it’s themes and plugins.

Let’s start

WordPress plugins are located inside the /wp-content/plugins/ folder. Here you can either create a new folder or file with a unique name. I recommend a folder even if you only have one file because this makes it easier to add new files when updating and you can keep a better overview.

If you’re done with that, let’s create our plugin file and give it a name – best would be to give it the same name as your plugin and please don’t call it index.php. Inside this file we will specify some meta information about the plugin, which will then be displayed in the admin plugins panel. We will also add something in our first line so people can’t directly open the file and cause errors:

defined('ABSPATH') or die('Hack your own stuff!');

/*
* Plugin Name: getOpenion
* Plugin URI: https://getopenion.com/wordpress
* Description: getOpenion is an extremely powerful tool to create online surveys. Add surveys from getOpenion to your posts with this plugin.
* Version: 1.0.3
* Author: Pius Ladenburger
* Author URI: https://pius-ladenburger.de
* Domain Path: /languages
* Text Domain: getopenion
* License: GPL2
* License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/

Now we can start writing our plugin.

Writing the plugin

Hooks

Because WordPress is a big and mighty content management system it works a lot with filter, hooks and actions. Let’s start with the two most important hooks: the activation and uninstall hook. You guest it – the one fires when the plugin is activated (not downloaded) and the other one when the plugin is uninstalled via the admin plugin panel (not deactivated). Using them is very straight forward simply register the hook by saying which function should be called in the event that the hook is called an tada:


register_activation_hook(__FILE__, 'getopenion_register');
function getopenion_register() {
// do something at installation
}
register_uninstall_hook(__FILE__, 'getopenion_remove');
function getopenion_remove() {
// do something at uninstallation
}

The first parameter (__FILE__) is needed because it specifies where the function (a.k.a. callback in the WordPress Codex) is placed – in this case in the same file as the hook is registered. There are of course some other hooks, for example if the plugin is deactivated.

Pages

Now you probably want to add a page in the Dashboard, either into the settings or as a own top-menu item. This is done with another set of functions which are build up like this add_%LOCATION%_page(). Let’s create a new page inside the settings menu, this is done via the function add_options_page(). We need to wrap this up inside another function though, the admin menu action:

add_action('admin_menu', 'getopenion_add_menus');
function getopenion_add_menus() {
add_options_page('getOpenion Settings', 'getOpenion', 'manage_options', 'getopenion', 'getopenion_settings_page');
}

admin_menu

Here’s what the parameters do: The first one (getOpenion Settings) is the page title (displayed at the top of the browsers window), the second one is the name displayed in the menu, the third one specifies who can see the page item (needs to be a capability), then comes the slug (how it is displayed in the url, e.g. https://pius-ladenburger.de/blog/wp-admin/admin.php?page=getopenion) and last is the callback function which handles the page to be displayed – we are going to look a this one now.

Here’s the full list to all functions for adding pages in the Dashboard.

So when the page is opened the function getopenion_settings_page will be called. Inside this function we will simply place the code which will displayed on the page:

getopenion_settings_page() {
echo '<h2>Settings</h2>';
echo '<p>Some text...</p>';
}

You can – and I guess it’s even better to do it this way – simply write the code for the page in an extra file and then simply include it inside the function include(__DIR__ . '/page_code_filename.php'); and don’t forget to prevent the file to be accessed directly with:
defined('ABSPATH') or die('Hack your own stuff!'); as the first line.

Storage

Since CMS’s are all about storing things here are two quick ways you can go about storing things. The third way is to create an own database table. I haven’t done that yet so I can’t tell you how to do it.

The two ways are:

  1. As a user meta: This means the information is stored linked to a user
  2. As an option: This is like a general information which is valid globally for the WordPress installation

For the user meta solution there are two important functions:

update_user_meta($userid, 'key_name', 'value'), get_user_meta($userid, 'key_name') and delete_user_meta($userid, 'key_name')

You can get the current user id with get_current_user_id().

The option is called like that because that’s how options in the settings are saved. Using options is almost like with user metadata.

You have update_option($key, $value) to create or change an option, get_option($key) to retreive the stored information and delete_option($key) to remove it.

Settings API

We have been looking at adding a page to the settings menu and storing information. Since WordPress 2.7 this can be combined semi-automatically. Please take a look at the Settings API over at WordPress for this.

Some things you should know

Here are some things you should know to make your life a lot easier.

Sessions

Interestingly WordPress doesn’t use the PHP session management with all the $_SESSION variables and session_start functions… This is why – if you want to use them you will have to add something like:

if (! session_id())
session_start();

at the front of your plugins code (please make sure you check if the user is still logged in and the same person to maintain security).

AJAX Requests

If you would like your user interface to work a bit more fluent you will need to use AJAX. Compared to normal web design you can’t just include your script in the document, you rather have to actions and filters again. Let’s see how to load a script in the admin area:

add_action('admin_enqueue_scripts', 'getopenion_load_ajax');
function getopenion_load_ajax($hook) {
if ($hook != 'post-new.php' && $hook != 'post.php')
return;
wp_enqueue_script('ajax-script', plugins_url('/js/surveys.js', __FILE__), array('jquery'));
wp_localize_script('ajax-script', 'localized', array('ajax_url' => admin_url('admin-ajax.php'),'error' => __('Error')));
}

As you can see I added the action admin enque scripts. In the function, I registered, I first check if we are on the page for adding a new post/page or editing one. Then I say load the file surveys.js with the wp_enqueue_script function, as well as that this script requires jquery. Last but not least I register localized variables for the script. These are javascript variables with the content generated in php. I can now use this javascript variables like this localized.error (because I stated this localized with the second parameter) for example.

Now we also have to handle the ajax request, which is normaly sent to domain.com/wp-admin/admin-ajax.php, as you might have noticed. But we have to register the ajax action like this:

add_action('wp_ajax_load_surveys', 'getopenion_surveys_ajax');
function getopenion_surveys_ajax() {
// do something
// maybe output a result
wp_die();
}

So the action is constructed like this: wp_ajax_[nopriv]_{action name}. You use the nopriv if this is an action for logged out users, else it only works when logged in. The action name is your unique action name, which you will need to send with your ajax request as action={action name}.

Tables

If you want to display the WordPress style admin tables it’s a topic all by itself. The WordPress Codex states following about the WP List Table Class (the one which generates these great ones):

This class’s access is marked as private. That means it is not intended for use by plugin and theme developers as it is subject to change without warning in any future WordPress release. If you would still like to make use of the class, you should make a copy to use and distribute with your own project, or else use it at your own risk.

This is because, as also described in the Codex, because it is subject to change in future versions of WordPress. But since almost all lists in the admin dashboard use this and therefore look similar there are ways to still implement it. I am not going to go through this but there lots of tutorials out there (e.g here [wpengineer, this is where I went] or here [paulund]).

TinyMCE

TinyMCE is the texteditor in WordPress with which you edit your posts and pages. Here’s quickly how you add a button:

Add another filter mce_buttons: add_filter('mce_buttons', 'getopenion_register_buttons');

In the function getopenion_register_buttons, I will add my buttons:

function getopenion_register_buttons($buttons) {
array_push($buttons, 'separator', 'getopenion_ins');
return $buttons;
}

and then I need a second filter to load the script which handles the button event (tinyMCE plugin):

add_filter('mce_external_plugins', 'getopenion_register_tinymce_js');
function getopenion_register_tinymce_js($plugin_array) {
$plugin_array['getopenion'] = plugins_url('/js/getopenion-tinymce.js', __FILE__);
return $plugin_array;
}

Inside this script (getopenion-tinymce.js), I will place the code for a tinyMCE button. See the full toturial on WPTuts.

WordPress has a great documentation. If you need a function you don’t know if it exists give it a web search. If you find a function but don’t know what it does or how to use it go to the WordPress Codex and look it up. To create my WordPress plugin I mainly used the WordPress Plugin Handbook.

Conclusion

As you can see creating a WordPress plugin is very easy thanks to the great resources by WordPress but also from other sources. Some things (stated in some things you should know) aren’t that straight forward. But if you know them – and now you do – you know how and where to find a solution. Download my plugin and look at the sourcecode to have a simple example of how to use javascript, tinyMCE buttons or WP List Tables.

This article is not meant to be another tutorial on how to create a WordPress plugin but rather give a brief overview at what I learnt while creating my one. I would recommend you to do a tutorial on how to create a plugin and check on this article if you get stuck or need some tips.
I also do not have anything to do with the websites I link to in this article. They are rather resources I have use myself and which have helped me.

Comments are closed.