function my_first_callback( $post_id, $post ) {
  // do something...
}
add_action('save_post', 'my_first_callback', 10, 2);

So far, pretty simple. Now let’s put something in our callback function.

function my_first_callback( $post_id, $post ) {
  if ( $post->post_type == 'post' ) {
    wp_insert_post(array(
      'post_title' => 'A Post',
      'post_status' => 'publish',
      'post_type' => 'a_custom_post_type',
    ));
  }
}
add_action('save_post', 'my_first_callback', 10, 2);

Not a horribly complicated function. We’ll leave aside my reasons for creating a post in this callback (there’s a myriad of reasons why one might want to create or update a different post when a given post is saved) and focus on the consequences.

wp_insert_post(), called from my_first_callback() will once again trigger the save_post action, while we’re still in the middle of processing the first save_post action. So long as you avoid an infinite loop, there’s nothing necessarily wrong with that. But look closely inside do_action(), and you’ll find something else to worry about.

The $wp_filter array

WordPress stores all of your action (and filter) callbacks in the global $wp_filter array. This is a multidimensional array, with the hook names at the top level, the priority as the second level, and the callback at the third level. E.g., adding our callback above with add_action() is basically the same as:

$wp_filter['save_post'][10]['my_first_callback'] = array('function' => 'my_first_callback', 'accepted_args' => 2);

Inside do_action()

do_action('save_post') takes the $wp_filter['save_post'] array, sorts the priorities, then loops through each priority’s array of callback functions. Basically, a foreach loop nested inside of a foreach loop.

But the outer loop is not a PHP foreach loop. Instead, we manually progress through each priority using next(). Here’s the exact code in do_action():

do {
  foreach ( (array) current($wp_filter[$tag]) as $the_ )
    if ( !is_null($the_['function']) )
      call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
} while ( next($wp_filter[$tag]) !== false );

In many situations, this is functionally identical to a foreach loop, but in certain cases, it’s not.

Case 1: Adding callbacks while already looping through the hook

Let’s say that during your save_post callback function, you decide that you need to add another callback function with a later priority.

function my_first_callback( $post_id, $post ) {
  if ( $post->post_type == 'pistachio' ) {
    add_action('save_post', 'my_second_callback', 15, 2);
  }
}
function my_second_callback( $post_id, $post ) {
  // do something else
}
add_action('save_post', 'my_first_callback', 10, 2);

Due to the way do_action() is implemented, you can do this. my_second_callback() will be called at an appropriate(-ish) time (I’ll leave it as an exercise for the reader to figure out why it may not be in the exact order you might expect), because, by using next() instead of foreach, WordPress avoids making a copy of the $wp_filter['save_post'] array.

Case 2: Nested callbacks

Now lets go back to our original callback function, and give it a friend:

function my_first_callback( $post_id, $post ) {
  if ( $post->post_type == 'post' ) {
    wp_insert_post(array(
      'post_title' => 'A Post',
      'post_status' => 'publish',
      'post_type' => 'a_custom_post_type',
    ));
  }
}
function my_second_callback( $post_id, $post ) {
  // do something else
}
add_action('save_post', 'my_first_callback', 10, 2);
add_action('save_post', 'my_second_callback', 15, 2);

my_second_callback() will never be called if $post->post_type == 'post'. In fact, any callback with a later priority will not be called. How did that happen?

When my_first_callback() calls wp_insert_post(), we have, as mentioned above, some nesting going on with the save_post action. The inner call to do_action('save_post') cycles through the $wp_filter['save_post'] array until next() moves the pointer to the end of the array. After that loop is done, the outer call to do_action('save_post') doesn’t get its array pointer put back in the appropriate location. As far as it can tell, it’s looped through the entirety of the array and reached the end.

If do_action() used a foreach loop instead of the do-while construct with next(), it would make a copy of the $wp_filter['save_post'] array with its own pointer, and we wouldn’t have this problem, but then case 1 wouldn’t work. It looks like a conscious design decision, and I’m inclined to say the correct decision.

Making things right

So what do we do about that? Well, we can just avoid calling wp_insert_post() or wp_save_post() in our callbacks for the save_post hook. If you can avoid it, I highly recommend it. Sometimes, though, that’s not practical, so you have to take a different approach: put the pointer back.

If you know your callback will (or might) cause nesting of an action/filter, you need to figure out where the array pointer should be when you’re done, and put it there.

function my_first_callback( $post_id, $post ) {
  // track the current position of the array_pointer
  global $wp_filter;
  $wp_filter_index = key($wp_filter['save_post']);
  if ( $post->post_type == 'post' ) {
    wp_insert_post(array(
      'post_title' => 'A Post',
      'post_status' => 'publish',
      'post_type' => 'a_custom_post_type',
    ));
  }
  // put the pointer back
  reset($wp_filter['save_post']);
  foreach ( array_keys($wp_filter['save_post']) as $key ) {
    if ( $key == $wp_filter_index ) {
      break;
    }
    next($wp_filter['save_post']);
  }
}

At the moment, I’m happy to admit that this is not 100% robust. E.g., the array may have changed or been resorted since your function started. So you’re not guaranteed to return to the exact state you were in before your function was called. But you’re probably close enough, and much better off than if you hadn’t tried at all.

Creating the Page

First off, rather than the admin_menu hook, you’ll use the network_admin_menu hook to register your page. E.g.:

add_action('network_admin_menu', array($this, 'register_network_admin_pages'), 10, 0);

In your callback function, you don’t have the luxury of shortcut functions (e.g., add_options_page()) for registering your settings page, so you have to use add_submenu_page(), with 'settings.php' as your first argument. Alternatively, you can still use add_menu_page() to create a new menu section, just as you would with the single blog admin menu.

The WordPress settings API doesn’t entirely work on network admin pages, but you can still take advantage of the add_settings_section(), add_settings_field(), and do_settings_sections() functions to register and display your settings, if appropriate. But register_setting() is useless here.

The action attribute for your settings form should point to edit.php?action=Your_Unique_Action, for reasons we’ll soon discover.

Individual settings should be pulled from the network-wide site options table, using get_site_option().

Saving the Settings

Your settings form gets submitted to edit.php. To save your settings, you need to hook into the network_admin_edit_ACTION hook.

add_action('network_admin_edit_Your_Unique_Action, array($this, 'save_network_settings_page'), 10, 0);

Again, register_setting() doesn’t work on admin pages, so you’ll need to sanitize, validate, and save all your options yourself. Save the settings to the network-wide site options table using update_site_option().

After all your settings are saved, do a redirect back to your settings page. If you don’t WordPress will automatically redirect to the network dashboard.

wp_redirect(add_query_arg(array('page' => 'Your_Page_Slug', 'updated' => 'true'), network_admin_url('settings.php')));
exit();

What is a URL?

In WordPress, a URL indicates which posts to display. Your request is mapped to query variables (if you don’t have permalinks turned on, you’ll see these variables directly in your query string), and those variables are used to manipulate the database query in $wp_query->query(). It’s a very nice, consistent system: a URL equals one or more posts (or a 404 error). (NB. the admin section is a different beast entirely.)

With Drupal, a URL is an entry in the menu system. When Drupal sees the URL, it looks up the corresponding entry, and calls the function specified in that entry. That function is responsible for creating the contents of the page, be it a list of nodes, a form, flying monkeys, or what have you. You can use a module like Views to achieve results similar to WordPress, but you have a lot more power and flexibility to do something different with a given page.

Sometimes you want that power and flexibility in WordPress. You just want to say, “When a user visits this URL, call this function and display its output.” That’s not really the “WordPress way” of doing things, and it requires a fair amount of code to accomplish what seems to be a simple instruction.

Abstract the Details Away

So I went and wrote another WordPress plugin. WP Router abstracts away all the messy details of declaring a callback function for a URL in WordPress. One method call is all it takes to set up your path, your rewrite rules, your query variables, your access rules, your title, your template overrides. It reduces a few dozen action/filter callbacks to a small list of easy-to-understand arguments.

If you’ve every worked with Drupal’s menu system, you’ll find many of the arguments familiar, adapted, of course, for the WordPress framework. Read all about them in the usage notes, and check out the sample code included in the plugin.

Ongoing Development

Right now, this is at version 0.2, which is synonymous with “has all the features I thought to add initially, plus one more”. But I’m just one developer. What would make this plugin more useful to you? What doesn’t work like you expect it to? What part of the API is confusing? Please leave a comment here or create an issue in Github.

And if you’re interested in contributing, feel free to fork the project and send me updates. It’s hosted at Github, with released copied over to WordPress’s plugin repository. As usual with code I write, it’s licensed under the MIT License (i.e., do whatever you want with it, just mention where it came from).

$my_plugin = new My_Plugin();

in your main plugin file, and declare all your actions/filters in your class’s __construct() function, using something like:

add_filter('init', array($this, 'my_init_function'));

And then you go on to add your plugin’s JavaScript and CSS, register post types and taxonomies, look for query variables, etc.

I’m declaring that to be “wrong”, and I’m not going to do it anymore. Why? Because it’s not good objects-oriented design, and it seems to me that if you’re going to use objects, you should follow good object-oriented design patterns.

What problems come from the current practice?

1. Lack of coherency. The class is basically being used as a plugin namespace. It’s laudable to try to avoid polluting the global namespace with all your function names, but using a consistent, unique prefix for your functions accomplishes the same thing. Instead you end up with data and methods that look like they’re related to each other, but really have the most tenuous connection of being part of the same plugin.
2. Poorly implemented singletons. Every plugin class really needs to be a singleton. Having two instance of the class would cause a range or problems, from inefficiency (e.g., running the same query multiple times) to possible conflicts as the first instance of the plugin filters some data that is then re-filtered by the second instance. I’m not saying that singletons are inherently bad, but they are definitely overused (Wikipedia says so!, and, to quote the “Bible”, “Be suspicious of classes of which there is only one instance”), and when they are used, they should be used deliberately and with proper care taken to avoid multiple instances.
3. Barriers to code reuse and abstraction. Classes created this way can’t really be sub-classed (although I’ve yet to see a final keyword in front of a class), partially because of the singleton problem mentioned above, partially because there’s no clear definition of what the class is, so it doesn’t make sense to make a more specific version of it. This gets in the way of creating abstractions to share common code among similar classes, and greatly increases the complexity of any plugin of reasonable size.

What do we do about it?

I’ll be the first to admit that I don’t know all the answers. I’m playing with some solutions right now that seem to be working well, and I welcome any suggestions for improving on these ideas.

1. Distinguish between class members and instance members. PHP includes the static keyword, to let you declare a property or method to be a member of the class itself, rather then an instance of the class. This is the proper place for your configuration settings, registering post types, etc. Instead of instantiating the class to tell WordPress about this information, create a static init() function to call in your base plugin file. E.g., My_Class::init().
2. Use different classes for different things. Does your plugin create two separate post types? Create a class to declare each of them. Throw in some instance methods for interacting with your custom post meta.

Example

class My_Custom_Post_Type {
  const POST_TYPE_NAME = 'my_post_type';
  const IMPORTANT_META = 'my_important_meta';
  private $post_id;
 
  public static function init() {
    add_action('init', array(get_class(), 'register_post_type'));
  }
  public static function register_post_type() {
    $my_post_type_args = array(
      // some args go here
    );
    register_post_type(self::POST_TYPE_NAME, $my_post_type_args);
  }
  public function __construct( $post_id ) {
    $this->post_id = $post_id;
  }
  public function get_important_meta_field() {
    return get_post_meta($this->post_id, self::IMPORTANT_META, TRUE);
  }
}

This lets you abstract away the implementation (e.g., is it a custom post type or a custom table?) and just work with your new object’s well-defined interface. You can start doing things like creating sub-classes, using polymorphism, setting up factory objects to give you different types of objects depending on taxonomy terms, and all sorts of other concepts based on object-oriented design patterns. Basically, it lets us grow up and use the amazing advances in computer science and the discipline of coding that we’ve seen over the last several decades.

I would love to get some feedback on this. It’s a nascent idea that could use some better minds to help form it.

function my_init() {
  add_post_type_support('page', array('excerpt'));
}
add_action('init', 'my_init');

That’s all there is to it. Works with WordPress 3.0+.

Update 2010-10-01: Hey, look, I made it into a plugin.

I was building a website today that has a location-based search component. Basically, I have a collection of posts with addresses, and I need to be able to search for addresses within a given distance of a queried address, and sort them by said distance. To be honest, that’s hard to do with WordPress. But it is possible…

Step 1: Create a Table to Hold Coordinates

To start out, you need to add a database table to hold the coordinates for each address. So use register_activation_hook() to point to a function that adds your table:

  function my_activation_function() {
    global $wpdb;
    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
    foreach ( array('providers') as $table ) {
      $sql = "CREATE TABLE ".$wpdb->prefix."coordinates (
                pid bigint(20) unsigned NOT NULL,
                latitude double,
                longitude double,
                UNIQUE KEY pid (pid),
                INDEX latitude (latitude),
                INDEX longitude (longitude)
              ) /*!40100 DEFAULT CHARACTER SET utf8 */;";
      dbDelta($sql);
    }
  }

I’m using the Google Geocoding API to populate this table based on an address I enter when creating a post.

Step 2: Look for a Query Parameter

I’m going to look for a query parameter that I’ll designate as ll (short for “latitude/longitude”), so you can do a search with a URL like http://example.com/?ll=40.0,-85.7. We need to tell WordPress to look for this parameter, using the query_vars filter.

  function my_query_vars_filter( $array ) {
    $array[] = 'll';
    return $array;
  }

Pretty simple, no? That just tells WordPress to add ll to the WP_Query->query_vars array if it’s present in the URL.

Step 3: Modify the SQL Query

Now for the hard part: we need to tell WordPress to modify the SQL query it uses to select posts if this parameter is present. To do this, we’ll use a collection of filters: posts_fields, posts_join, posts_groupby, and posts_orderby.

First, we’ll use posts_fields to add a field to the SELECT statement. By default, the query returns wp_posts.*. We need to add a field for the distance from the given coordinates to each post’s coordinates. I’ll call that field distance.

  function posts_fields( $fields, $query ) {
    global $wpdb;
    if ( $query->query_vars['ll'] ) {
      list($lat, $lng) = explode(',', $query->query_vars['ll']);
      $fields .= sprintf(", ( 3959 * acos( cos( radians( %f ) ) * cos( radians( ".$wpdb->prefix."coordinates.latitude ) ) * cos( radians( ".$wpdb->prefix."coordinates.longitude ) - radians( %f ) ) + sin( radians( %f ) ) * sin( radians( ".$wpdb->prefix."coordinates.latitude ) ) ) ) AS distance", $lat, $lng, $lat);
    }
    return $fields;
  }

Without getting into the details of the math, this tells MySQL to calculate the distance between two sets of coordinates in miles (3,959 is the circumference of the earth in miles) and call the result distance.

posts_join adds a JOIN clause to the query, so we can link the posts table with our coordinates table.

  function posts_join( $join, $query ) {
    global $wpdb;
    if ( $query->query_vars['ll'] ) {
      $join .= " LEFT JOIN ".$wpdb->prefix."coordinates ON ".$wpdb->posts.".ID = ".$wpdb->prefix."coordinates.pid";
    }
    return $join;
  }

posts_groupby is used to limit to posts within a certain distance. It’s not strictly necessary, and you could conceivably add another query parameter to make this configurable.

  function posts_groupby( $groupby, $query ) {
    global $wpdb;
    if ( $query->query_vars['ll'] ) {
      $groupby .= $wpdb->posts.".ID HAVING distance < 100";
    }
    return $groupby;
  }

Finally, posts_orderby orders the results by distance (instead of the default post date).

  function posts_orderby( $orderby, $query ) {
    global $wpdb;
    if ( $query->query_vars['ll'] && $query->query_vars['post_type'] == 'provider' ) {
      $myorder = "distance ASC";
      if ( $orderby ) {
        $myorder .= ", ".$orderby;
      }
    }
    return $myorder?$myorder:$orderby; // return the default if we haven't changed it
  }

Notice that we need to prepend the value here, to override the default sort.

And there you have it. Quite a lot to go through, but the end result works exactly as intended.

You archives pages will use the default index.php template. If you want to use a different template, you’ll need to hook into the template_redirect action to specify your template file. I like to use a file name like type-MY_POST_TYPE.php (although that’s easily changed), using the function below.

function my_template_redirect() {
  if ( is_robots() || is_feed() || is_trackback() || is_single() ) {
    return; // run the default action
  }
  global $wp;
  $template = locate_template(array('type-'.$wp->query_vars['post_type'].'.php'));
  if ( $template ) {
    include($template);
    exit;
  }
}
add_action('template_redirect', 'my_template_redirect');

If you have an archive of article posts, WordPress will try to use type-article.php. If it doesn’t find the template file, it will fall back to index.php. You can add as many additional template names as you like to the array passed to locate_template().

For example, you can create an post type called article, and set the permalink for that post type to articles (i.e., an article will have a URL like http://example.com/articles/my-article-title).

Where do you go for a list of all articles, though? You might assume http://example.com/articles/, but you would be assuming erroneously. You could create a page with the slug articles and use a custom template for that page, but that doesn’t work with paging (e.g., http://example.com/articles/page/2/).

Instead, you need to fiddle with WordPress’s rewrite rules. (And thanks to Andrew Wilson for helping me understand this.)

Just after you call register_post_type() to define your custom post type, you’ll call another function, which I’ll call register_post_type_archives. It will take two arguments: the post type (i.e., the first argument to register_post_type), and the base path you’ll be using. So to create an archives page for the articles example above, you would call:

register_post_type_archives('article', 'articles');

What does the register_post_type_archives() function look like? Here you go:

function register_post_type_archives( $post_type, $base_path = '' ) {
  global $wp_rewrite;
  if ( !$base_path ) {
    $base_path = $post_type;
  }
  $rules = $wp_rewrite->generate_rewrite_rules($base_path);
  $rules[$base_path.'/?$'] = 'index.php?paged=1';
  foreach ( $rules as $regex=>$redirect ) {
    if ( strpos($redirect, 'attachment=') == FALSE ) {
      $redirect .= '&post_type='.$post_type;
      if (  0 < preg_match_all('@\$([0-9])@', $redirect, $matches) ) {
        for ( $i=0 ; $i < count($matches[0]) ; $i++ ) {
          $redirect = str_replace($matches[0][$i], '$matches['.$matches[1][$i].']', $redirect);
        }
      }
    }
    add_rewrite_rule($regex, $redirect, 'top');
  }
}

Here, we use $wp_rewrite->generate_rewrite_rules($base_path); to create a default set of rules, and add the case where there are no arguments besides the base path. Then we append the post_type query parameter to each rule. Finally, replace each reference in the redirect (e.g., $1) with the string $matches[1] (or the corresponding number).

Now you have a listing of articles at http://example.com/articles/. You can add other query parameters after that, too. For example, http://example.com/articles/?s=penguin to search articles. ]]> http://xplus3.net/2010/08/08/archives-for-custom-post-types-in-wordpress/feed/ 3 http://xplus3.net/2010/05/20/wp3-custom-post-type-permalinks/ http://xplus3.net/2010/05/20/wp3-custom-post-type-permalinks/#comments Thu, 20 May 2010 20:23:19 +0000 Jonathan Brinley http://xplus3.net/?p=275 Continue reading →]]> Update 2010-10-04: See Understanding Rewrite Tags for a somewhat more helpful treatment of the subject.

I’ve been playing around with WordPress 3.0 to create a bug/issue-tracking plugin (i.e., using WP to track bugs, not to track WP bugs (although it could conceivably do that)). More details about the plugin will be forthcoming, but now is as good a time as any to share the solution to one problem I came across.

Creating New Post Types and Taxonomies

When you create a new post type, you use the register_post_type function. When you create a new post type through that function, WP creates a new rewrite rule base on the name you give the post type. In my case, I’ve created an issue post type, so all issues, by default, will have the permalink /issue/%issue%/ (where %issue% is replaced with the post slug). Using the rewrite argument to register_post_type, you can change the beginning of the permalink to something different (e.g., /bugs/%issue%/) should you so desire.

Here’s the full function call I’m using (I’m not guaranteeing that everything here is correct or necessary, but it seems to be working):

register_post_type( 'issue', array(
  'label' => 'Issues',
  'singular_label' => 'Issue',
  'description' => 'A bug to fix, task to complete, or anything else that need to be done',
  'public' => TRUE,
  'publicly_queryable' => TRUE,
  'show_ui' => TRUE,
  'query_var' => TRUE,
  'rewrite' => TRUE,
  'capability_type' => 'post',
  'hierarchical' => FALSE,
  'menu_position' => NULL,
  'supports' => array('title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments', 'custom-fields', 'revisions'),
  'menu_position' => 5,
  'rewrite' => array(
    'slug' => 'issue',
    'with_front' => FALSE,
  ),
));

Similarly, you can create a custom taxonomy. In this case, I’ve created a taxonomy for projects, so issues can be assigned to projects. Much like a normal category will have a URL like /category/%category%/, my issue_project taxonomy has URLs matching /issue_project/%issue_project%/, which gives you a page with all issues matching the given project name. You can, once again, use the rewrite argument to give a different path (in my case, I’ve used /project/%issue_project%/).

Here’s the function call for the taxonomy (same caveats as above):

register_taxonomy('issue_project', 'issue', array(
  'label' => 'Projects',
  'singular_label' => 'Project',
  'public' => TRUE,
  'show_tagcloud' => FALSE,
  'hierarchical' => TRUE,
  'query_var' => TRUE,
  'rewrite' => array(
    'slug' => 'project'
  ),
));

Putting Things Together

Now, what if you want to combine these, to show the hierarchy in your URLs (e.g., /project/my-project/issue/horrible-bug/)?

I first attempted to change the slug of the issue post type to project/%issue_project%/issue. That didn’t work. I had URLs that looked like /project/%issue_project%/issue/horrible-bug/; %issue_project% wasn’t being replaced. So I scrapped that idea.

I dug around for a while and found the post_type_link filter. Using that, I could add the project URL to the front of the issue URL when WP was building the permalink for an issue. That gave me the correct URLs, but they would 404.

So I dug around some more through the WP_Rewrite class and realized that I had been wasting a lot of time when I already had the solution: do both.

1. Change the slug argument to register_post_type to project/%issue_project%/issue
2. Hook into the post_type_link filter with a callback that replaces %issue_project% with the appropriate project slug.

Let’s say you want more control over your image thumbnails, or you would like to have thumbnails attached to your other uploads. You would need to install a plugin like the Custom Thumbnails plugin I just wrote.

What it does

WordPress associates each upload with a post or a page, using the item’s post_parent attribute. This plugin adds a field to the editing screen for your upload, allowing you to associate it with a “Parent Item”. Once thus associated, any time WordPress requests the thumbnail image of the parent item, it will retrieve the thumbnail image you uploaded, instead.

How it works

Writing this plugin took me much farther into the bowels of WordPress than I had reached before. As it turns out, I needed to use four completely undocumented filters to achieve the effect I wanted.

attachment_fields_to_edit

The first step is to add the fields you want edit for your uploads. WordPress uses the function get_attachment_fields_to_edit to build the form fields. You can use the filter attachment_fields_to_edit to add or remove fields from this form. Your filter function needs to take two arguments, so add your filter using:

add_filter('attachment_fields_to_edit', 'custom_thumbnail_fields_to_edit', 11, 2);

The first argument is an associative array of form fields ($form_fields in the following code), the second is the attachment object we are currently editing ($post, since WordPress attachment objects are the same as post objects).

Fields for images

We add a select box to the form for image uploads. This select box will have a list of all other media files. So first we query the database for the list of files:

$attachments = get_children( array(
  'post_type' => 'attachment',
  'order' => 'ASC',
  'orderby' => 'post_title',
  'exclude' => $post->ID
) );

Next we start to build the HTML for our select box:

$name = "attachments[$post->ID][post_parent]";
$html = "<select id='$name' name='$name'>";
$html .= "<option value='0'></option>";
foreach ( $attachments as $attachment ) {
  $parent = get_post($attachment->post_parent);
  if ( $parent && $parent->post_type == 'attachment' ) { continue; }
  if ( $attachment->ID == $post->post_parent ) {
    $selected = " selected='selected'";
  } else {
    $selected = '';
  }
  $html .= "<option value='$attachment->ID'$selected>";
  $option_text = array( $attachment->post_title, ' ('.basename($attachment->guid).')');
  if ( strlen($option_text[1]) > 62 ) {
    $option_text[0] = '...';
  } elseif ( strlen($option_text[0].$option_text[1]) > 65 ) {
    $option_text[0] = substr($option_text[0], 0, 62-strlen($option_text[1])).'...';
  }
  $html .= $option_text[0].$option_text[1];
  $html .= "</option>";
}
$html .= "</select>";

We create an empty option, then an option for each media item, with its ID as the value. I limited the text of the option to 65 characters so it doesn’t overflow the item editing box.

Finally, we add our new field to the $form_fields array:

$form_fields['post_parent'] = array(
  'label' => __("Parent Item"),
  'value' => '',
  'input' => 'select',
  'select' => $html,
  'helps' => __("If this is a thumbnail for another image, choose that image here.")
);

The array keys are somewhat self-explanatory. label is the label, value is the default value, input can be one of text, textarea, or any arbitrary string. If you use an arbitrary string, you’ll use that string as a key for the HTML that will be printed for the form field (in this case, select). helps contains helpful text you want to include along with the field.

Fields for other media

Other media items cannot serve as thumbnails, so they don’t need the “Parent Item” field. They do, though, need the same options as images have for inserting your items into your post, including options to align the image and to display the thumbnail.

I copied the “Alignment” field directly from the image_attachment_fields_to_edit function that adds the field to image items. The “Display” field took a bit of editing from the “Size” field in image_attachment_fields_to_edit. First, we see if the item has a thumbnail image, using a function we’ll define later:

$thumb = custom_thumbnail_image_downsize(false, $post->ID, 'thumbnail');

Then we add the radio buttons to choose among the thumbnail (if it exists), the text from the “Title” field, or the media icon. (“Media icon?”, you ask. Yes, WordPress comes with nine icons for representing various kinds of media files (e.g., audio, video, spreadsheets, documents, etc.). It doesn’t give you any easy way to use these icons anywhere except on the Media Library page.)

Finally, return $form_fields and close the function.

attachment_fields_to_save

We now need to save date from our new form field when we save our images. We can use the attachment_fields_to_save filter hook to make sure our field is saved.

The attachment_fields_to_save filter function takes two arguments: the first is an associative array of data that will be saved (called $post); the latter is an associative array of the data that was submitted ($attachment$post['post_parent'] to the value of $attachment['post_parent'], using a series of if statements. In the event that we do change the post_parent of the item, assigning it as the thumbnail of another item, we need to make sure to unset the post_parent of the current thumbnail, if there is one.

$children = get_children( array(
  'post_parent' => $attachment['post_parent'],
  'post_type' => 'attachment',
  'post_mime_type' => 'image'
) );
if ( $children ) {
  $old_attachment = current($children);
  wp_update_post( array(
    'ID' => $old_attachment->ID,
    'post_parent' => 0
  ) );
}

If $attachment['post_parent'] is set to ’0′, we need determine if the file was previously set as a thumbnail to another item and is now being removed, or if it is an attachment to a post/page and should remain as such.

$parent = get_post( $post['post_parent'] );
if ( $parent->post_type != 'attachment' ) {
  return $post;
}

Finally, change $post['post_parent'] if necessary:

$post['post_parent'] = $attachment['post_parent'];

And return the final version of $post.

image_downsize

Now that we have a way to record and store our associations, it’s time to tell WordPress to do something useful with that information.

When creating the <img> element for an image, WordPress calls the function wp_get_attachment_image, which, in turn, gets it src attribute from the function wp_get_attachment_image_src. These functions take a $size argument, which can be one of “thumbnail”, “medium”, or “full”, or an array containing the width and height of the image you want. This and the attachment ID get passed to the function image_downsize to see if there is a smaller version of the image to meet your size criteria.

This is where WordPress finally gives us a hook to latch onto. The image_downsize function calls the image_downsize filter. The filter function needs to take three arguments. The first seems to be deprecated (with no documentation and only one occurrence, it’s hard to say what it’s supposed to do), and can be safely ignored, in any case. The attachment ID and size fill out the remaining arguments. The filter should return an array containing the URL for the image, its width, and its height.

Since this plugin is only dealing with thumbnail images, we don’t want to change anything if the $size argument is something other than “thumbnail”. We have the option of returning false if the filter doesn’t need to do anything.

if ( $size != 'thumbnail' ) { return false; }

Now we can see if our item has any images attached to it:

$attachments = get_children( array(
  'post_parent' => $id,
  'post_type' => 'attachment',
  'post_mime_type' => 'image'
  )
);

If so, we can call wp_get_attachment_url to get the URL for the first attached image, returning false if there are no attached thumbnails.

if ( $attachments ) {
  return array( wp_get_attachment_url(key($attachments)), '', '' );
} else {
  return false;
}

You may notice that I didn’t return aything for the width and height of the image. These really aren’t necessary, as they are just used to set the deprecated width and height attributes for the <img> tag. By returning empty strings, we ensure that those attributes are not created.

If you recall from the discussion earlier from the custom_thumbnail_fields_to_edit function, we use the custom_thumbnail_image_downsize function to see if non-image attachments have a thumbnail image.

$thumb = custom_thumbnail_image_downsize(false, $post->ID, 'thumbnail');

If you’re really doing your homework, you might have noticed that I used this in place of

$thumb = wp_get_attachment_thumb_url($post->ID);

which is used for the same purpose in the image_attachment_fields_to_edit function. Why the difference? wp_get_attachment_thumb_url calls image_downsize. Unfortunately, image_downsize uses wp_attachment_is_image to see if your attachment is an image before it will look for a thumbnail version and before it calls the image_downsize filter. That means that it won’t look for a thumbnail for non-image uploads. We have to bypass that and go straight to our filter function to see if our attachments have thumbnails. Simply rearranging a few lines of code would fix this issue, and I’ll be requesting that the WordPress developers do just that.

media_send_to_editor

Our last function handles the job of creating the HTML to send back to the editor when the user clicks the “Insert into Post” button. This filter takes three arguments: $html, the HTML created by the built-in functions and any other functions attached to this filter; $attachment_id, the ID of the item being inserted; and $attachment, the associative array that was posted when you clicked the “Insert into Post” button. The function should return the HTML that should be sent to the editor.

After checking that our item is not an image (since WordPress can handle images on its own), we look at $attachment to see what options the user chose. The value of $attachment['media-display'] will determine the path our code takes. If the user chose “thumbnail”, we get the child images of the item:

$thumbnails = get_children( array(
  'post_parent' => $attachment_id,
  'post_type' => 'attachment',
  'post_mime_type' => 'image'
  )
);

If it has a thumbnail, we get an <img> tag for the thumbnail image and put it into the $html variable:

$html = get_image_tag(key($thumbnails), $attachment['post_excerpt'], $attachment['post_title'], $align, $size);

It the user chose “icon”, or if the thumbnail disappeared for some reason before the user submitted the form, we get an <img> tag for the appropriate icon:

$html = wp_get_attachment_image($attachment_id, 'thumbnail', true);

The third argument to wp_get_attachment_image tells it to return an icon.

If the user chose “text”, then we can just let WordPress handle it like it normally would by returning $html unchanged.

Next we wrap the <img> in a link:

$url = $attachment['url'];
if ( $url == get_attachment_link($attachment_id) ) {
  $rel = ' rel="attachment wp-att-'.attribute_escape($id).'"';
} else {
  $rel = '';
}
if ( $url ) {
  $html = '<a href="' . clean_url($url) . "\"$rel>$html</a>";
}

Finally, we let any other filters (e.g., to create captions or align the image) run on $html before we return it:

$html = apply_filters( 'image_send_to_editor', $html, $attachment_id, $attachment['post_excerpt'], $attachment['post_title'], $align, $url );

At long last, we’re done. Once again, the Custom Thumbnails plugin is available from the WordPress Plugin Directory if you would like to use it or see the full code.