WordPress Plugin Construction for the Non-Programmer: Part IV

Welcome to the fourth post in my series on building a WordPress plugin from scratch. This tutorial series requires no programming experience, but I do suggest you start from the first post in this series if you’re a total newbie to WordPress development.

Just a couple things to keep in mind about this series:

Five Official “Cover my Butt” Statements

  • At the time of this writing, the most up to date WordPress version is 3.4.1. It might be different by the time you read this.
  • I’m assuming you already know how to install a basic WordPress site, if you’re unsure please see their www.wordpress.org.
  • Please do NOT attempt anything in these tutorials on one of your live WordPress sites. Rather, set up a subdomain and a brand new WordPress installation to use for plugin testing purposes only.
  • If you’re confused by any of the code or terminology above, please go back and read the first two posts in this series.

Recap of the Basic WordPress Plugin Structure

The following is the code the WordPress Plugin named “Basic” which we’ve been creating in these tutorials. If you’ve been following this series, you’ll notice a few new lines of code. We’ll be breaking the new code down in this tutorial:

{code type=php}

<?php

/*/

Plugin Name: Basic

Plugin URI: www.yourwebsiteurl.com

Description: Demonstrates how a WP plugin works and how to create a unique class for your WordPress plugin.

Version: 101

Author: Your Name

Author URI:  www.yourwebsiteurl.com

/*/

// check for existing class //

if(!class_exists(“YourBrandWPBasic”)) {

// create class //

class YourBrandWPBasic {

//plugin constructor//

function YourBrandWPConstructor(){

}//close constructor //

//create admin page//

function YourBrandWPAdminPage() {

//lock out unauthorized users//

if (!current_user_can(‘manage_options’)) {

wp_die( __( ‘ KEEP OUT! Authorized Personnel Only!’ ) );

}//end lock out//

//spit out html for admin area//

echo ‘<div>’;

echo ‘<h1>Welcome to Your Brand WP Basic</h1>’;

echo ‘<p>This will be the command center for the Basic Plugin customization features.</p>’;

echo ‘</div>’;

} //end of html for admin page//

//build plugin menu//

function my_plugin_menu() {

add_options_page(‘Your Brand WP Basic’, ‘Your Brand WP Basic’, ‘manage_options’, ‘your-brand-wp-basic-admin’, array(&$this, ‘YourBrandWPAdminPage’));

}//end plugin menu

} // close class //

} //close check or existing class //

//if the class exists, assign a handler to it//

if(class_exists(YourBrandWPBasic)){

$your_brand_wp_basic = new YourBrandWPBasic();

//tell your handler to build the plugin menu using WP action

add_action( ‘admin_menu’, array($your_brand_wp_basic, ‘my_plugin_menu’) );

}//close assignment of handler//

{/code}

If you’re overwhelmed, don’t worry. This isn’t so bad once you go through it line for line. What we’re doing here is adding an admin menu which will display in the WordPress Dashboard like this:

When you click the name of the “Your Brand WP Basic” plugin, you’ll see an admin page open up that looks like this:

Just a quick tip, since you should already be working with the plugin we’ve been building, you should now be able to edit the plugin code from within your WordPress dashboard. Just go to “Plugins,” and when the “Your Brand WP Basic” plugin comes up, select “Edit.” You’ll see a page that looks like this, where you can edit and save the plugin code:

Let’s start with the new methods (aka functions) which we’ve added to our “YourBrandWPBasic” toolbox (class).

Step #1: Add Some Admin Page Building Tools (Methods) into Your Handler’s Toolbox (Class)

In the code above, you’ll notice that our toolbox (aka class) now has a few new tools (methods) in it. There are two new methods in all, both of which follow the keyword “function” in the code below:

{code type=php}

<?php

//create admin page//

function YourBrandWPAdminPage() {

//lock out unauthorized users//

if (!current_user_can(‘manage_options’)) {

wp_die( __( ‘ KEEP OUT! Authorized Personnel Only!’ ) );

}//end lock out//

//spit out html for admin area//

echo ‘<div>’;

echo ‘<h1>Welcome to Your Brand WP Basic</h1>’;

echo ‘<p>This will be the command center for the Basic Plugin customization features.</p>’;

echo ‘</div>’;

} //end of html for admin page//

//build plugin menu//

function my_plugin_menu() {

add_options_page(‘Your Brand WP Basic’, ‘Your Brand WP Basic’, ‘manage_options’, ‘your-brand-wp-basic-admin’, array(&$this, ‘YourBrandWPAdminPage’));

}//end plugin menu

{/code}

First, let’s look at the “YourBrandWPAdminPage” method. This method has two parts. First, we use an if not statement (the ! character negates the “if”, thus the “if not”) to determine whether the current WordPress user (the person logged in) can manage options in WordPress.

The “current_user_can” is not a PHP function. It’s a native WordPress function which allows you to check what the current user can do. WordPress has created a whole bunch of things that you can check for, all of which are included in the list at this link:

List of WordPress Roles and Capabilities for “current_user_can” function.

You can swap anything you see in the list at this ^ link in place of the “manage_options” and the if statement would change accordingly. Notice that if the person can NOT manage options, the “wp_die” function executes. Don’t worry, no one will die if you use this, it’s simply telling the plugin to stop and to display the message which comes between the “(_(“ and the “));” characters.

So if you were to translate this segment of our first method into plain English:

{code type=php}

//lock out unauthorized users//

if (!current_user_can(‘manage_options’)) {

wp_die( __( ‘KEEP OUT! Authorized Personnel Only!’ ) );

}//end lock out//

{/code}

…it would read:

“Wordpress, if the user who is logged in is not able to manage options, don’t execute anymore code for this plugin. Instead, give them a message that reads like this:”

By the way, you might be wondering how you can test this method, since you obviously have permissions to manage options on your WordPress test site. Simple, just remove the “!” and the method will display the keep out message to the people who DO have permission to manage options.

Okay, so moving on to the next part of the method.

Here, we’re using the PHP echo function to spit out some html code (we talked about html code a bit in the 3rd article of this series). In the code below, we’re wrapping the entire html section in a “div” which has the class “wrap” assigned to it. I think of the “div” element as a “division” of a page, a piece if you will.

As for the “wrap” class, just go with it for now because html classes are s a topic for another post. Next, notice that we’ve used the “h1” to create the primary header for the admin page and the “p” to create a small message in paragraph format:

{code type=php}

//spit out html for admin area//

echo ‘<div>’;

echo ‘<h1>Welcome to Your Brand WP Basic</h1>’;

echo ‘<p>This will be the command center for the Basic Plugin customization features.</p>’;

echo ‘</div>’;

} //end of html for admin page//

{/code}

So this entire method builds an admin page that can only be accessed by people who have permissions to manage options in the WordPress site. Here’s what it should look like when you access the admin page:

TIP: For my overachievers, try changing the text within the “h1” tag or the “p” tags and see what kind of admin page you can create. Also, try out a few of the other options for the “current_user_can” function and test them with and without the “!” character to get a feel for how this WordPress function works within an “if” statement.

Step #2: Add Some Admin Page Menu Building Tools (Methods) into Your Handler’s Toolbox (Class)

Now that we have an admin page, let’s build a menu that the user can click to get there. Here’s the method named “my_plugin_menu” which we’ve added to our class to make that happen:

{code type=php}

//build plugin menu//

function my_plugin_menu() {

add_options_page(‘Your Brand WP Basic’, ‘Your Brand WP Basic’, ‘manage_options’, ‘your-brand-wp-basic-admin’, array(&$this, ‘YourBrandWPAdminPage’));

}//end plugin menu

{/code}

If you’ve been following this series, this code ^ should be self-explanatory with the exception of the “add_options_page” method. This is another method which is not native to PHP but to WordPress. It’s basically telling WordPress to add an option for your plugin under the “Settings” menu which the user can click to access your admin page.

Like this:

If you break the “add_options_page” function down, you’ll notice that it takes 5 arguments. In our code, these arguments are as follows:

1.      Your Brand WP Basic: the text that appears in the “Settings” menu.

2.      Your Brand WP Basic: Use the name of your plugin for now.

3.      manage_options: leave this as is for now, we’ll get into this argument in later tutorials.

4.      your-brand-wp-basic-admin: the url of your admin page (you’ll see this in the URL bar of your browser when you go to your admin page).

5.      array(&$this, ‘YourBrandWPAdminPage’): this 5th argument tells WordPress where to find the content for your admin page.

 Number five is a bit thick, but in the last tutorial, we explained the “array” as a string of data. So in the 5th argument, we’re telling WordPress to use “$this” which represents the current class (YourBrandWPBasic) and to select the “YourBrandWPAdminPage “  method from this class.

So if you were to translate this code into plain English:

{code type=php}

add_options_page(‘Your Brand WP Basic’, ‘Your Brand WP Basic’, ‘manage_options’, ‘your-brand-wp-basic-admin’, array(&$this, ‘YourBrandWPAdminPage’));

{/code}

…it would say:

“WordPress, I want to use this tool (add_options_page) to create a menu option which reads ‘Your Brand WP Basic” and when the person clicks that link it takes them to the page which I built in “THIS” class (the “YourBrandWPBasic” class) using the “YourBrandWPAdminPage” method.”

Now, remember that putting these tools in the toolbox doesn’t make them do anything. You have to assign them to your handler, so let’s knock that out…

Step #3: Assign Your Admin Page and Menu Building Tools (Methods) to Your Handler

Notice that in our source code, we have the following WordPress action added to the handler named “$your_brand_wp_basic”:

{code type=php}

add_action( ‘admin_menu’, array($your_brand_wp_basic, ‘my_plugin_menu’) );

{/code}

As you might recall from Part I, that function “add_action” is a native WordPress function which takes two arguments. The first (‘admin_menu’) is the “filter” which tells WordPress where to put the content. The second (array($your_brand_wp_basic, ‘my_plugin_menu’)) tells WordPress what to put there.

So if we were to translate this code into plain English:

{code type=php}

add_action( ‘admin_menu’, array($your_brand_wp_basic, ‘my_plugin_menu’) );

{/code}

…it would read

“WordPress! I want you to add some content to the admin menu. My handler “$your_brand_wp_basic” will be using the “my_plugin_menu” tool which I placed in his toolbox (class named “YourBrandWPBasic”) to assemble this content.”

As in the last tutorials, I suggest you experiment with some of the html to change the display on the admin page. In the next tutorial, we’ll get into some strategies for using PHP code within the admin page. We’ll be using some of the same techniques we’ve used already, so if you’re feeling overwhelmed yet, don’t worry…it DOES get easier!

Comments and questions are welcome.

-Till next time, Seth C