Dealing With Inaccuracy In The WordPress Codex

(Reading time: 9 – 14 minutes)

>>>NOTE: the primary audience for this article is people with much-less-than-expert knowledge of WordPress and programming. WordPress experts may find some food for thought in remarks on the Codex about halfway through.

It’s another beautiful day in paradise. I should be at the beach, but instead, I’m slaving away for you, bringing you the freshest information I can find on all things WordPress.

So, “What’s on the agenda this morning?” you ask…

Well, I’ve been teaching myself to write WordPress plugins.

I’m not very good yet, but it’s fun and useful.

As a result I’ve spent a fair amount of time perusing the WordPress Codex teaching myself various bits and pieces of the WordPress system. Some of the Codex is really good, some of it is out of date.

I’m also examining the source code for a half-dozen or so plugins. Some plugins are fairly well-written, others… not-so-much. As I’m writing this post, one of my current favorites is Amazon Reloaded for WordPress. I like both the design and the style of this plugin. It’s nice to read literate code. I’ll make a list below with a few more that I’m using for example code.

I’m also working my way through PHP5. My previous exposure to PHP ended in the version 4.x series (or maybe it was 3.x?) right before Google totally changed the Google Maps API (everything we wrote broke all at once). So I never made the jump to classes. PHP is one of these technologies I think I should like more than I do. (Python on the other hand, I like much more than I thought I would.)

It’s keeping me busy!

Even busier parsing slightly out-of-date information…

What the Codex doesn’t say about class-based plugins

In the Codex, the plugin examples (generally) don’t use PHP classes, but a large number of interesting plugins do use PHP classes. This creates an opportunity ripe for misunderstanding, which I thoroughly exploited.

Here’s what happened while I was working on a little demonstration plugin recently. By “demonstration,” I mean a plugin whose only reason for existence is to demonstrate to me exactly how something works. In this case, I was testing database table creation and dropping.

Part of the plugin appeared to be working correctly. The database table was being correctly created but the entry in the WordPress administration Settings menu was not appearing. I wasn’t getting the add_action callback to add the example text. Which seemed strange, because I copied that code from known working code elsewhere.

Here’s what the Codex has to say for add_action:

add_action( $tag, $function_to_add, $priority, $accepted_args );

In more concrete terms, I need something like this:

add_action('hook', 'my_function');

…time passes. I’m checking my code line by line. (Experienced PHP programmers know what I’m looking for.) Eliminating everything unnecessary.

And there it is: When using PHP classes with the WordPress hooks, you have to pass an array through, not just the callback by it’s bare self:

add_action('hook', array($this, 'my_function'));

Here’s my stripped down code for calling on_admin_menu:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

class demo_plugin_database {
 
    // Pass an array as arg2 when using classes.
    function demo_plugin_database() {
       add_action('admin_menu', array(&$this, 'on_admin_menu'));
    }
 
   function on_admin_menu() {
	add_options_page('Demo Database Page', 'Demo Database', 8, __FILE__, array( &$this, 'database_options' ));
   }
 
   function database_options() {
?>
       <div class="wrap">
       <p>Here is where the form would go if I actually had options.</p>
       </div>
< ?php
   }
}
$wpdpd = new demo_plugin_database();
?>

Now, this is really old hat to experienced PHP programmers. Not so obvious to someone bootstrapping their way in. Once I saw it, it was totally obvious.

Years ago, I would have beefed about it on the forum. Nowadays, I make a note to myself… or write a blog post about it.

Someone without a lot of experience… this could trip them up for hours.

Codex or not to Codex

[I noted while proofreading this article that there is a call for editing to update the add_action page on the Codex. The call for action is at the bottom of the add_action page, it would probably be more effective at the top of the page.]

Now, I know at least one reader may be thinking… “Why didn’t you put this in the Codex?”

Good question, and I’m glad you asked.

There’s several reasons, but first, let me explain a couple of things:

• I’m not criticizing the Codex in general. I have a long term interest in the nature of writing, documentation, document storage, document classification, etc. Maybe I’m a bit of a librarian at heart.
• I’m not criticizing any person in particular. The amount of work the top authors have put into their parts of the Codex is staggering, and it’s something I completely and thoroughly respect.

Now here are those reasons.

First, I like screenshots, and I’ve never run across images in the Codex. True, I haven’t looked that hard, but still, if images were common, I would have seen several by now.

Second, I’ll maintain this web page on Website In A Weekend or I’ll take it down. You can check the wayback machine. I have a history of taking down my websites, and I’ll take this one down the instant it stops serving my purpose. But most likely, I won’t maintain my own work on the Codex. More from lack of time than lack of desire. I would like to help maintain the Codex, but there are other things I would prefer to do instead.

Inaccurate and unmaintained pages on the Codex (anywhere, really) tend to outlive their usefulness. In this case, “bit rot” is setting in. In another example, I was examining some links on the Codex page for User:L            ‘s page, and both 3 links to color scheme generators I tried were broken. Bummer. As it turns out, I like Color Scheme Designer, which I didn’t see listed anyway (and I may well have missed it, there’s a lot of links there). The page is rotting away. Without maintenance, it will eventually degrade past the point of usefulness.

Third, I’m no longer sold on the notion that centralized documentation is always either necessary or desirable. If it absolutely must be canonical, tag it or time stamp and publish it in an uneditable format, like dead tree. We’re not supposed to need everything totally centralized anymore. Before anyone jumps my case about canonical documents, I could almost as easily argue the opposite, and I have in the past. But this is what I’m thinking at this particular stage of the web.

I have a whole post on There Is NO Box discussing what constitutes a canonical document. It’s not easy to define.

Fourth, I would prefer to write my own material, and I don’t have a lot of time. See reason two above.

Fifth, having high quality and accurate documentation widely disseminated mitigates one of the most notorious problems with all search engines: irrelevant results. Having an accurate Codex page come up #1 on the topic I’m searching for is great. It doesn’t often happen. If the information on that page turns out to be inaccurate, very often many of the trailing search results turn out to be either wrong (correct answer for different question), a more-or-less blatant copy of the Codex, or outright garbage (i.e., spam blog, answers nobody’s question at all).

Sixth, and most importantly, being an effective contributor to the Codex requires time to learn the unwritten rules of the community creating and currently maintaining the Codex. If you don’t take the time to suss out the rules, your contributions have little chance of acceptance. This isn’t a bad thing. It’s human nature, and worth keeping in mind. After all, if you make an incorrect contribution, you’re part of the problem, not part of the solution!

Finally, this article is a work in progress, and I intend on keeping it updated. Comments are welcome, especially opposing points of view, argued rationally. (ad hominem goes to /dev/null)

So, what?

The current explanation in the Codex for add_action is fine for non-class-based plugins. If you’re just starting out and you’re new to PHP and the WordPress system, start with what works first, then migrate EARLY to code that will be supported in 2.8 and beyond.

Could any of this information found elsewhere on the web?

Probably, given you somehow search on the exact terms that will allow Google or Yahoo to find it for you. It’s probably on the Codex as well, but again no search terms I tried got me any closer than running my own experiments.

Demo Database Plugin

Inserting into Settings

Here’s a screenshot of the activated plugin’s menu item in the Settings menu.

Hints for newbies

A lot of new programmers get overwhelmed once they realize that writing code is only about half of what a programmer does, and code writing is the easier half by far. All the other stuff is maddeningly time consuming. Especially documentation.

1. If you find an inaccurate Codex page, check the date when it was last edited. You can assume fairly reasonably that it was correct when it was written, and you can start from that date in the source code and mailing lists to figure it out.
2. Check the material on the page for internal consistency. For example, the plugin example I reference WILL work as written, provided it’s not part of a PHP class. So it’s not wrong, just incomplete with respect to a lot of the code sitting in the plugin repositoty.
3. I’m a big believer in writing to learn, and Murray’s “Write To Learn” is a seriously good book. I’ve been writing a long time, and I’ve learned a lot from Murray. By all means, when you find inaccurate or outdated information anywhere on the web, consider writing a little note in the appropriate venue. Blogs are excellent for this task. If it’s in the Codex, seriously consider getting a Codex account and learning how to fix it yourself. Do both!

   I’m such a big believer in this learning style, I recently wrote an article on writing to learn, and you should check it out.

This article is far too long now. I promised above I would list out a few cool plugins, but… that was a fib. However, interested readers could inspire me to write a longish article on exactly how to use the plugin repository to rapidly bootstrap your plugin code writing skills. The concepts are easy, the devil is in the details. I’ve read a LOT of source code over the last 15 years. My knowledge is yours to exploit… just let me know.

This article is licensed in the Creative Commons, please retain source attribution.