-
-
Notifications
You must be signed in to change notification settings - Fork 97
Admin columns
The admin_cols argument allows you to declare various table columns for the post type listing screen without having to deal with WordPress' long-winded actions and filters for list table columns.
Extended CPTs provides built-in columns which display post meta fields, taxonomy terms, featured images, post fields, Posts 2 Posts connections, and custom callback functions. Column sorting is handled where appropriate (for post meta, taxonomy terms, and post fields), and output is escaped for safety.
- Example
- Available column types
- Restricting Visibility by User Capability
- Default Sort Column
- Column Titles
- Optional Parameters
register_extended_post_type( 'article', array(
'admin_cols' => array(
// A featured image column:
'featured_image' => array(
'title' => 'Illustration',
'featured_image' => 'thumbnail'
),
// The default Title column:
'title',
// A meta field column:
'published' => array(
'title' => 'Published',
'meta_key' => 'published_date',
'date_format' => 'd/m/Y'
),
// A taxonomy terms column:
'genre' => array(
'taxonomy' => 'genre'
),
),
) );Display the value of a meta field by using the meta_key parameter:
'foo' => array(
'title' => 'Foo',
'meta_key' => 'foo',
),If the meta field represents a Unix or MySQL timestamp, you can format the output as such using the date_format parameter. The value gets passed to PHP's date() function, so any standard date format is accepted.
'start_date' => array(
'title' => 'Start Date',
'meta_key' => 'start_date',
'date_format' => 'D, d M Y',
),Display a taxonomy's terms by using the taxonomy parameter:
'genre' => array(
'title' => 'Genre',
'taxonomy' => 'genre',
),Multiple terms will be comma separated.
You can control where each term links to with the link parameter, which accepts view, edit, or list as its value.
'genre' => array(
'title' => 'Genre',
'taxonomy' => 'genre',
'link' => 'edit',
),view links to the term archive on the front end.
edit links to the edit screen for the term.
list links to the post type list screen for that term.
Output the post's featured image at the size specified by using the featured_image parameter:
'illustration' => array(
'title' => 'Illustration',
'featured_image' => 'thumbnail',
),If necessary, you can set the image's width and/or height in pixels if you need to scale down the image in the browser.
'illustration' => array(
'title' => 'Illustration',
'featured_image' => 'thumbnail',
'width' => 80,
'height' => 80,
),Any of the standard post fields (in the wp_posts table) can be output by using the post_field parameter:
'last_modified' => array(
'title' => 'Last Modified',
'post_field' => 'post_modified',
),Date fields (post_date, post_date_gmt, post_modified, and post_modified_gmt) will be formatted as dates. Other fields will also be formatted where appropriate.
Posts 2 Posts connections can be output using the connection parameter:
'my_connection' => array(
'title' => 'Connected Posts',
'connection' => 'my_connection',
),You can even specify a connection field and value to display connections with the corresponding field and value:
'my_connection' => array(
'connection' => 'my_connection',
'field' => 'person',
'value' => 'john',
),You can control where each connection links to with the link parameter, which accepts view, edit, or list as its value.
'my_connection' => array(
'title' => 'Connected Posts',
'connection' => 'my_connection',
'link' => 'list',
),view links to the connected post permalink.
edit links to the edit screen for the connected post.
list links to the post type list screen for the connection.
If you don't want to use one of Extended CPT's built-in column types, you can use a callback function to output your column value by using the function parameter. Anything callable can be passed as the value, such as a function name or a closure.
'my_column' => array(
'title' => 'Hello World',
'function' => function() {
echo 'Hello, World!';
},
),'my_column' => array(
'title' => 'Hello World',
'function' => 'my_custom_function',
),For post types: Note that the function does not get passed any parameters, so it must use the global $post object.
For taxonomies: The function is passed the term ID as its first parameter.
Any column can be restricted so it's only shown to users with a given capability by using the cap parameter:
'my_column' => array(
'title' => 'Admin-Only Column',
'meta_key' => 'foo',
'cap' => 'manage_options',
),Additionally, just the output of any column can be restricted so it's only shown to users with a given capability for the current row's post by using the post_cap parameter. The column will be shown to all users, but the value for each row will only be shown to users with the capability when applied to the row's post.
'my_column' => array(
'title' => 'Editor-Only Column',
'meta_key' => 'foo',
'post_cap' => 'edit_post',
),Any column can be made the default sort column (instead of the default Title column) by using the default parameter and giving it a value of ASC or DESC:
'start_date' => array(
'title' => 'Start Date',
'meta_key' => 'start_date',
'default' => 'DESC',
),The title parameter is optional for any column. If omitted, a title will be generated based on the meta key, taxonomy name, post field, connection name, or connection value as appropriate.
The title_icon parameter allows you to specify a name of a Dashicon to use as the column title. Example:
'admin_cols' => [
'expires' => [
'title_icon' => 'dashicons-calendar-alt',
'meta_key' => 'expiry_date',
'date_format' => 'd/m/Y',
],
],The title_cb parameter allows you to specify a callback function which generates the column title. Use this for complex requirements or if you need the title to include HTML. Example:
'admin_cols' => [
'expires' => [
'title_cb' => function() {
return '<b>Amazing</b> Field';
},
'meta_key' => 'expiry_date',
],
],The sortable parameter can be used (with a value of boolean false) to prevent a column from being sortable, if it normally is.