WordPress Plugin Construction for the Non-Programmer: Part III

First, a couple of guidelines for getting the most out of this series:

How to Create a Very Basic WordPress Plugin

WordPress Plugin Creation for the Non-Programmer: Part II

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.

{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”)){

class YourBrandWPBasic {

function YourBrandWPConstructor {

}

}//close check for existing class//

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

If(class_exists(“YourBrandWPBasic”)) {

$your_brand_wp_basic = new YourBrandWPBasic();

}//close assignment of handler//

?>

Remember that the comments which are surrounded by the “//” characters explain exactly what the code is either about to do or has just done. These comments will not be read and processed by WordPress. They’re strictly in place to help you or anyone who will be working on your plugin in the future to keep track of what the code is doing

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

In the last tutorial, we talked about how your class was like your toolbox, the methods (also called functions) inside it were like the tools and the “handler” was like the magic WordPress elf who will be handling your class and going to work in the WordPress Workshop.

As you can see, the class (toolbox) “YourBrandWPBasic” only has one tool (method) in it right now, which is called “YourBrandWPConstructor.” So when your WordPress elf opens up his toolbox to go to work, he only finds one tool…not very efficient. So let’s add two new tools before we give your handler a task to perform in the WordPress Workshop.

The following code is the class which we created in the last tutorial, with two new methods (functions) added. The methods have been named “Brand Title” and “Brand Content.”

{code type=php}

<?php

if(!class_exists(“YourBrandWPBasic”)) {

// create class //

class YourBrandWPBasic {

function BrandTitle($title) {

$title = “<h1>Woah!</h1>”;

return $title;

} // close brand title method //

function BrandContent($content) {

$content = “<p>The Basic Plugin has taken over your WordPress site!</p>”;

return $content;

} // close brand content method//

function YourBrandWPConstructor(){

}//close constructor //

} // close class //

} //close check or existing class //

?>

Notice that we’ve followed the principles you learned in the first tutorial of this series and added a function which set the variable “$title” to equal “Woah!” and the variable “$content” to equal “The Basic Plugin has taken over your WordPress site!” The peculiar looking characters surrounded by “<” and “>” are not PHP, but html “tags.”

These html tags tell WordPress what type of content you want it to echo out. For example “p” stands for paragraph. So by putting <p> (the opening tag) at the start of your content and </p> (the closing tag) at the end, you’re telling WordPress to format that text using the font size and style it normally uses for paragraphs.

The “h1” stands for “Header 1” and it tells WordPress to format that text as it normally would the primary (first) headers on your site. So if you were to translate this method into plain English…

{code type=php}

<?php

function BrandContent($title) {

$content = “<p>The Basic Plugin has taken over your WordPress site!</p>”;

return $content;

} // close brand content method//

?>

…it would read like this:

“WordPress!  When I use the tool “BrandTitle” I want you to format the content inside <h1> like you would a primary header!”

The same principle applies for the second method which you named “BrandContent.” Of course, the immediate question is how these tools are going to be used to make things happen in the WordPress Workshop.

Step #2: Give Your New “Tools” to Your Handler and Have Him Go to Work

Once you’ve got your methods created, assigning them to your handler is easy. You simple use WordPress filters, as we talked about in the first tutorial of this series to tell your handler where the tools will be used. So here’s what your handler assignment (instance) will look like with the two new methods applied:

{code type=php}

<?php

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

if(class_exists(YourBrandWPBasic)){

$your_brand_wp_basic = new YourBrandWPBasic();

// use brand title method to change title //

add_filter(‘the_title’,array($your_brand_wp_basic, ‘BrandTitle’),1);

// use brand title method to change content //

add_filter(‘the_content’,array($your_brand_wp_basic, ‘BrandContent’),1);

}//close assignment of handler//

?>

Notice the two lines which start with “add_filter,” those functions tell WordPress to pass its content through the filters you assign between “(“ and “)” before displaying that content on your blog. Remember that WordPress uses “hooks” to determine what type of content to filter.

The hook which is used in the first line is “the_content” and the second uses the hook “the_title.” The only difference between this example and the example of how we used this filter in the first tutorial is that instead of your function, you have some code which says “array($your_brand_wp_basic, ‘BrandTitle’) after your first comma.

This appears confusing at first, but notice that you’re simply telling WordPress that your handler ($your_brand_wp_basic) is grabbing the tool named “BrandTitle” out of his toolbox (the “YourBrandWPBasic” class) and using that tool to manipulate the title of your WordPress site. That PHP function which says “array” simply tells WordPress that instead of a single function name, you’re passing it an array of data to represent the function you want to filter the content through.

It’s the same principle with the filter for ‘the_content,’ so what you’ll end up with is a post title and post content which reads like this:

That last little “1” that you see simply tells WordPress to make that filter it’s #1 priority. So if you were to translate this code into plain English:

add_filter(‘the_content’,array($your_brand_wp_basic, ‘BrandContent’),1);

…it would read like this:

“WordPress!  This is “$your_brand_wp_basic.” I’m the official handler for the Basic Plugin and I want you to use the tool named “BrandContent” to filter all your post content so that reads The Basic Plugin has taken over your WordPress site! “ This will be a #1 priority, so let’s make it happen!”

If any of the terminology here is confusing, please check out the first two tutorials in this series, but it should be fairly simple when you read it in English commands.

If you’d like to test out the code we’ve written so far, I’ve left the entire plugin code below:

{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 {

function BrandTitle($title) {

$title = “<h1>Woah!</h1>”;

return $title;

} // close brand title method //

function BrandContent($content) {

$content = “<p>The Basic Plugin has taken over your WordPress site!</p>”;

return $content;

} // close brand content method//

function YourBrandWPConstructor(){

}//close constructor //

} // 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();

// use brand title method to take over title //

add_filter(‘the_title’,array($your_brand_wp_basic, ‘BrandTitle’),1);

// use brand title method to take over content //

add_filter(‘the_content’,array($your_brand_wp_basic, ‘BrandContent’),1);

}//close assignment of handler//

?>

I suggest experimenting with this by changing the actual content of the title and post or perhaps by trying a few new filters. Just be sure that you’re working on a WordPress testing site instead of a live one. In the next tutorial, we’ll start working on making your plugin do things within the WordPress admin panel.

Comments and questions are welcome.

-Till next time, Seth C

 

7 Responses

  • New Recruit

    This posts series are really amazing. I was wondering if there’s a way to search&replace a part of a php template (pre processed), or if that’s not clever, to replace one file (default in wordpress) for another with some extra feature. I’m trying to make a plugin that changes some php part inside a template (let’s say the post loop) and changes it for another piece of code… how do I “invalidate” the original post loop in favor for my new improved one? or if it’s not just a snippet and I want to replace a whole file, shall I use a search and replace or a “child theme” part giving it along with the plugin or what would be the smartest approach? Thanks a lot for all this knowledge!! :D

  • Hi Juanma,

    If I’m understanding you right, that could get pretty tricky. If you change one thing in the default code, there could be other parts of the code, or application which depend on the part you changed and which will start spitting out errors that are very hard to debug. I’d really need to know the specific thing you’re trying to accomplish to give a good answer, but you could always wrap something inside a conditional loop and provide another conditional loop with the alternative code in it.

    Again, not 100% sure what you’re trying to accomplish.

  • New Recruit

    Hi, Seth, thanks for the amazing feedback. I just want to customize some code, for example, let’s imagine we have the post-loop and I want to replace the part were the comments are spitted out (no dependencies since it’s just a template that is showing the info, not affecting the original function that gather the posts from the DB or nothing like that) and let’s suppose I want to replace it for a customized code.

    As an example (not real code):

    `
    //I want to search for this code inside "file.php"...

    says
    }

    //And let's suppose I want to replace it for...

    Let's hear what has to say, while hears him talk
    }
    `

    I hope this can give you an idea of what I’m looking for. I know I could just make a “child theme” with the modified “file.php” but sounds messy to me since the user who wants to “download this plugin” would have to install it as a theme and mine would not know what theme was the user originally using… that does not seem right.

    But maybe you can give me a peace of advice on how to approach this issue. I think plugin developers surely finds this kind of challenges every once in a while, what you think?

    Again, thanks for your help and feedback!!! I hope I will make my first plugins with this :D

    • Okay, I see what you’re trying to do. There’s a simpler and safer
      way to do this though. WordPress has provided “filters” which
      you can use to manipulate text such as the post title, the post
      content and the comments and much more. I explain a simple way to
      do this in the first and second posts of this series
      which you can find under my author directory.

      In those first two posts ^, I use the two filters “the_title” and
      “the_content” to replace the title and content of a post, but you
      can apply the same approach to comment text using this filter:

      comment_text

      >How it works: Applied to the comment text before displaying on the screen by
      the comment_text function, and in the admin menus.

      Or, if you want to get a bit more saucy and know how to use PHP
      arrays, this filter:

      comments_array

      >How it works: applied to the array of comments for a post in the
      comments_template function. Filter function arguments: array of
      comment information structures, post ID.

      There’s a full list of the WordPress filters and what they do
      here:

      http://codex.wordpress.org/Plugin_API/Filter_Reference

      Based on what you seem to know about PHP, and using the
      tips I cover in these first two posts, I’m sure you’ll be able to
      apply these filters to do what you want. If not, I’ll actually
      be covering more on how to manipulate comments and post content
      using your WordPress plugin class in future tutorials.

      BTW: If you don’t want to replace the entire comment text, you can
      slurp the comment data into a variable called “$comment,” and tack your
      extra stuff onto the end of the comment, like this:

      {code type=php}

      $comment.= ‘I want to add this text to the end of each comment.’

      {/code}

      That “.=” appends the stuff on the right of the “=” to the variable on
      the left. So this…

      {code type=php}

      $comment.= ‘stuff.’;

      {/code}

      …is like saying “comment data plus ‘stuff’ equals comment dat.” So if
      you did this:

      {code type=php}

      $comment = ‘original WP comment data.’;
      $comment.= ‘stuff.’;
      echo $comment;

      {/code}

      …it would echo:

      original WP comment data stuff.

      Or you could reverse it:
      {code type=php}

      $comment = ‘original WP comment data.’;
      $new_comment_text = ‘add stuff to.’;
      $new_comment_text.= $comment;
      echo $new_comment_text;

      {/code}

      …it would echo:

      add stuff to original WP content data.

      Once you’ve got the data you want stored in a variable, you pass it
      through the WP filter (as I did in tutorials one and two) and you’ve
      got a new comment format.

      Thanks for the question.

Comments are closed.