Plugins are so easy to find and install. From right within the Plugins menu in the admin area, you can search for, browse, and install plugins that are listed—as seen in Figure 5.1—in the WordPress Plugin Directory.

Figure 5.1. The WordPress Plugin Directory

Beware, though, that not all WordPress plugins are listed within the WordPress Plugin Directory, but as an end user seeking plugins, Google is a great option for you. Many premium, commonly used plugins like Gravity Forms or Shopp need to be purchased separately and installed into your WordPress installation through the Upload option.

Aside from their easy installation, there is a bunch of other useful aspects about plugins; for instance:

While the upsides are fairly obvious, there’s a darker side to plugins that’s often overlooked by end users, but all too apparent to the seasoned developer who’s had to deal with the aftermath. While core WordPress is developed, maintained, and vetted by a team of trusted developers with core commit privileges, the plugin space is, in many ways, the equivalent of the Wild West.

On the most fundamental level, plugins typically comprise nothing more than a few PHP functions and possibly some supporting JavaScript or CSS. As we’ll demonstrate in just a bit, writing a plugin and registering it with your WordPress installation is a simple process, but the quality of the code therein is only as solid and thought-out as the developer chooses to (or is able to) make it. Reality dictates that there are plugin developers all along the talent spectrum, ranging from beginners to experts, and, naturally, the products each developer produces directly corresponds to their level of proficiency. Furthermore, plugins are typically developed by either one developer or a small team of two to three working on the project. Things can get missed, and everybody has bad days.

In short, there are some poorly coded plugins out there.

While no method is 100% guaranteed, you can largely avoid poorly coded plugins by doing your homework on them before you install them. Start by looking at the overall star ranking of a plugin—these rankings are subjective, but a large enough sample user base will give you some reasonable expectations. You can also look at the discussion about the plugin right from the plugin’s comments section: see if there have been complaints about the plugin (and if you are so inclined, try to make a judgment as to how relevant those complaints are). Another tried-and-tested way to check out plugins before installing is to simply google them and see what’s been said about them. And, of course, even a highly rated plugin can be problematic if it hasn’t been in production for some time, and was last compatible with an older WordPress version than you happen to be running.

Just what are some of the issues that come up with plugins? There is a litany, but here are a few common problems:

Another issue with many plugins—especially those in the WordPress Plugin Directory—is that since most of them are created by non-compensated developers in their spare time, you may not receive prompt technical support when the need arises; this fact has almost single-handedly driven the popularity of the premium WordPress plugin market, where tech support is more widespread.

With all of that said, plugins are essential to bending WordPress to your will; it’s just necessary to keep a few guidelines in mind when using them. As an end user, follow these two tips and you’ll be fine:

Worth mentioning as well are must-use plugins, which comprise an underutilized but extremely useful technique for working with plugins. Must-use plugins are handy for developers who want to add plugins to a WordPress installation in a way that makes them more difficult for end users to deactivate. There’s nothing particularly special about must-use plugins themselves—any plugin can be a must-use plugin. What’s unique is how and where the plugins are installed. Instead of being downloaded from the WordPress Plugin Directory (or uploaded from your computer system) into the wp-content/plugins directory, they must be manually installed via FTP or your web host’s control panel into the wp-content/mu-plugins directory. This directory does not exist by default—you’ll need to create it—but when WordPress sees that it’s there, it will automatically activate and load any plugin it finds therein.

Must-use plugins have several special properties in the way that they’re handled by WordPress:

Another special type of plugin is a drop-in plugin. Drop-in plugins replace entire portions of WordPress core functionality. They are specifically named files that you can create and customize, and must be located within the wp-content/ directory. A complete listing of drop-in plugins can be found in Table 5.1, along with the context (single WordPress installation or WordPress Multisite installation) in which each is appropriate.

Whether you’re a developer or an end user, ask yourself whether it’s necessary to develop (or contract out the development of) a plugin before you begin the work. There are literally dozens of ways to do many common programming tasks within WordPress, and with the prolific use of the platform, it’s rare that you’d be creating a plugin that nobody else has attempted to do before you. Whether searching in the WordPress Plugin Directory or Google, you are apt to find several solutions that meet your needs. In the event that you’re unable to find a suitable plugin solution, sometimes the creative use of several plugins can accomplish your goal equally as well.

While many of us in the development community cut our teeth on writing every single line of code ourselves, you’ll often find that others who’ve tackled the same problems before us have created scripts with more fleshed out and better interfaces than we’d manage—at least, not without a significant investment of time and effort on our own. Use the open-source community; it’s there to help you. If after an exhaustive search you still find that no existing plugin meets your needs, or you have an extremely specific piece of functionality that’s unique to your application, by all means knock yourself out!

None of us are perfect, and experienced plugin developers will testify that debugging your plugin as you develop it is just a fact of life. While there are several techniques you can use to debug your code, the most fundamental is to go into your wp-config.php file in your sandbox WordPress installation and ensure you’ve enabled WP_DEBUG, so that it appears in your code as follows:

define('WP_DEBUG', true);

This will automatically make WordPress spit out any PHP warnings or notices that you’ll need to be aware of in order to correct, displaying them in real time as they happen. Furthermore, if you’re going to be modifying any of WordPress’s built-in JavaScript, make sure you enable SCRIPT_DEBUG as well, so that it appears in wp-config.php as follows:

define('SCRIPT_DEBUG', true);

In the same way as WP_DEBUG, SCRIPT_DEBUG will display JavaScript issues in real time as they occur.

Now that we’ve addressed the basics of what plugins are, how they’re installed, what to be careful of when you use them, and when to actually create one yourself, let’s get our hands dirty and pick them apart. Upwards and onwards!

WordPress provides us with a standardized place to keep all the plugins within a particular WordPress installation: the wp-content/plugins directory. Because all plugins are stored in the same location, your plugin must have a unique name, lest it cause an error as WordPress attempts to initialize it upon running. This unique name should be built right into the main PHP file for the plugin that will live in the wp-content/plugins directory, or in the name of the directory that will house the primary plugin PHP file. While technically all a plugin needs to function is just one properly formatted PHP file, it’s generally considered best practice to give each plugin its own directory, storing all files associated with the plugin within subdirectories therein. At the very top of our primary PHP file for our plugin, we’ll add a standard identifying WordPress plugin header. We introduced the concept of the plugin header briefly back in the section called “Creating Your First Custom Post Types ” in Chapter 4, but it’s worth going into more detail here:

<?php
/*
Plugin Name: The Name of Your Plugin Here
Plugin URI: Link to the Home page for the Plugin
Description: Brief descriptive text for the Plugin 
Version: What Version is the Plugin
Author: Author Name
Author URI: Author Home page
*/

The only required line in this header is the Plugin Name, but the rest of the information is extremely important, and WordPress will use the information within this header when initializing your plugin for use. Aside from verifying that it is a valid WordPress plugin file, WordPress gathers the information about the plugin in this header for your users to view in the Manage Plugins screen, as shown in Figure 5.2.

Figure 5.2. The Manage Plugins screen

Making sure that you include correct, up-to-date information about who the plugin is written by and where users can go for updates ensures its usefulness over time. Additionally, you should make sure to include licensing information about the plugin. Most plugins are GPL-compatible, and indeed must be so if they are to be included within the WordPress Plugin Directory (more on that in the section called “The WordPress Plugin Directory ”). Licensing information should directly follow your header information. Standard GPL licensing (with dummy text inserted for copyright year, plugin author name, and plugin author email) looks like this:

<?php
/*  Copyright YEAR  PLUGIN_AUTHOR_NAME(email : PLUGIN AUTHOR EMAIL)

    This program is free software; you can redistribute it and/or 
    modify it under the terms of the GNU General Public License as 
    published by the Free Software Foundation; either version 2 
    of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public 
    License along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  
    02110-1301  USA
*/

While it is customary to insert the plugin license directly underneath the plugin header, it’s also a nice idea to include it in a text file called license.txt within the plugin directory. An additional (and completely optional) step is to include a readme.txt file with your plugin, to provide any basic information or frequently asked questions to your plugin users that you might deem useful, but that’s entirely up to you.

That’s pretty much all we need to do in order to set up a plugin in the correct format so that WordPress can recognize it. Now’s when the fun begins, and we can actually start doing something genuinely useful.

We know that WordPress is a collection of PHP scripts that executes functions in a specific order, creating an end result that essentially comprises our website. One way to visualize the way core WordPress works is to think of it as a conveyor belt that moves through a specific process to get from point A to point B, producing a website as its end product. There’s no black magic here, but rather an assembly line of PHP functions that moves information in different directions, depending on a set of predefined rules.

When we write plugins, what we are really doing is introducing new PHP functions that add to the predetermined rules WordPress has already given us. To make that happen, WordPress has been good enough to create a special set of PHP functions that give us the ability to connect with that conveyor belt in the specific place it is appropriate to do so. These functions are called hooks, and they are the essential tools we need to be able to take our great new ideas and latch them into WordPress in a way that makes them useful to our users. Two hooks exist: Action hooks and filter hooks.

Action hooks are used when specific events take place within WordPress’s execution process. For instance, if you’d like to add some inline CSS code into the header of a page template, you could use the wp_head() action hook to do so, executing your function to create the appropriate lines of code when the wp_head() function is run in the standard assembly line of WordPress core functions. A properly formatted action hook call follows this format:

<?php add_action( hook, function, priority, accepted_arguments ); ?>

Where the parameters are equivalent to:

Let’s consider our simple CSS insertion example above, and see what that code might look like:

<?php

function inline_css() { ?>
<style type="text/css"  >
  .mockingbird {padding-top:15px;}
  .mockingbird .famous {display:block;padding:1em;}
  .mockingbird .famous p.label_title {font-size:12px;font-weight:bold;
     display:block;margin-bottom:5px;}
  .mockingbird .famous label.no_bold {font-weight:normal;}
</style>

<?php }

add_action( 'wp_head', 'inline_css' );
?>

Easy stuff, right? We’ve just created a short function called inline_css() containing some CSS code that defines styles for a class called mockingbird, as well as a subclass that defines what a famous mockingbird might look like. Then, using our add_action() function, we employ the wp_head() action hook to add the code in this function to the header of our WordPress page; this is when events occur that are associated with the wp_head action hook.

There are many action hooks available to latch into our WordPress assembly line process where we want to, but here are some that are more commonly used:

Where action hooks are used to execute functions at a certain time during the WordPress assembly line process, filter hooks, are used when you want to modify information before saving it to a database or outputting it to a browser; they’re typically used when modifying text in some way, shape, or form. The classic example of a filter would be in censoring out profane language that your users might try to add to pages or posts on your site. In this instance, you might apply a PHP function to a specific filtering hook such as the_content, so that you can remove words such as putz, dumdum head, or dimwit with a standard phrase like [mean name]. Let’s take a peek at what an example of the PHP function and the associated filter might look like in this instance:

<?php
function play_nice($content) {
  $mean_words = array("putz","dumdum head","dimwit");
  $content=str_ireplace($mean_words,'[mean name]',$content);
  return $content;
}

add_filter ('the_content', 'play_nice'),
?>

Here, we’ve written a little function that identifies and replaces words that we want to omit. Then, we’ve added our filter, instructing WordPress to run everything that goes through the_content (our filter hook) through our function, thus ensuring nobody can call anybody else a dimwit.

As much as we all like to be trusting, the truth is that every room has a shadow or two, and sometimes bad things lurk in the shadows. And if we have a user who tries to call another user a dumdum head on our public website for all to see, maybe they’ll want to do worse! There’s power in paranoia, kids, and for this reason you always need to be certain to validate and sanitize your data.

Much like brushing your teeth and (we trust) showering with soap every morning, data validation and sanitization should be treated as a habit every time you either output to a browser or save to your database. Essentially, what you want to do here is scrub every piece of data you can that is coming from a location external to your own code, as it may have illegal characters or genuine malicious intent.

WordPress gives us a standardized set of escaping functions we can use to scrub our data and ensure it’s safe for our use. Consider Figure 5.3, which describes the WordPress escaping API.

Figure 5.3. WordPress escaping API

In this diagram, we see that there are three components to the function set, as described following:

For example, in order to remove any HTML tags from a text string, you would use this format:

<?php esc_html( $text ); ?>

Alternatively, if you were looking to escape any illegal characters from within an HTML attribute, you might code this:

<input type=”text” name=”name” value=”<?php echo esc_attr($text); ?>”>
               

For more information on data validation, take a look at the WordPress Codex.

Okay, we’ll avoid acting like a parent here and beating this into the ground, but seriously: don’t be an ingrate, remember to validate!

Let’s take a look at that first chunk of code:

<?php
/*
Plugin Name: Antelope General Social Media Links
Plugin URI: http://mickolinik.com/plugins/antelope-social-media-links
Description: Easily add links to your social media profiles
Version: 1.0
Author: Mick Olinik
Author URI: http://www.mickolinik.com
*/

/*  Copyright 2011  Mick Olinik  (email : [email protected])

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

Nothing too exciting’s going on here, but there’s stuff we need to take care of anyway. We have our standard WordPress header detailing exactly what the name of the plugin is, what it’s for, the version, who wrote it, and so on. We’re also telling people what the terms of use are—will your end users need to promise you their firstborn child to use this thing, or are the terms of use easy like the summer breeze? Let the good people know whether it’s GPL or commercial.

Next comes the code for our localization settings:

//load textdomain for localization settings
load_plugin_textdomain('agsml', false, basename( dirname( __FILE__ ) ) .↵
  '/languages' );

Before we really do anything in our plugin, we should check to see whether we have a language translation file that matches the language that has been set in wp-config.php. WordPress is brought to you in English by default, and most plugins are as well, but if we have localized our plugin (and we have), we enable our users the ability to extend the plugin themselves by translating it into a language of their choice. Consider the function load_plugin_textdomain(), which takes the three parameters described below:

load_plugin_textdomain( $domain, $abs_rel_path, $plugin_rel_path ) 

A more detailed explanation of localization can be found in Chapter 11, but for our purposes here, we’re looking in the /languages directory of our plugin to see if there’s a language translation file that matches the language we’re running WordPress in (if we’re not running it in English already). If we find a match, load_plugin_textdomain() will grab all the translated text strings and swap them out for their counterparts; these counterparts are defined within the plugin’s code as it executes and outputs to the screen.

Now matters become interesting. Let’s look at this next code block and break it down into pieces:

add_action('admin_menu', 'agsml_create_menu'),

function agsml_create_menu() {

  //create new top-level menu
  add_options_page('Antelope General Social Media Links',↵
    'AG Social Media Links', 'manage_options', __FILE__, 'agsml_settings_page'),
  add_filter( "plugin_action_links", "agsml_settings_link", 10, 2 );
  //call register settings function
  add_action( 'admin_init', 'agsml_register_settings' );
}


//add settings link to plugins list
function agsml_settings_link($links, $file) {
  static $this_plugin;
  if (!$this_plugin) $this_plugin = plugin_basename(__FILE__);
  if ($file == $this_plugin){
    $settings_link = '<a href="options-general.php?page=AGSocialMedia/↵
      antelope-social-media-links.php">'.__("Settings", "agsml_social_media").↵
      '</a>';
    array_unshift($links, $settings_link);
  }
  return $links;
}

function agsml_register_settings() {
  //register our settings
  register_setting( 'antelope_social_group', 'agsml_facebook' );
  register_setting( 'antelope_social_group', 'agsml_twitter' );
  register_setting( 'antelope_social_group', 'agsml_youtube' );
  register_setting( 'antelope_social_group', 'agsml_linkedin' );
}

In full, what we’re doing here is laying the groundwork for working with our plugin inside the WordPress admin area. Let’s start by looking at the top code block:

                  add_action('admin_menu', 'agsml_create_menu'),

function agsml_create_menu() {

  //create new top-level menu
  add_options_page('Antelope General Social Media Links',↵
    'AG Social Media Links', 'manage_options', __FILE__, 'agsml_settings_page'),
  add_filter( "plugin_action_links", "agsml_settings_link", 10, 2 );
  //call register settings function
  add_action( 'admin_init', 'agsml_register_settings' );
}

We start by first using an action hook, requesting that the Admin menu run the agsml_create_menu() function. And what does that function do? It utilizes the add_options_page() function to add the Antelope General Social Media Links plugin and label it AG Social Media Links. The other parameter of interest in the add_options_page() function is agsml_settings_page, which defines the callback function to be used that displays the contents of the page within the link. We’ll cover this function further on in our explanation.

The next line is an example of a filter hook, whereby we are calling plugin_action_links() and running it through the agsml_settings_link() function that we’ll explore in a moment. This filter serves to insert the function that creates the link to our plugin settings page directly within the Manage Plugins listing page, which is utilized by many of the nicer plugins.

Finally, we use another action hook to initialize the agsml_register_settings() function, which we’ll use to save our data directly to the wp_options table in our WordPress database. More on this shortly.

Let’s look at our next function:

//add settings link to plugins list
function agsml_settings_link($links, $file) {
  static $this_plugin;
  if (!$this_plugin) $this_plugin = plugin_basename(__FILE__);
  if ($file == $this_plugin){
    $settings_link = '<a href="options-general.php?page=AGSocialMedia/↵
      antelope-social-media-links.php">'.__("Settings",↵
      "simple-social-sharing").'</a>';
    array_unshift($links, $settings_link);
  }
  return $links;
}

This little code block just defines the PHP code we’ll use to actually create the link and label that we’ll insert into our plugin settings page. This will be placed directly within the Manage Plugins listing page, as described previously in the filter hook in the agsml_create_menu() function. This is really just PHP code, and there’s not much here that involves WordPress.

Next up comes our agsml_register_settings() function:

function agsml_register_settings() {
  //register our settings
  register_setting( 'antelope_social_group', 'agsml_facebook' );
  register_setting( 'antelope_social_group', 'agsml_twitter' );
  register_setting( 'antelope_social_group', 'agsml_youtube' );
  register_setting( 'antelope_social_group', 'agsml_linkedin' );
}

Here we go, back to WordPress functions. This is a useful spot to discuss database considerations when dealing with WordPress plugins.

When you are working with WordPress plugins, you’ll almost always need to save your data to the database at some point. There are generally two ways to do this:

Space doesn’t allow us to cover the creation of new tables for plugin data storage in the context of this chapter; however, bear in mind that when you go in this direction, there’ll be several considerations you’ll need to keep in mind including initially setting the table up, ensuring that there are no naming conflicts, and developing a mechanism to safely remove the table upon uninstall. With that said, unless your plugin is extremely specialized and complex, and requires you to save an extensive quantity of data, you’ll typically use the first method and store your data in the wp_options table.

The register_setting() function is useful for defining the data you want to save for your plugin, and takes the following parameters:

register_setting( $option_group, $option_name, $sanitize_callback )

In our case, our intent is quite simple. We only really have four values we want to save with this plugin, so we register each of these with its own unique name and tag it back to a unique group name: antelope_social_group. Once we’ve done this, we have our framework in place and we’re off to the races … what’s next?

Check out the CSS file in the AGSocialMedia folder:

/* Antelope General Social Media Links */
.agsml_widget {
  overflow: hidden;
  padding: 0;
}

.agsml_widget ul {
  list-style-type:none;
  margin:0;
  padding:5px 0;
}

.agsml_widget ul li a{
  padding: 5px 10px 5px 20px;
  line-height:18px;
  margin:0;
}

.agsml_widget ul li {
  padding-bottom:5px;
}

.agsml_widget ul li.twitter a {
  background:url(images/mini_twitter.png) no-repeat left; 
  margin:0;
}

.agsml_widget ul li.facebook a {
  background:url(images/mini_facebook.png) no-repeat left; 
  margin:0;
}

.agsml_widget ul li.linkedin a {
  background:url(images/mini_linkedin.png) no-repeat left; 
  margin:0;
}

.agsml_widget ul li.youtube a {
  background:url(images/mini_youtube.png) no-repeat left; 
  margin:0;
}

Again, not a whole lot to see here aside from demonstrating the addition of internal CSS styles within a plugin. We’re just creating a function, inlaying some CSS for the purpose of styling our Admin page to make it look pretty, and then adding the function in to run with the admin_head action hook. At this point in the game, we’ve seen this stuff before; let’s keep moving.

Following this comes a chunk of form-building HTML:

//html for settings form
function agsml_settings_page() { ?>

<div class="wrap agsml_social_list">
  <h2>Antelope General Social Media Links</h2>

  <form method="post" action="options.php">
    <?php settings_fields( 'antelope_social_group' ); ?>


      <div class="setting">

        <p class="label_title"><?php _e('Facebook Profile URL:', 'agsml') ?></p>
        <p><label class="no_bold" for="agsml_facebook"><span class="slim">
           <?php _e('Facebook URL', 'agsml') ?></span>
        <input name="agsml_facebook" type="text" id="agsml_facebook" 
            value="<?php form_option('agsml_facebook'), ?>" /></label></p>
        <p class="desc"><?php _e('Enter URL to your Facebook profile.') ?></p>

        <p class="label_title"><?php _e('Twitter Profile URL:', 'agsml') ?></p>
        <p><label class="no_bold" for="agsml_twitter"><span class="slim">
           <?php _e('Twitter URL', 'agsml') ?></span>
        <input name="agsml_twitter" type="text" id="agsml_twitter" 
           value="<?php form_option('agsml_twitter'), ?>" /></label></p>
        <p class="desc"><?php _e('Enter the URL to your Twitter profile.') ?></p>     
        
        <p class="label_title"><?php _e('YouTube Profile URL:', 'agsml') ?></p>
        <p><label class="no_bold" for="agsml_youtube"><span class="slim">
           <?php _e('YouTube URL', 'agsml') ?></span>
        <input name="agsml_youtube" type="text" id="agsml_youtube" 
            value="<?php form_option('agsml_youtube'), ?>" /></label></p>
        <p class="desc"><?php _e('Enter the URL to your YouTube profile.') ?></p>

        <p class="label_title"><?php _e('LinkedIn Profile URL:', 'agsml') ?></p>
        <p><label class="no_bold" for="agsml_linkedin"><span class="slim">
           <?php _e('LinkedIn URL', 'agsml') ?></span>
        <input name="agsml_linkedin" type="text" id="agsml_linkedin"  
           value="<?php form_option('agsml_linkedin'), ?>" /></label></p>
        <p class="desc"><?php _e('Enter the URL to your LinkedIn profile.',↵
                          'agsml') ?>
        </p>             

        <p class="setting">
        <input type="submit" class="button-primary" 
           value="<?php _e('Save Social Media Links', 'agsml') ?>" />
        </p>

      </div>

  </form>

</div>

<?php }

There are three main points in this code block worth noting. First, we see our definition of our agsml_settings_page() function, which we last referenced as the callback function in our add_options_page() function further back in the code. In other words, it’s this function that defines the instructions for displaying all the code for our actual Settings page in the Admin menu.

Secondly, since this is the administrative settings page output, it follows that we have text strings here being displayed to our users. Because we are thoughtful developers and want to make sure that folks all over the world are able to use our plugin in their own native language, we need to prepare our text strings for localization. This means that instead of just typing in an output string like this:

<p class="label_title">LinkedIn Profile URL:</p> 

We’ve added our _e() wrapper tags around each of our strings to produce results that look more like this:

<p class="label_title"><?php _e('LinkedIn Profile URL:', 'agsml') ?></p>

You’ll notice here that we’ve defined both the string to be translated (in this instance, 'LinkedIn Profile URL:') as well as the unique domain namespace we’ve created for our localization at the top of our code (agsml). Again, for more on localization, have a look at Chapter 11.

Finally, notice that we’ve taken care to sanitize the data here before committing anything to our database. Here, we’ve used form_option() to output our social media values. form_option() runs these values through esc_attr() to sanitize them, ensuring that they are safe for our use.

This next piece of code is an example of the proper and safe way to insert an external CSS sheet into your plugin:

function agsml_enqueue_styles() {

  // url to stylesheet
  $agsml_css_url= WP_PLUGIN_URL . '/' . plugin_basename(dirname(__FILE__)) .↵
    '/agsml-widget.css';
       
  //register and enqueue stylesheet
  wp_register_style('agsml_styles', $agsml_css_url);
  wp_enqueue_style( 'agsml_styles'),
        
}

add_action( 'wp_print_styles', 'agsml_enqueue_styles' );

We create a function called agsml_enqueue_styles(), and then define the URL to the CSS for our widget to be displayed on the front end of our website, but the next two functions are really worth taking note of. Rather than just injecting the link to the CSS sheet directly into the <head> section of your WordPress site, enqueueing a WordPress CSS file allows you to specify dependencies that tell WordPress your CSS depends on another CSS file, and should be loaded afterwards. While the wp_register_style() function essentially serves as a helper function to prepare your data for wp_enqueue_style(), wp_enqueue_style() is where all the magic happens. Our example is a very simplified form of wp_enqueue_style(), and so in the situation of AGSocialMedia we’re really including it for proper form, and to prepare to extend the plugin later on if we so choose.

Before we further continue tearing apart our Antelope General Social Media Links plugin, let’s take a moment to talk about widgets and how they work.

Useful for dragging different pieces of functionality around to sidebars, footers, and other widgetized areas on a WordPress site, widgets extend the functionality of a plugin by allowing users to place it in an appropriate place on their websites. They’re not appropriate to add to all plugins, but in the case of our AGSocialMedia plugin, they are, as the entire purpose of the plugin is to display icons and links to our four most used social media sites: Facebook, Twitter, LinkedIn, and YouTube.

Thanks to the widget API that WordPress gives us, creating and using widgets isn’t as difficult as it could be. There are three basic steps to creating and using a widget in your plugin, broken down as follows:

To further understand how widgets work, let’s look briefly at the basic structure of the widget class in WordPress:

<?php
class Antelope_Widget extends WP_Widget {
  function Antelope_Widget() {
    // actual widget code that contains the function logic
  }

  function widget($args, $instance) {
    // display the widget on website 
  }

  function update($new_instance, $old_instance) {
    // save widget options
  }

  function form($instance) {
    // form to display widget settings in WordPress admin
  }

}
?>

As you can see, the widget class contains four basic components:

Check out our first piece of widget-related code:

/* Register the widget */
function agsml_register_widget() {
  register_widget( 'Antelope_Widget' );
}

The first piece here is super-easy, and it’s our first step in creating and using a widget for our Antelope General Social Media Links plugin. We’re just going to register our widget so that WordPress knows we have a new one coming, and it’s called Antelope_Widget. Easy peasy.

Now we jump into step two of creating our widget, which is really step one of its own four-step process: defining the widget class functionality:

/* Begin Widget Class */
class Antelope_Widget extends WP_Widget {

  //* Widget setup  */
  function Antelope_Widget() {
    $widget_ops = array('classname' => 'agsml_widget', 'description' =>↵
       __( 'Your Social Media Links', 'agsml') );

  // The actual widget code goes here
    parent::WP_Widget( false, $name = 'AG Social Media Links', $widget_ops );
  }

In the code, you can see that we begin by extending the WP_Widget object with the Antelope_Widget class, thus extending it and creating a namespace for ourselves to work with. After that, we create a basic localized array (note the double underscore wrapper that encompasses the string 'Your Social Media Links' and which denotes the unique domain namespace we’ve created earlier in 'agsml') and toss it all into a variable. Then we utilize the widget API to create a new object for our actual widget, which we’ll be able to find in the Appearance > Widgets menu area within WordPress. Notice that we have a label for our widget here ('AG Social Media Links'), and we’re also passing our array in as well, so we have our object’s data handy for use.

The second piece of the widget class involves actually outputting the instance of a given widget to the browser:

/* Display the widget  */
function widget( $args, $instance ) {

  //get widget arguments
  extract($args);
  //get widget title from instance variable
  $title = apply_filters('widget_title', $instance['title']);
 
  //insert before widget markup
  echo $before_widget;

  //if theres a title, echo it.
  if( $title ) 
  echo $before_title . $title . $after_title;
 
  //start list
  $social_list .= '<ul>';
  
  // define list
  if (get_option('agsml_facebook' )){ 
    $social_list .= '<li class="facebook"><a href="'.↵
      get_option('agsml_facebook').'">' . __('Friend us on Facebook', 'agsml') .↵
      '</a></li>';
  } 
  if (get_option('agsml_twitter' )){ 
    $social_list .= '<li class="twitter"><a href="'.↵
      get_option('agsml_twitter').'">' . __('Follow us on Twitter', 'agsml') .↵
      '</a></li>';
  }
  if (get_option('agsml_linkedin' )){ 
    $social_list .= '<li class="linkedin"><a href="'.↵
      get_option('agsml_linkedin').'">' . __('Link us on LinkedIn', 'agsml') .↵
      '</a></li>';
  }
  if (get_option('agsml_youtube' )){ 
    $social_list .= '<li class="youtube"><a href="'.↵
      get_option('agsml_youtube').'">' . __('Watch us on Youtube', 'agsml') .↵
      '</a></li>';
  }
  // end list
  $share_content .= '</ul>';

  //display assembled list
  echo $social_list;
 
  //insert before widget markup
  echo $after_widget;

}

Because we’ve passed the object’s data to the instance of the widget as just described, the first step is to extract the $args so that we can use them. The AGSocialMedia widget has the capacity to create a custom title on an instance-by-instance basis as we’ll see in a moment, so one of the first items here is the extraction and sanitization of the title string from our array, after which we drop it into the $title variable.

You may notice that there are several variables sprinkled throughout this code block that we aren’t defining: $before_title, $after_title, $before_widget, and $after_widget. These tags are provided to you by the widget API, and are available to theme designers to manipulate in different ways, so that they can add code to make their websites look pretty. Make sure the tags stay as positioned, so those designers avoid running into any unforeseen and unexpected surprises.

Aside from that, the rest of this code is fairly self-explanatory. Because we’re outputting to the browser here, we once again have strings that are being localized in the same format as before; it doesn’t bear any more explanation, but when you are writing your own plugins, you will want to remember this important detail. Spread the WordPress love by localizing—have you noticed this as a recurring theme yet? We should make bumper stickers: “Be Wise and Localize!”

The third piece of the widget class is the nearest we have to a standardized component, and it’s very simple to see what’s happening:

/* Update the widget settings, just the title in this case  */
function update( $new_instance, $old_instance ) {
  $instance = $old_instance;
  $instance['title'] = strip_tags($new_instance['title']);
  return $instance;
}

All we are doing here is sanitizing the only input we have for our widget—in this case the customized title—and saving it as a new instance, replacing the old instance if it existed.

The final component of the widget class provides the logic for the form, which is necessary to update the title of the instance of the widget:

//form to display in widget settings.  Allows user to set title of widget.
function form( $instance ) {
  $title = esc_attr($instance['title']);
?>
<p>
  <label for="<?php echo $this->get_field_id('title'), ?>"><?php _e('Title:'),
    ?></label> 
  <input class="widefat" id="<?php echo $this->get_field_id('title'), ?>"
    name="<?php echo $this->get_field_name('title'), ?>" type="text" 
    value="<?php echo $title; ?>" />
</p>
<?php 
}
}

Here we find a very simple form with just one label (that includes our now all-too-familiar localized string) and its corresponding input field, which autopopulates with the existing title, if one has been previously set.

The final touches on our Antelope General Social Media Links plugin are finally within our grasp:

/* Load the widget */
add_action( 'widgets_init', 'agsml_register_widget' );
?>

Now all we need to do is use widgets_init to load up our agsml_register_widget() function. After this function fires, we’re home, and while most antelopes run out of control, our antelope is running with all the controlled precision we could possibly hope for!

In many plugins, you’ll want to give your end users the ability to add information in a standardized way right on the page or post editing screen. One way to accomplish this is to utilize meta boxes, which we looked at back in the section called “Meta Boxes ” in Chapter 2. If you recall, meta boxes are customized dialog boxes you can insert on administrative editing screens, seen in Figure 5.4.

Figure 5.4. Custom meta boxes

Meta boxes are added using a standard function that takes seven parameters, as shown below:

add_meta_box($id, $title, $callback, $page, $context, $priority, $callback_args) 

Each of the parameters is defined as follows:

The add_meta_box() function is typically used in conjunction with the admin_init action hook, which you can use to create your custom meta box within page types associated with your plugin. While most of the parameters that add_meta_box() takes are self-explanatory, there’s a couple of really cool ones that make this a particularly flexible function. Notably, the $page parameter queues up the type of page that your meta box can be displayed on; because it ties into custom post types, it gives you an additional level of control when morphing WordPress into the specialized CMS you envision for your website, as described in Chapter 4. The $context parameter is equally useful, giving you control over exactly where that meta box will show up on the page type editing screen. This is sexy stuff that lets you carve out WordPress to make it look and function however you see fit.

Another extremely useful concept to dig into is shortcodes. Shortcodes are essentially sanitized placeholders for PHP functions that are either initialized by core WordPress, from within a plugin, or even from within the functions.php file of your theme. They can accept parameters that make them perform tasks, and are very useful when you want to insert fairly complicated code into a page or post without actually inserting that code. Instead, you can think of a shortcode as a placeholder that WordPress will identify when outputting your website, replacing it with the appropriate code associated with the shortcode. They are formatted with opening and closing brackets that look like this: [my_super_awesome_shortcode].

Shortcodes are easy to create, and for the most part you can embed any functionality you want into them. WordPress gives us the following standard function to use when we want to create one:

add_shortcode( 'shortcode-name', 'shortcode-function-name' )

Here, the parameters are straightforward, with the name of the shortcode (the text we insert in our brackets) being defined within the first string parameter, and the associated function that calls the PHP function we’ll be executing where the shortcode is inserted in our page. Let’s take a look at a very simple example of a shortcode in action:

<?php

function thank_you() {
  return 'You can feel good about Hood.';
}

add_shortcode( 'mrminer', 'thank_you' );
?>

Here, we have defined an extremely simple shortcode named mrminer, which makes reference to a function called thank_you(). While you can be extremely creative and intricate with the functionality you’d like to introduce in your shortcode, we’ve kept it very simple here to illustrate the process. In our example, we can add the shortcode [mrminer] to any post or page, and it’ll print out “You can feel good about Hood.” in that space.

All right, so let’s say you’ve created a plugin and you want to give back to the community by sharing your creation with the world. One of the easiest and most effective ways of doing that is to submit it to the WordPress Plugin Directory on WordPress.org. There are several really cool things that result from listing your plugin in the directory, most notably that it instantly becomes accessible to anybody who’s running a WordPress installation. With just a few clicks and the right search, your plugin can come up in the plugin search and be added to anyone’s WordPress site in just a few minutes. Additionally, when you update your plugin inside the directory, your users will be immediately notified and prompted to upgrade from right within their WordPress admin back end … and that just feels so cool the first time you ever see it happen with one of your plugins. Finally, WordPress.org also gives you access to statistics, so you’ll be able to see exactly how many people have downloaded your plugin and the ratings they’ve given it, as well as view and respond to comments.

You’ll need to adhere to several blanket terms and conditions if you want your plugin to be listed in the directory, namely:

If you choose to submit your plugin to the WordPress Plugin Directory, it’s an easy process, even though it’s not immediate. You’ll need to be a WordPress.org registered user, and then you submit your plugin at http://www.WordPress.org/extend/plugins/add/. Upon adding your plugin, it will need to be reviewed and approved by the staff managing WordPress; it’s a process that can take some time, as it is manual.

Upon having your plugin approved, you will be given access to the WordPress.org Subversion repository, where you’ll commit the uncompressed plugin to the SVN repository, along with a valid readme.txt file that describes the information needed for listing a plugin in the directory. A sample readme.txt file can be found at http://wordpress.org/extend/plugins/about/readme.txt, and a readme validator that will help you determine whether you’ve added the required elements for a listing is available at http://www.WordPress.org/extend/plugins/about/validator/.