Introduction

Some of these ideas are taken from a page I started on the WordPress Codex to mull over workflow ideas.

WordPress is built to cater to the single user running a personal blog up to the global company running an entire website. In the big cases such as the latter, some controls and processes need to be in place to restrict what users can do and to assure that certain events take place in the correct order. Collectively, I’ll call these controls and processes a workflow and they’re the heart of the project I’d like to do for Google Summer of Code.

Wikipedia defines a workflow as:

A workflow is a reliably repeatable pattern of activity enabled by a systematic organization of resources, defined roles and mass, energy and information flows, into a work process that can be documented and learned.

This definition can be trimmed and refined a bit to better suit its application to WordPress, yielding:

A workflow is a reliably repeatable pattern of activity enabled by a systematic organization of resources, defined roles, and information flows, into a work process that can be documented and learned.

Use Cases

• category editors – to be published in a category, a post/page must be approved by an editor for that category
• writer->editor->designer – the writer writes text, which is edited by the editor, and then made pretty by the designer
• the big boss – everything that gets published must get the ok of the boss

System Design

I envision the workflow system being implemented as a plugin. I don’t think the number of people needing workflow controls justify putting it in the core. I do, however, think there is a critical mass of sites that would benefit from the plugin.

My initial thinking about the plugin leads to three main components: design, notification, and moderation.

Design

Under ‘design’, I categorize the definition of the workflow. This would be a ‘Settings’ page and would utilize some kind of GUI to create a funnel-like representation of the workflow. Posts/pages enter the system at the wide end of the funnel, go through a number of workflow stages, and emerge published at the other end. Designing the workflow would consist of creating vertices and edges in this tree. Vertices are moderation checkpoints that must be passed in order to move towards the root (publication). Edges are the path that documents travel along.

Another facet of the workflow design is assigning users to the vertices. A user at a vertex is the gatekeeper (moderator) of that stage, allowing documents to pass unscathed, modifying them, and/or sending them back to the previous stage. Here, I picture a drag/drop interface to assign users to vertices. Multiple users can occupy a vertex, as can one user occupy multiple vertices.

Notification

Notification is simply the idea that a user be notified when a document reaches his/her stage. This would naturally occur when a document has passed from the previous stage, but also when a document has been turned back from the next stage. Some options would be useful here to prevent a user from getting swamped with notification emails. For example, only notify a user once between logins or at most once per day.

Moderation

This is really the heart of the plugin. In order to pass through a stage, a moderator for that stage has to approve a document. The moderator can optionally modify the document before approving it. Once approved, a document either moves to the next stage or is published. A rejected document is sent back to the previous stage. Comments can be attached to the document to provide a justification for the decision.

Implementation

The design component will be implemented as a settings page that allows the user to graphically design the workflow. When saved, the workflow will be captured as a tree structure and written to the options table.

Each stage of the workflow will have a shortname (think post slug). This short name will be used to call an action when a post {enters, exits, …} that stage. For example, the action ‘workflow_editor_entered’ would be called with the post/page id when an author submits a document to the editor stage. Default action handlers would be included that would email the users in that stage. This is the notification component. These default action handlers could be disabled if a user wanted to just notice the waiting posts, or a different action handler that twittered or SMSed a user.

Forcing posts to go through the workflow would be largely accomplished with the current capabilities system. Many of the capabilities are meta-capabilities and are also sent through a user_has_cap filter before being processed. The plugin would add a handler to this filter that looked up in the workflow to see if that action was allowed. For example, in the case of an author X working on post 100 in the editing stage, the filter would receive the values (X, 100, editing). The plugin would determine if the user is able to pass posts through that stage.

There are a couple open questions about the implementation. If a published document is edited, where does it enter the workflow pipeline? Is the published version un-published? How does the revision control introduced in WP 2.6 play factor in?

Existing Functionality

WordPress introduced the concept of a ‘pending review’ state in version 2.3. This was a big step towards providing a workflow system, but it doesn’t go far enough. Indeed, it only covers the last use case above. In that case, the ‘big boss’ would need to be the only user with permission to publish. All other users would be able to create posts/pages and submit them for review. This only provides the moderation component of the design. There’s no built-in mechanism to notify the boss that a post is waiting for review. The only way to design the workflow is to designate the boss as having the publishing capability. There’s no further way to design such a trivial workflow.

The pending state doesn’t provide a workflow, but it makes it much easier to implement a full workflow system. Basically, the entire workflow exists inside of the pending state. When the original author thinks that a document is ready to be published, it is submitted for review, at which point it enters the workflow system and is given the pending state. The editors at that first level of the workflow are notified that a document is waiting for them. An editor makes any necessary changes and passes the document through to the next stage in the workflow. It is still in the pending state at this point. Until the document reaches the root of the workflow and is green-lighted to be published, it’s in the pending state.

When Mark Jaquith posted about the new pending state in June 2006, he wrote that “There are obviously a lot more ‘editorial process’ types of features that we could implement”. In addition, the comments on that post requested many of the features that this GSoC project would provide.

Previous Work

I’ve previously implemented a much simpler 1-stage workflow in a plugin called Zensor. It hasn’t been updated in quite a while due to external time constraints. This work was done for a high school in Germany where all changes to the website needed to be approved by the headmaster.

Public Comment

I solicited comments for this idea on the wp-hackers mailing list, but didn’t receive too much feedback. Maybe more comments will appear below.

Updates

4/10/2009: I added the Existing Functionality section and expanded on the Implementation details in response to comments from Jane Wells on the GSoC site.

I don’t think this has enough information. There is a review process built into WP core already… what actual functions are you proposing to built, how will they differ from current functions, and how will you approach it technically? Those are the questions that the application needs to answer.

Top 20 WordPress actions

As is clear from the graph, the most popular WordPress action is admin_menu. This makes sense, as one of the first things a plugin developer might want to do is have their plugin show up in the WordPress backend. Not surprisingly, many of the other top 20 actions are used just to get the plugin up and running: init, plugins_loaded, activate_, deactivate_, etc. The other well-represented group of actions are those dealing with the post life-cycle: save_post,publish_post, edit_post, delete_post.

In total, there were 659 unique actions used 12373 times. The graph above represents about 72% of the actions.

Top 20 WordPress filters

The shape of the top 20 filters graph is a bit different. the_content is the clear favorite of plugin developers, along with a couple other content filters: the_excerpt, the_content_rss, the_excerpt_rss. The query filters are also well-represented: posts_where, query_vars, wp, posts_join. The filter graph drops off pretty quickly so that most of the filters are used a maximum of 20 times.

In total, there were 512 unique filters used 5071 times. The above graph represents about 55% of the filters.

Method

I’ll post more about my method in the future. The numbers and graphs should be current as of SVN revision #85627 on 1/10/2009. A number of errors were encountered along the way and some corners were cut, so the numbers aren’t perfect.

As discussed previously in this series, you’ll need to have WP-Crontrol installed and go to the Add PHP Cron Entry screen under Manage->Crontrol. For Hook Code, enter the following snippet:

    $email  = 'There are currently ';
    $email .= akismet_spam_count();
    $email .= ' spams identified by Akismet, of which ';
    $email .= akismet_spam_count('comment');
    $email .= ' are comment spams and ';
    $email .= akismet_spam_count('trackback');
    $email .= ' are trackback spams.  Akismet has caught ';
    $email .= number_format_i18n(get_option('akismet_spam_count'));
    $email .= ' spams since you first installed it.';
    wp_mail('scompt@scompt.com', 'Spam statistics', $email);

Notice that all we’re doing is tossing a string together and sending it off to the wp_mail function to be emailed. You’ll of course want to change the email address. I personally don’t need to know how much spam you’re getting… I’ve got problems of my own.

• A Shortcode for use in posts and pages
• A template function for use in templates
• A dashboard widget

An example download graph looks like this:

Download Plugin-Stats Version 1.1

PHP Cron Entry Screen

The first requirement is to install WP-Crontrol. This will add the Manage->Crontrol admin screen. Head there and you’ll get a quick insight into what’s going on behind the scenes in the WP-Cron system. We want to add a new PHP cron entry, so click on the small link next to ‘Add Cron Entry’. Now you should have something like the screen to the right.

The code that we’re going to use for the hook is below. I won’t go deep into it. Suffice to say, it looks at the date of the most recent post. If it’s more than 2 days old, it sends out an email reminder.

    global $post;
    $recent = new WP_Query("showposts=1");
    if( $recent->have_posts() ) {
        $recent->the_post();
        if(time()-strtotime($post->post_date)>60*60*24*2)
            mail('scompt@scompt.com', 'Post reminder',
                 "Hey!  You haven't posted in a while.");
    }

The only other options to set are when to run the hook and how often. After saving the hook, it should run immediately. Depending on how good you’ve been, you’ll get an email.

The plugin was sponsored by The Lessnau Lounge which means each Twitterdoodle post contains a sponsored link to his site. He’s advertised it a bit better and word of it is already popping up on Google, etc.

Download Twitterdoodle 1.0

• Input PHP code directly into the Crontrol interface.
• Non-repeating (one-offs) cron entries can be scheduled.
• Cron entries with arguments are now properly handled

For plugin developers writing plugins using the WP-Cron system, this plugin is indispensable. For WordPress users, WP-Crontrol reveals the secret life of your blog. My series on taking control of the WordPress cron system provides code and tips on how to best utilize WP-Crontrol.

Download WP-Crontrol Version 1.0

add_action("sm_buildmap","scompt_series_sitemap");
function scompt_series_sitemap() {
    if( !class_exists(GoogleSitemapGenerator) ||
        !function_exists(get_series) ) return;
	$gen = &GoogleSitemapGenerator::GetInstance();
	if($gen != null) {
	    $all_series = get_series();
        foreach( $all_series as $series ) {
            $gen->AddUrl( get_series_link($series->term_id) );
        }
	}
}

I think the code is pretty self-explanatory. Lines 3 and 4 make sure that all the necessary bits have been loaded. Line 5 gets a copy of the object used to generate the sitemap and line 9 feeds it’s the URLs of your series pages. The AddUrl method takes a couple extra parameters that let you define last changed date, change frequency, and priority if you want.

The statistics are pulled using the same functions that the WordPress.com Stats plugin uses and are cached for 5 minutes, as are all stats from the plugin. The graphic is created on the fly using the Google Charts API. The plugin just build the URL and sends it to the browser. Colors, timespan, and Google Charts parameters are all completely configurable using filter hooks.

WordPress 2.5 is the primary version supported. Previous versions should work, but have not been tested.

Download ImmerStat Version 0.5

One quick note

It appears that something changed in Version 2.5 that breaks the way that the posts_where hook was being attached. Initially, the admin_head hook was being used to attach it. This isn’t that great because it means the hook is loaded on all admin pages, which isn’t really necessary. Also, as I said, it just doesn’t work in the new version of WordPress. A better way, which replaces lines 21—24 in the code below is:

add_action('load-edit.php', 'scompt_load_edit_page');
function scompt_load_edit_page() {
    add_filter('posts_where', 'scompt_posts_where');
}

What we’re starting with

Comparison of WordPress 2.3 & 2.5

Below is the code that we ended up with in the last post. To the right, you’ll see a screenshot of how it looks in the WordPress 2.3 and 2.5. WordPress 2.2 should look the same as 2.3, but it’s old enough that we’re not concerned with it. There are a couple things worth noting in the image.

In WordPress 2.3, the dropdown fits with the other dropdowns. That’s good. Notice that there’s two ‘Filter’ buttons. That’s bad, but was necessary because the restrict_manage_posts hook is called outside of the form element. In WordPress 2.5, there’s a stylish light-blue bar where the filters should go, and there’s our filter sitting out in the middle of nowhere. Also, there’s no longer a border with label surrounding the dropdown. The last thing to notice is that the text inside of the dropdown is different: “Any” compared to “Show all Dates” in the case of the date filter. This leaves us with a nice TODO list of things to accomplish in this post:

1. Get rid of the extra ‘Filter’ button
2. Put the dropdown in the filter bar
3. Get rid of the border and label surrounding the dropdown
4. Make the text shown in the dropdown fit better with the other filters
5. Make sure it still works and looks good in WordPress 2.3

add_action('restrict_manage_posts', 'scompt_restrict_manage_posts');
function scompt_restrict_manage_posts() {
    global $wpdb;
    $has_count = $wpdb->get_var("SELECT COUNT(*) FROM wp_posts WHERE post_type='post' ".
        "AND ID IN (SELECT post_parent FROM wp_posts WHERE post_type='attachment')");
    $hasnt_count = $wpdb->get_var("SELECT COUNT(*) FROM wp_posts WHERE post_type='post' ".
        "AND ID NOT IN (SELECT post_parent FROM wp_posts WHERE post_type='attachment')");
    ?>
		<form name="scompt_attachmentform" id="scompt_attachmentform" action="" method="get">
			<fieldset style="margin: 0pt 1em 1em 1.5em; padding: 0pt; float: left;">
    			<legend><?php _e('Attachments'); ?>&hellip;</legend>
    			<select name='scompt_attachments' id='scompt_attachments' class='postform'>
        			<option value=""><?php _e('All'); ?></option>
        			<option value="has" <?php if( isset($_GET['scompt_attachments']) && $_GET['scompt_attachments']=='has') echo 'selected="selected"' ?>><?php _e('Has attachments'); ?>  (<?php echo $has_count ?>)</option>
        			<option value="hasnt" <?php if( isset($_GET['scompt_attachments']) && $_GET['scompt_attachments']=='hasnt') echo 'selected="selected"' ?>><?php _e('Has no attachments'); ?>  (<?php echo $hasnt_count ?>)</option>
        		</select>
			</fieldset>
			<input type="submit" name="submit" value="<?php _e('Filter &#187;'); ?>" class="button" style="float:left;margin:14px 0pt 1em;position:relative;top:0.35em;"/>
		</form>
	<?php
}

add_action('admin_head', 'scompt_admin_head');
function scompt_admin_head() {
    add_filter('posts_where', 'scompt_posts_where');
}
function scompt_posts_where($where) {
    global $wpdb;
    if( $_GET['scompt_attachments'] == 'has' ) {
        $where .= " AND ID IN (SELECT post_parent FROM {$wpdb->posts} WHERE post_type='attachment' )";
    } else if( $_GET['scompt_attachments'] == 'hasnt' ) {
        $where .= " AND ID NOT IN (SELECT post_parent FROM {$wpdb->posts} WHERE post_type='attachment' )";
    }
    return $where;
}

Getting down to work

I would suggest that we just head straight down our TODO list. The first point is to get rid of the ‘Filter’ button. Luckily, the restrict_manage_posts hook is called inside the form in version 2.5, eliminating the need for it. This also means that we can leave out the form tag that was previously necessary. In summary, cut out lines 9, 18, and 19.

The second point and third points can be solved together. The reason the dropdown is getting shoved outside the filter bar is actually because of the border and label that we wanted to get rid of anyway. This means not printing the fieldset and label tags, so we can get rid of lines 10, 11, and 17. You’ll notice that out code is getting whittled away pretty quickly. That’s what I call progress.

The fourth point is a logical consequence of the previous one. There’s no longer a label describing what the dropdown does, so now the text inside the dropdown has to do so. Previously, our label was “Attachments” and the dropdown text was “All”. Now, we need to come up with a phrase that captures the essence of the two former phrases. The best I could come up with is “View with/without attachments”, which needs to be changed in line 13. Leave a comment if you have a better idea. This label will go inside the default first option in the dropdown.

Posts filtering on 2.5

At this point, having addressed the first four points, we have a working chunk of code for WordPress 2.5. Below is the updated copy of the scompt_restrict_manage_posts function and to the right a screenshot of the results. We’ll hit the last point in the next section.

function scompt_restrict_manage_posts() {
    global $wpdb, $wp_version;
    $has_count = $wpdb->get_var("SELECT COUNT(*) FROM wp_posts WHERE post_type='post' ".
        "AND ID IN (SELECT post_parent FROM wp_posts WHERE post_type='attachment')");
    $hasnt_count = $wpdb->get_var("SELECT COUNT(*) FROM wp_posts WHERE post_type='post' ".
        "AND ID NOT IN (SELECT post_parent FROM wp_posts WHERE post_type='attachment')");

    ?>
	<select name='scompt_attachments' id='scompt_attachments' class='postform'>
		<option value="0"><?php _e('View with/without attachments') ?></option>
		<option value="has" <?php if( isset($_GET['scompt_attachments']) && $_GET['scompt_attachments']=='has') echo 'selected="selected"' ?>><?php _e('Has attachments'); ?>  (<?php echo $has_count ?>)</option>
		<option value="hasnt" <?php if( isset($_GET['scompt_attachments']) && $_GET['scompt_attachments']=='hasnt') echo 'selected="selected"' ?>><?php _e('Has no attachments'); ?>  (<?php echo $hasnt_count ?>)</option>
	</select>
	<?php
}

Backwards Compatibility

Now that we’ve shrunk our code down to it’s 2.5 essentials, it’s time to balloon it back up again to make it backward-compatible with 2.3. If you’re running 2.5 and don’t plan on looking back anytime soon, you can skip this section and still live a happy life.

The first step is being able to differentiate between version 2.3 and 2.5. To do this, we’ll take advantage of the PHP function version_compare and the WordPress global $wp_version which comes from wp-includes/version.php. Putting those together, we get the following useful bit:

if( version_compare( $wp_version, '2.5', '<' ) ) {
    // Versions before 2.5
} else {
    // Version 2.5 and later
}

Because our 2.5 code is essentially the 2.3 code wrapped in a couple tags (form and fieldset) with a couple extras thrown in at the beginning and end (legend and input), I would suggest making variables to hold these extra $before and $after bits. For version 2.5, these variables will be empty. The only other difference is the verbage in the dropdown. Here's the final code that will work well and look good for WordPress versions 2.2 — 2.5.

function scompt_restrict_manage_posts() {
    global $wpdb, $wp_version;
    $has_count = $wpdb->get_var("SELECT COUNT(*) FROM wp_posts WHERE post_type='post' ".
        "AND ID IN (SELECT post_parent FROM wp_posts WHERE post_type='attachment')");
    $hasnt_count = $wpdb->get_var("SELECT COUNT(*) FROM wp_posts WHERE post_type='post' ".
        "AND ID NOT IN (SELECT post_parent FROM wp_posts WHERE post_type='attachment')");

    if( version_compare( $wp_version, '2.5', '<' ) ) {
        $before  = '<form name="scompt_attachmentform" id="scompt_attachmentform" action="" method="get">';
        $before .= '<fieldset style="margin: 0pt 1em 1em 1.5em; padding: 0pt; float: left;">';
        $before .= '<legend>'. __('Attachments') .'&hellip;</legend>';
        $all = __('All');
        $after  = '</fieldset>';
        $after .= '<input type="submit" name="submit" value="'. __('Filter &#187;') .'" class="button" style="float:left;margin:14px 0pt 1em;position:relative;top:0.35em;"/>';
        $after .= '</form>';
    } else {
        $before = "";
        $all = __('View with/without attachments');
        $after = "";
    }
    echo $before;
    ?>
	<select name='scompt_attachments' id='scompt_attachments' class='postform'>
		<option value="0"><?php echo $all; ?></option>
		<option value="has" <?php if( isset($_GET['scompt_attachments']) && $_GET['scompt_attachments']=='has') echo 'selected="selected"' ?>><?php _e('Has attachments'); ?>  (<?php echo $has_count ?>)</option>
		<option value="hasnt" <?php if( isset($_GET['scompt_attachments']) && $_GET['scompt_attachments']=='hasnt') echo 'selected="selected"' ?>><?php _e('Has no attachments'); ?>  (<?php echo $hasnt_count ?>)</option>
	</select>
	<?php
	echo $after;
}

add_action('load-edit.php', 'scompt_init_attachments');
function scompt_init_attachments() {
    add_filter('posts_where', 'scompt_posts_where');
    add_action('restrict_manage_posts', 'scompt_restrict_manage_posts');
}
function scompt_posts_where($where) {
    global $wpdb;
    if( $_GET['scompt_attachments'] == 'has' ) {
        $where .= " AND ID IN (SELECT post_parent FROM {$wpdb->posts} WHERE post_type='attachment' )";
    } else if( $_GET['scompt_attachments'] == 'hasnt' ) {
        $where .= " AND ID NOT IN (SELECT post_parent FROM {$wpdb->posts} WHERE post_type='attachment' )";
    }
    return $where;
}

Conclusion

We've now successfully updated the Manage Posts filtering code for WordPress 2.5. In the process, we even made it backward compatible. This has been another post in my series on Pimping your Manage Panel. Keep an eye peeled here for when I present my ever-promised technique of filtering in the Manage Pages panel.

Update!

One thing I forgot to mention. In WordPress 2.5, the restrict_manage_posts hook is also used on the upload screen. To make sure your dropdown code doesn't appear on the upload screen, make sure you add the restrict_manage_posts action inside the scompt_init_attachments hook. This will make sure it only gets loaded when edit.php is called. I've made the change on the above code snip