Actions and Filters
There are a number of filters provided in Posts Table Pro which allow you to customize the behavior of the plugin.
Please note that this article is aimed at developers. If you don't know how to use this code then you should ask your developer.
Filters
Language filters
There are various filters provided for manipulating text strings and messages used in the plugin. Please refer to this article for filters to override the text strings.
posts_table_minimum_search_term_length
Sets the minimum search term length (number of characters) which is considered a valid search term in the search box above the table. Below this number of characters, a search is not performed.
This filter only applies when lazy load is enabled.
Arguments/return
int - The minimum number of characters for a valid search term. Defaults to 2 characters.
add_filter( 'posts_table_minimum_search_term_length', function( $length ) {
return 5;
} );posts_table_search_filter_get_terms_args
This filter modifies the arguments passed to get_terms() when building the dropdown search filters.
Arguments
array - An array of args to pass to get_terms.
string - The taxonomy for the dropdown filter
Barn2\Plugin\Posts_Table_Pro\Posts_Table_Args - The posts table args object for the current table.
Return
array- an array of args.
add_filter( 'posts_table_search_filter_get_terms_args', function( $args, $taxonomy, $table_args ) {
// Change the orderby to 'menu_order'
$args['orderby'] = 'menu_order';
return $args;
}, 10, 3 );posts_table_search_filter_terms_<taxonomy>
This filter allows you to modify the items displayed in the dropdown search filters that appear above the table.
The filter name is dynamic, so replace the <taxonomy> portion of the filter with the taxonomy slug that you want to modify.
- For the
categoriesdropdown, use this filter:posts_table_search_filter_terms_category - For the
tagsdropdown, use this filter:posts_table_search_filter_terms_tags - For any custom taxonomy dropdown, use the taxonomy slug. For example, if your taxonomy is called
city, the filter would be:posts_table_search_filter_terms_city.
Arguments
WP_Term[] - An array of WP_Term objects to be included in the dropdown list.
Barn2\Plugin\Posts_Table_Pro\Posts_Table_Args - The posts table args object for the current table.
Return
WP_Term[]- an array of term objects.
add_filter( 'posts_table_search_filter_terms_category', function( $terms, $table_args ) {
// Remove the 'hampshire' term from the category dropdown.
foreach ( $terms as $i => $term ) {
if ( 'hampshire' === $term->slug ) {
unset( $terms[$i] );
}
}
return $terms;
}, 10, 2 );posts_table_data_filters
This filter will modify all dropdown search filters at once. Returns an array of arrays, with the column used as the top-level array key.
Arguments
array - An array of arrays for the search filters to display. Each array has the following keys: heading, taxonomy, terms.
Barn2\Plugin\Posts_Table_Pro\Posts_Table_Args - The posts table args object for the current table.
Return
array- an array of arrays.
add_filter( 'posts_table_data_filters', function( $filters, $table_args ) {
// Do something with the filters, e.g:
$filters['categories']['heading'] = 'Choose a category';
return $filters;
}, 10, 2 );posts_table_data_config
Filters which allows you to override the inline table configuration used when the DataTables script is initialised. You can use this filter, for example, to disable or enable certain table features. The following example disables the ordering/sorting feature in all tables.
Arguments
array - The table config array. This is passed to jQuery DataTables to initialize the posts table.
Barn2\Plugin\Posts_Table_Pro\Posts_Table_Args - The posts table args object for the current table.
Return
array- the config array.
// Disable column sorting
add_filter( 'posts_table_data_config', function( $config, $table_args ) {
$config['ordering'] = false;
return $config;
}, 10, 2 );posts_table_open_posts_in_new_tab
Posts tables contain various links to the single post page, depending on the links option. For example, the name and button columns are normally formatted as a link to the post.
These links will open in the same tab by default. To open them in a new tab use the posts_table_open_posts_in_new_tab filter and return true.
Arguments/return
bool - Whether to open posts in a new tab from the table. Default false.
add_filter( 'posts_table_open_posts_in_new_tab', '__return_true' );posts_table_process_shortcodes
By default, the plugin will strip shortcodes from the post content so any content that would appear inside these shortcodes will not appear in the table. You can enable shortcodes on a per-table basis using the shortcodes option, but if you want to enable them globally, return true from this filter.
Arguments/return
bool - Whether to process shortcodes in the table. Default false.
add_filter( 'posts_table_process_shortcodes', '__return_true' );posts_table_run_in_search
Use to filter decide if posts tables should be displayed in the standard search results page (i.e. in the post excerpt or content that is displayed in the search results).
Normally, you would want to prevent the shortcode running within the search results, as only a snippet or excerpt of each page or post is shown in the search results. However, if you want to enable posts tables in the search results, set this filter true.
Arguments/return
bool - Whether to display posts tables in the post excerpts shown on the search results page. Default false.
add_filter( 'posts_table_run_in_search', '__return_true' );posts_table_data_<column>
This filter allows you to modify the data for each column in the table (apart from custom taxonomies and custom fields - see below for these). It allows you to modify the HTML for each column before it is added to the table.
There is a filter available for each column in the table, in the form posts_table_data_<column>. The filter name is dynamic, so replace the <column> portion with the column that you want to modify, for example, posts_table_data_title.
For example, to modify data for the image column you would use the posts_table_data_image filter like this:
add_filter( 'posts_table_data_image', function( $image, $post ) {
// Wrap the image in an extra div.
return '<div class="foo">' . $image . '</div>';
}, 10, 2 );The list of available data filters for each column are:
- ID:
posts_table_data_id - Title:
posts_table_data_title - Categories:
posts_table_data_categories - Tags:
posts_table_data_tags - Author:
posts_table_data_author - Date:
posts_table_data_date - Modified date:
posts_table_data_date_modified - Image:
posts_table_data_image - Content:
posts_table_data_content - Excerpt:
posts_table_data_excerpt - Status:
posts_table_data_status - Button column:
posts_table_data_button
Note: custom taxonomy and custom field columns use a slightly different format. See the following sections for details.
Arguments
string - The HTML data for the column to add to the table.
WP_Post - The current post object.
Return
string- the HTML data.
posts_table_data_custom_taxonomy_<taxonomy>
This filter allows you to modify the value of the data in a custom taxonomy column. The filter name is dynamic, so replace the <taxonomy> portion of the filter with the taxonomy slug that you want to modify. For example, if your taxonomy is called city, the filter would be posts_table_data_custom_taxonomy_city.
The filter accepts two arguments: the list of $terms for this post as a comma-separated string, and the current WP_Post object.
Here's an example to add an extra city to list of cities for each post in our city taxonomy column:
add_filter( 'posts_table_data_custom_taxonomy_city', function( $terms, $post ) {
// Append an extra city to the list of 'city' terms.
$terms .= ', ' . 'London';
return $terms;
}, 10, 2 );Arguments
string - The formatted list of terms for the taxonomy column.
WP_Post - The current post object.
Return
string- the list of terms.
posts_table_data_custom_field
Filter which allows you to override the value of all custom fields in the table. It accepts 3 arguments – the custom field value, the custom field name and the current post object.
// Override the 'extra_notes' custom field
add_filter( 'posts_table_data_custom_field', function( $value, $field, $post ) {
if ( 'extra_notes' === $field ) {
// do something with $value
}
return $value;
}, 10, 3 );Arguments
string - The custom field value.
string - The custom field
WP_Post - The current post object.
Return
string- the list of terms.
posts_table_data_custom_field_<field>
This filter allows you to modify the value of a custom field column, prior to it being added to the table. The <field> portion of the filter is dynanic and should be replaced by the custom field key.
// Override the 'extra_notes' custom field
add_filter( 'posts_table_data_custom_field_extra_notes', function( $value, $post ) {
// do something with $value
return $value;
}, 10, 2 );Arguments
string - The custom field value.
WP_Post - The current post object.
Return
string- the custom field value.
posts_table_url_custom_field_link
Use this filter to override the link used for a URL custom field. This filter is applied only for valid URLs (beginning http:// or https://).
add_filter( 'posts_table_url_custom_field_link', function( $url, $field, $post ) {
// do something with $url...
return $url;
}, 10, 3 );Arguments
string - The custom field URL.
string - The custom field key.
WP_Post - The current post object.
Return
string- the custom field URL.
posts_table_url_custom_field_text
Use this filter to override the anchor link text displayed for a URL custom field. This filter is applied only when the field value is a valid URL (beginning http:// or https://).
add_filter( 'posts_table_url_custom_field_text', function( $anchor_text, $field, $post ) {
// do something with $anchor_text
return $anchor_text;
}, 10, 3 );Arguments
string - The custom field anchor text.
string - The custom field key.
WP_Post - The current post object.
Return
string- the custom field anchor text.
posts_table_custom_field_stored_date_format
If you are using date-based custom fields in your table, you may find that your dates are sometimes incorrectly sorted or formatted. The most likely cause of this is the date conversion functions used by the plugin which are built into PHP.
For example, dates such as “12/04/2018” are assumed to be in U.S. format with the month first. So this example date would be December 4th, 2018.
If the date is separated by dash (-), dot (.) or other symbol, it’s assumed to be a European/Australian date with the day before the month. If you’re using dates separated by a forward slash but in this format: d/m/Y, the plugin will not be able to sort these correctly, or format them if you’re using the date_format option. To fix this, you will need to set this filter.
Note: this is not related to how the custom field is actually displayed in the table - see the date_format option for controlling the date output.
add_filter( 'posts_table_custom_field_stored_date_format', function( $format, $field ) {
if ( 'despatch_date' === $field ) {
return 'd/m/Y';
}
return '';
}, 10, 2 );
posts_table_custom_field_is_eu_au_date
Use this filter to specify that a custom field in your table should be treated as a date in EU/AU format (i.e. day before month). This is an alternative to the above filter - posts_table_custom_field_stored_date_format - which requires you specify the exact format your date is stored in. This filter instead requires a boolean true or false to indicate whether to treat the field as an EU/AU date.
The can be applied globally to all date-based custom fields, as follows:
add_filter( 'posts_table_custom_field_is_eu_au_date', '__return_true' );
Or you can use it for individual custom fields:
add_filter( 'posts_table_custom_field_is_eu_au_date', function( $is_eu_date, $field ) {
if ( 'event_date' === $field ) {
return true;
}
return false;
}, 10, 2 );posts_table_taxonomy_is_eu_au_date
Use this filter to specify that a custom taxonomy column in your table should be treated as a date in EU/AU format (i.e. day before month). This can be applied globally to all date-based taxonomies as follows:
add_filter( 'posts_table_taxonomy_is_eu_au_date', '__return_true' );
Or you can use it for individual taxonomies:
add_filter( 'posts_table_taxonomy_is_eu_au_date', function( $is_eu_date, $tax ) {
if ( 'event_date' === $tax ) {
return true;
}
return false;
}, 10, 2 );
posts_table_acf_value
Filters which allows you to override the custom field values returned from Advanced Custom Fields. It accepts 3 arguments – the custom field value, the ACF field object and the current post ID.
add_filter( 'posts_table_acf_value', function( $value, $field_obj, $post_id ) {
if ( 'file' === $field_obj['type'] ) {
// do something with $value
}
return $value;
}, 10, 3 );posts_table_button_column_button_text
Filter the text used for the button element when using the button column in the table. The text is set via the Plugin Settings page or the button_text shortcode option. You can use this filter to add more complex formatting around the text.
add_filter( 'posts_table_button_column_button_text', function( $text ) {
return '<span>' . $text . '</span>';
} );posts_table_button_column_button_class
Filter the CSS class for the button element when using the button column in the table. Defaults to: button btn posts-table-button
add_filter( 'posts_table_button_column_button_class', function( $class ) {
return $class . ' custom-btn';
} );posts_table_more_content_text
Filter which controls the text/HTML appended when data in the content or excerpt columns is truncated. Defaults to ….
add_filter( 'posts_table_more_content_text', function( $more_text ) {
return ' [...]';
} );posts_table_separator_<type>
Filter which allows you to change the separator used between categories, tags, terms and custom fields. For example, a post can have multiple categories, each separated by a comma. This filter allows you to change the comma for a different character, line breaks, or other custom HTML.
The filter must include the relevant type. Possible values for type are: categories, tags, terms, custom_field, and custom_field_row.
For example, to change the separator between categories in the table, add this filter:
add_filter( 'posts_table_separator_categories', function( $sep ) {
return '<br/>';
} );posts_table_custom_class
Use this filter to add additional CSS classes to the posts table's <table> element. Type: string
add_filter( 'posts_table_custom_class', function( $class ) {
return 'feature-table';
} );posts_table_row_class
Use this filter to add extra CSS classes to each row in the table, or selectively based on the current post. Type: array
add_filter( 'posts_table_row_class', function( $class, WP_Post $post ) {
if ( 23 === $post->ID ) {
$class[] = 'featured';
}
return $class;
}, 10, 2 );posts_table_row_attributes
Use this filter to add extra attributes (e.g. data attributes) to the <tr> element in the table. Should return an array of attribute pairs in the format key => value.
add_filter( 'posts_table_row_attributes', function( $attributes, $post ) {
$attributes['data-foo'] = 'bar';
return $attributes;
}, 10, 2 );posts_table_column_class_<column>
This filter allows you to add additional CSS classes to columns (i.e. the <td> cells) in the table. Replace <column> with the column that you want to add the class to. You may add additional classes, but do not remove any from the list passed in, as it may affect the operation of the table.
add_filter( 'posts_table_column_class_title', function( $classes ) {
$classes[] = 'highlight';
return $classes;
} );posts_table_column_heading_<column>
Filter which allows you to override a column heading for all posts tables on your site. If a custom heading is specified within the shortcode itself (in the columns option), then it will take priority over the value returned from this filter.
add_filter( 'posts_table_column_heading_title', function( $heading ) {
return 'My Title';
} );posts_table_column_priority_<column>
Filter which allows you to override a column priority for all posts tables on your site. If a priority is specified within the shortcode itself (using the priorities option), then it will take priority over the value returned from this filter.
add_filter( 'posts_table_column_priority_date', function( $priority ) {
return 10;
} );posts_table_column_width_<column>
Filter which allows you to override a column width for all posts tables on your site. If a width is specified within the shortcode itself (using the widths option), then it will take priority over the value returned from this filter.
add_filter( 'posts_table_column_width_author', function( $width ) {
return '100px';
} );posts_table_column_searchable_<column>
This filter allows you to set whether or not a column is “searchable” in the posts table. If a column is searchable, it means that the column will be used when the user types something into the search box above the table.
By default, the plugin includes all columns for searching, except for the image column (unless you're using the lazy load option, in which case only the title and content columns are searchable). To override this behavior when you're not using lazy load, use this filter with the appropriate column name added to the filter.
E.g. to exclude the title column from the table search:
add_filter( 'posts_table_column_searchable_title', '__return_false' );If you wish to disable searching for a custom field or taxonomy, use the column name without the cf: or tax: prefix:
add_filter( 'posts_table_column_searchable_my_custom_field', '__return_false' );posts_table_column_sortable_<column>
This filter allows you to set whether or not a column is “sortable” in the posts table. If a column is sortable, the table can be re-ordered by that column using the up/down arrows that appear in the column heading.
If you’re using lazy load, the sorting is restricted to certain columns only. If you’re not using lazy load, then sorting is enabled for all columns except image.
E.g. to prevent the table being sorted by title:
add_filter( 'posts_table_column_sortable_title', '__return_false' );See the note above about using this filter for custom field or taxonomy columns.
posts_table_max_posts_limit
Filter which allows you to override the maximum posts limit (500 posts) set in Posts Table Pro. Note that this option only applies when you are not using the lazy_load option.
add_filter( 'posts_table_max_posts_limit', function( $limit, $posts_table ) {
return 1000;
}, 10, 2 );posts_table_data_cache_expiry
Filter which allows you to set the expiry time (in seconds) for the table data cache. The default cache expiry time is 6 hours, and is configured via the plugin settings.
add_filter( 'posts_table_data_cache_expiry', function( $expiry, $cache ) {
return 3 * DAY_IN_SECONDS;
}, 10, 2 );posts_table_use_data_cache
Filter whether to use data caching globally across all posts tables. Should return true or false.
posts_table_query_args
Filter which allows you to override the query args passed to WP_Query prior to retrieving posts from the database. See WP_Query documentation for details.
add_filter( 'posts_table_query_args', function( $args, $query ) {
// do something with $args
return $args;
}, 10, 2 );posts_table_optimize_table_query
Use this filter to disable the database query optimisations applied by Posts Table Pro. Use this if you need to directly access the post_content or post_excerpt database fields, even when the content and excerpt columns are not displayed in your posts table.
add_filter( 'posts_table_optimize_table_query', '__return_false' );posts_table_shortcode_output
Allows you to modify the HTML returned by the [posts_table] shortcode. Takes two parameters: the HTML and the Posts_Data_Table instance.
add_filter( 'posts_table_shortcode_output', function( $html, $table ) {
// do something with HTML
return $html;
}, 10, 2 );posts_table_load_frontend_scripts
Filter to disable the loading of the frontend scripts and styles used in Posts Table Pro. Only use this if you want to load the scripts yourself (e.g. on specific pages).
add_filter( 'posts_table_load_frontend_scripts', '__return_false' );posts_table_use_fitvids
Filter to disable the use of FitVids script used in Posts Table Pro. FitVids is used to ensure videos are sized correctly at smaller screen sizes.
add_filter( 'posts_table_use_fitvids', '__return_false' );posts_table_enable_select2
Filter whether to enable or disable the Select2 Javascript library. This library adds enhancements to the search filters and page length dropdown menus above and below the table. It is enabled by default. To disable it, use:
add_filter( 'posts_table_enable_select2', '__return_false' );posts_table_facetwp_custom_args
Filter which allows you to modify the arguments passed to the post table when using the FacetWP integration.
add_filter( 'posts_table_facetwp_custom_args', function( $args ) {
$args['lazy_load'] = true;
return $custom_args;
} );posts_table_custom_table_data_<column>
Filter which allows you to add a custom column in Posts Table Pro. See this article for more details.
add_filter( 'posts_table_custom_table_data_media_type', function( $obj, $post, $args ) {
return new Posts_Table_Media_Type_Column( $post );
} );Arguments
Abstract_Table_Data - The table data object.
WP_Post - The current post object.
Table_Args - The table arguments object.
Return
Abstract_Table_Data- the table data object.
Actions
posts_table_parse_args
Fired when the posts table arguments have been parsed and set. Takes one argument – the Barn2PluginPosts_Table_ProTable_Args instance.
posts_table_args_updated
Fired when the table args are updated. This happens, for example, when the table is filtered by category or a search term is entered. Takes one argument - the Barn2PluginPosts_Table_ProPosts_Table object.
posts_table_before_get_table
Fired once before the table is created, before the attributes and headings are added to the table. Takes one argument – the Barn2PluginPosts_Table_ProPosts_Table object.
posts_table_after_get_table
Fired once after each the table is fully created and (for standard loading) the data has been added. Takes one argument – the Barn2PluginPosts_Table_ProPosts_Table object.
posts_table_before_get_data
Fired once before the data is fetched and added to the table. Takes one argument – the Barn2PluginPosts_Table_ProPosts_Table object.
posts_table_after_get_data
Fired once after the data is added to the table. Takes one argument – the Barn2PluginPosts_Table_ProPosts_Table object.