I was curious why people were reporting having trouble accessing the Compact Calendar. Usually, my site access problems stem from PHP timing-out while WP-Cache is attempting to build the page, which means that nothing shows up. Usually I clear the cache, and the problem goes away.

This time, though, it was a user error on my part; apparently I’d set the Private flag on that post while making some update. WordPress then continues to show me the post because I’m logged-in to the system, but everyone else sees the message sorry no posts found. Because of the clicky nature of the post editing window, which took a small usability step backwards in 2.0, it’s not difficult to accidentally click and set the post status to private without realizing it.

Anyway, the Compact Calendar is back online…I apologize for the trouble in accessing it. And for WordPress users, here’s what I did to fix it so this doesn’t happen again. WARNING! Geek talk follows!

Making the Invisible Visible

The problem is that I can’t tell as a logged-in user that a post is marked private. This is entirely because my aging WordPress template isn’t coded to display this information. It’s been frankencoded out of bits of the old WordPress 1.1 template with MovableType’s old CSS. So the solution is to add some conditional logic to check the following:

1. Is a private post being displayed?
2. If yes, then display something like “PRIVATE POST ” somewhere visible on the page.
3. If no, display normally.

The challenge is now to figure out how to modify my template to do this, which means that once again I get to dive into the WordPress API. Which is incompletely documented. The way that I’ve cobbled together my bits of functionality is by studying other plugins and templates discovered through dilligent googling, using search terms that are descriptive of the problem (“wordpress show private posts”) and are also a bit technical (“template is_private”). The “is_private” search term is based on a guess I made about what function WordPress might have to help me detect if a particular post is private or not; there are several other ‘is_this’ and ‘is_that’ functions that are built-in to the system. Read on.

Checking for a Private Post

There are a number of special functions that you can use in your WordPress Loop to conditionally display information. The Loop is the PHP code that actually pulls your articles one-by-one from the database and displays them in vivid HTML; if you want to modify the appearance of a post based on its category, you can use the is_category() function to check whether it is in a certain one.

There’s a whole bunch of such functions available, and I’ve never found a complete and comprehensive list of them in one place, until I stumbled upon PHPXRef. There’s a complete WordPress function list available (click the functions tab at the top of the screen) that lists everything that I need to see for the latest version of WordPress. Alas, there is no additional documentation other than the list, but since WordPress is coded with fairly clear function and variable naming conventions, a programmer with direct experience with the application can scan the list and get an idea of how the application operates just by seeing how elements are named. It’s not unlike being able to walk into an office and read, just by looking at the arrangement and details of the space, how things get done (or not).

The specific function I was looking for was something like is_private(), but SURPRISE…there IS no such function! Fortunately, someone else already figured this out and posted a solution. The code just queries the WordPress post directly and checks the post_status flag. I didn’t know how the WordPress posts were organized, so this saved me a lot of digging. I took the function and dropped it into my template directory’s functions.php file. This makes the function available for use in my template (and ties it directly to my template, which makes it more portable from installation to installation).

Now I can make the changes to my template. There’s a line of code in it that looks something like this:

&lt;?php     if ( is_private() )       echo "<span style='color:red'>PRIVATE POST</span>"; ?&gt; Filed under &lt;?php the_category(', ') ?&gt;

The conditional IF statement will prepend PRIVATE POST (in red letters) in front of the normal “Filed under [category]” bit of text, but only if it’s a private post. For regular users, this will never happen. For ME, I should see the warning signs pretty clearly next time I bungle the privacy setting on a post.

Going Further

There are 30-something other simple is_something functions that you can explore at PHPXref, along with everything else. Unfortunately it’s not exactly documentation. I find it useful for just seeing the “big picture” of function availability. If I want to know what the function does, I have to click on the function name, then look at the source code to divine what it actually does. It’s not a bad way to learn PHP though, by modifying a piece of software you use everyday.

Here’s an example of exploring the reference: I was scanning the list and the is_preview() function caught my eye. So I clicked it, then clicked on the defined in line # link on the next page, and this took me to the place in the WordPress source code that defined it. You can follow around such links until you find some comments that tell you what the hell it’s supposed to do; in this case, the pertinent comment in wp-include/classes.php was if we're previewing inside the write screen. Now I know what this function does.

There’s a lot of tracing lines of logic and following declarations, so this technique won’t work for the novice programmer who’s just learning how to code. For more experience programmers, it’s a pretty quick way to explore the code without a heavy-duty integrated development environment (IDE) capable of cross-referencing functions, variables and classes. Doing this on the web is actually a little more convenient for me, since I don’t have to worry about messing up my WP source files by accident.

Another cool thing: the PHPXRef site also covers other blogging and CMS systems, so this could be a very useful resource for understanding the architecture of those systems using a “ground-up” approach…which is really your own option when the official documentation fails to provide that picture for you.

So that’s that.