Easy WordPress Plugin Development (Part 5)

This is the fifth article in our plugin development tutorial series. In the last segment, we explained how to implement dashboard admin pages. You can access the linked table of contents for the entire series below.

Now that we have our plugin functional, let's discuss three additional development considerations.

Table of Contents for this Tutorial

Toggle Article Details

1. Introduction: Plug-in Development Overview
   Overview of the Steps Involved · Why You Should Use the WordPress Plug-in Directory · Official Plug-in Development Documentation · Official Plug-in Submission Documentation · Choose a Sandbox for Code Development
2. Plug-in Development Fundamentals
   How to Get Ideas for Plug-ins · Pre-Development Considerations ·
   Plug-in Folder Structure · Plug-in File Header · Plug-in File License Description
3. Our Plug-in's Primary File Source Code
   Activating Our Plug-in · The Shortcode Handler · The Shortcode Workhorse Function · Our Shortcode Support Functions · Setting Up the Dashboard Admin Options Page
4. Implementing Dashboard Admin Pages
   Our Dashboard Admin Page PHP · Our Dashboard Admin Page Content ·
   How to Style Dashboard Admin Pages · How to Use the screen_icon Function ·
   Additional Admin Page Functions · Admin Page Fade Out Alerts ·
   How to Add Your RSS Feed on Your Admin Page
5. Additional Plug-in Considerations  (you are here)
   How to Add Contextual Help to Your Plug-in · How to Offer a Customizable CSS File ·
   How to Load Any Required Javascript Files · Types of Plug-in Capabilities ·
   Internationalizing Your Plug-in
6. Plug-in Testing Techniques
   Debugging Basics · Cross-browser Testing · WordPress Version Testing
7. Finalizing Our Plug-in
   Creating a LICENSE.txt File · Creating an index.html File · Creating an uninstall.php File ·
   Creating Screenshot Images · An Overview of the readme.txt File ·
   Markdown Language Basics · The readme.txt File Structure
8. (coming soon) Submitting Your Plug-in to WordPress
9. (coming soon) Promoting Your Plug-in's Future
10. (coming soon) Advanced Plug-in Techniques

How to Add Contextual Help to Your Plug-in

At some point you may have clicked the “Help” link on an admin page … in the top right corner. By default, this dropdown context help simply displays two WordPress links: “Documentation” and “Support Forums”.

But, you may want to utilize this feature in your own plug-in, particularly if you offer a lot of features that need explanation. Actually, this is fairly easy to accomplish. As an example, we'll add help to the admin page of the plug-in we've been discussing, WCS QR Code Generator.

First, we need to make a couple of minor changes to our wcsp_qrc_activate_admin_options function in the wcs-qr-code-generator.php file. Here's the source code with the two updates highlighted.

Code: PHP (plus WordPress)Admin Context Help Revisions

414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431

function wcsp_qrc_activate_admin_options()
{
    global $current_user;
 
    global $wcsp_qrc_plugin_hook;
 
    $wcs_qrc_icon_url = plugins_url('wcs-qr-code-generator/images/wcs-qrc-icon.png');
 
    if (current_user_can('manage_options')) // typically Admin or Super-Admin
    {
        // at the bottom of all Dashboard menus (also has a custom icon)
        $wcsp_qrc_plugin_hook = add_menu_page('WCS-QR-Code', 'WCS-QR-Code', 2, 'wcsp_qrc_options', 'wcsp_qrc_options', $wcs_qrc_icon_url);
 
        // OR:
        // inside Settings menu block
        //add_submenu_page('options-general.php', 'WCS-QR-Code', 'WCS-QR-Code', 'manage_options', 'WCS-QR-Code', 'wcsp_qrc_options');
    }
}

On line 414 we declare a new global variable. It's global in scope so that we can use it in another function. Then, on line 425, we set its value. Each of the admin menu creation functions returns a hook name to track menu page callbacks. You only need this hook name for special circumstances … like creating contextual help.

Now, at the bottom of this primary plug-in file, we'll add the following code to complete the help feature.

Code: PHP (plus WordPress)Admin Context Help Functionality

438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497

/**************************************************************************
DISPLAY ADMIN HELP
**************************************************************************/
 
function wcsp_qrc_context_help($text, $screen)
{
    global $wcsp_qrc_plugin_hook;
 
    // create our helpful information
    if ($screen == $wcsp_qrc_plugin_hook)
    {
        // Comment the next line to also include any global help while on our page
        $text = '';
 
        $text .= '<br/>';
        $text .= wcsp_qrc_context_help_content();
        return $text;
    }
 
    // pass through for other admin page's help
    return $text;
}
 
 
add_action('contextual_help', 'wcsp_qrc_context_help', 10, 2);
 
 
function wcsp_qrc_context_help_content()
{
$output = <<<HEREDOC
    <h2>Help: WCS QR Code Generator</h2>
 
    <div class="metabox-holder">
        <div class="postbox">
            <h3 style="cursor:default;">Some Information</h3>
            <div class="inside" style="padding:0px 6px 0px 6px;">
                <p>
                    Now is the time for all good men to come to the
                    aid of their country. The quick red fox jumped over
                    the lazy brown dog.
                </p>
            </div>
        </div>
 
        <div class="postbox">
            <h3 style="cursor:default;">Some More Information</h3>
            <div class="inside" style="padding:0px 6px 0px 6px;">
                <p>
                    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
                    Nunc arcu enim, adipiscing eget porta ut, tempor gravida
                    sapien. Nulla ac venenatis dolor. Nam egestas ante ac
                    nisi pellentesque congue.
                </p>
            </div>
        </div>
    </div>
HEREDOC;
 
    return $output;
}

On line 442, we create a contextual help handler function. wcsp_qrc_context_help uses a format that is backward compatible WP 2.9 (3.0 made minor updates). On line 444, we declare our global hook name so that we can use it here even though it was created in another function.

In lines 447 – 455, we display our plug-in's contextual help content. On line 450 we clear the default WordPress help content … while on our page. Then, in line 453, we call the function that returns our help data as a string. We MUST include line 458 so that we don't change the contextual help of other admin pages.

On line 462, we activate the contextual help for our plug-in's admin page.

In reality, your help content could simply be a couple of lines of text. But, we kicked it up a notch by presenting nicely styled blocks of text … using the admin styling technique we explained in the last segment of this tutorial series.

Finally, we generate the output string in the wcsp_qrc_context_help_content function which starts on line 465.

It is worth noting that we use the PHP heredoc operator (<<<) to create our output string. This is a cool way of setting a variable's value to a large block of HTML code ... so that you don't have to be concerned about single and double quotes within the content. The only caveat   is that the closing identifier (HEREDOC; in our example) must begin in the first column of the line … it can NOT be preceded with any white space.

Here's what our sample contextual help (from the code above) looks like:

How to Offer a Customizable CSS File

Some plug-ins which offer visual output functionality include a CSS file in their root directory. Then, they provide the option to the plug-in user to copy that file to the current theme's folder as a priority replacement for the one in the plug-in's folder.

This way, the blogger can customize their copy of the CSS file without changing the default file. Here's an example of how to accomplish this feature.

Code: PHP (plus WordPress)Customizable CSS Functionality

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

add_action('wp_head', 'wcs_custom_css');
 
function wcs_custom_css()
{
    // set the url of default css file
    $css_url = WP_PLUGIN_URL . '/wcs-my-plugin/wcs-my-plugin.css';
 
    // instead, set the variable to the current theme's custom css (if it exists)
    if (file_exists(get_stylesheet_directory() . '/wcs-my-plugin.css'))
    {
        $css_url = get_bloginfo('stylesheet_directory') . '/wcs-my-plugin.css';
    }
 
    // output the css link in the header
    echo "\n" . '<link rel="stylesheet" href="' . $css_url . '" type="text/css" media="screen" />' . "\n";
}

In this example, we're using wcs-my-plugin as the plug-in folder name. And, we're using wcs-my-plugin.css as the CSS filename.

Note that we add an action to wp_head  to load plug-in's CSS file. This places it in the header (<HEAD> section) of the HTML source code when the theme calls the WordPress wp_head() function.

As an alternative to this add_action() technique, you could comment out the first line. Then, on line 15, you could use wp_register_style() and wp_enqueue_style().

How to Load Any Required Javascript Files

If your plug-in requires a proprietary javascript file, you can use the following example as a template for loading it. In this case, we've stored the supporting file in the js sub-directory of our plug-in folder.

Code: PHP (plus WordPress)How to Load a Javascript File

1
2
3
4
5
6
7

add_action('init', 'wcs_required_js');
 
function wcs_required_js()
{
    $js_url = WP_PLUGIN_URL . '/wcs-my-plugin/js/wcs-my-plugin.js';
    wp_enqueue_script('wcs-my-plugin', $js_url, '', '1.0', true);
}

Javascript files should generally be loaded in the footer section of a page. This is how we do it here. You may want to read more about the WordPress wp_enqueue_script() function.

Types of Plug-in Capabilities

Essentially, plug-ins offer four ways that the developer can extend the default WordPress installation. The actual implementation and capabilities of any of these four methods is at the plug-in developer's discretion (limited only by his/her skill set and imagination). Moreover, a combination of methods can be (and frequently is) incorporated into any plug-in.

Template Tags

One method is by creating template tags. This is a WP term for a PHP function that can be inserted into a theme file to add capabilities and features. Using our plug-in as an example, the wcsp_qr_code_generator function could be used directly by the network administrator.

Suppose you wanted to include a QR Code for the current page's URL near the bottom of every post on the blog. To do so, you could open a theme's single.php file and insert the following code just above the post meta section (where the categories and tags are listed).

Code: PHP

<?php if (function_exists('wcsp_qr_code_generator')) {wcsp_qr_code_generator ('100', 'darkblue', 'L|4', '');} ?>

Click this link to view the WordPress documentation on Template Tags.

Shortcodes

Action Hooks

Filter Hooks

Internationalizing Your Plug-in

Internationalization is the process of setting up your plug-in so that it can be localized for specific languages and/or regions. WordPress has internationalization and localization built into its core structure, including localization of plug-ins.

In all likelihood, you won't internationalize the first public release of your plug-in. However, you may well want to prepare for this future consideration while in the initial development stages.

Here's how to prepare. Instead of including output strings or text directly, you should process them through the _e() function. So…

Instead of
  "Now is the time for"
you would use
  _e("Now is the time for")

This simple conversion now will be a big time-saver later. Click this link to read the details about WordPress internationalization procedures.

Continue Reading…

In our next article, we'll continue with Plug-in Testing Techniques.

And, in the previous article, we discussed Implementing Dashboard Admin Pages.
 

Print PDF

Share This Article: “Easy WordPress Plugin Development (Part 5)”

(Also Available: Press CTRL+D to Bookmark this Page)