Modifying Administration Tables

Define Your Custom Column

To add a custom column, you must first add its name to the array of column header names. This is done by hooking into the 'manage_{$screen->id}_columns' filter. Your callback is passed the current name array. Simply add another key/value pair to the array and return the entire array. The key can be any arbitrary unique string and the value is the actual column name that will appear in the table header. The following example defines a 'Metabox' column to be added to a 'portfolio' custom post type table.

function bcw_cpt_columns($columns) { 
 $columns["metabox"] = "Metabox"; 
 return $columns; 
} 
add_filter('manage_edit-portfolio_columns', 'bcw_cpt_columns'); 

Sortable Columns

You can only sort columns that contain data from the database related to the table objects, as the sort is achieved by re-querying the table contents. If your data cannot be related to the table objects in a mySQL query, then it cannot be used for sorting of your column.

After defining your column you can make it sortable by hooking the sortable filter variant 'manage_{$screen->id}_sortable_columns' and adding your column name to that array as well. This can often be the same callback as the one for adding the initial non-sortable column.

function bcw_cpt_columns($columns) { 
 $columns["metabox"] = "Metabox"; 
 return $columns; 
} 
add_filter('manage_edit-portfolio_columns', 'bcw_cpt_columns'); 
add_filter('manage_edit-portfolio_sortable_columns', 'bcw_cpt_columns');

You then hook the 'request' filter and check the passed query variables array for your column name under the 'orderby' key. If found, set query arguments that can be used to query the table contents in the correct order (typically the orderby column) and merge into the passed variables. Clicking the column head will toggle the query order between ASC and DESC.

The query arguments you set are the same arguments you define in a custom new WP_Query object. You essentially define an arguments array as if for a new query object and merge it with the array passed by the 'request' filter. The 'request' filter is initiated from the parse_request() method of the WP class. It is defined in wp-includes/class-wp.php. Your callback is passed $this->query_vars.

function bcw_sort_metabox($vars) { 
 if(array_key_exists('orderby', $vars)) { 
  if('Metabox' == $vars['orderby']) { 
   $vars['orderby'] = 'meta_value'; 
   $vars['meta_key'] = '_my_meta_value_key'; 
  } 
 } 
 return $vars; 
} 
add_filter('request', 'bcw_sort_metabox');

Horizontally Reordering Columns

By default, the column order is predefined. So when you add your custom column, it appears at the end of the list at the far right edge of the table. If you want your column to appear elsewhere, or simply wish to rearrange the order of default columns, while you are hooked into the 'manage_{$screen->id}_columns' filter, instead of working with the array passed, copy the elements in the desired order into a new array. Return this new array and it's order will be used instead of the default. The following example moves our Metabox column to appear before the Date column. As it only involves the last column, instead of redefining the entire array, we leave the first part alone and only unset then reset the date column we want to move to the end. You can var_dump($columns) to see the key names used for each column.

function bcw_cpt_columns($columns) { 
 $date = $columns['date'];
 unset $columns['date'];
 $columns['metabox'] = 'Metabox'; 
 $columns['date'] = $date;
 return $columns; 
} 
add_filter('manage_edit-portfolio_columns', 'bcw_cpt_columns');