Views API Hooks
Filters the array of shortcodes that can be used inside other shortcodes.
By design, Views can handle a series of shortcodes inside other shortcodes. With this filter, the list of allowed inner shortcodes can be altered.
array $custom_inner_shortcodes The custom shortcodes that can be used inside other shortcodes.
This filter must return an array.
More Usage examples
//Add your own shortcode 'myshortcode' to the list of allowed inner shortcodes:
add_filter( 'wpv_custom_inner_shortcodes', 'prefix_add_my_shortcodes' );
function prefix_add_my_shortcodes( $shortcodes ) {
$shortcodes[] = 'myshortcode';
return $shortcodes;
}
Filters the output generated by a Content Template or, in general, the content of any post.
There are four parameters being passed to this filter: the content to be displayed, the ID of the Content Template being applied, the ID of the current post and the place where this filter is being used.
Note that the $kind parameter can be sometimes ambiguous. For single pages it should point to single-{post-type} for the main post being displayed and to listing-{post-type} on any View used inside that page. But on archives, it will point to archive-{taxonomy} on taxonomy archive pages and to archive-{post-type} elsewhere, no matter if the post is being displayed in a widget or in a View embedded inside a post shown on the archive.
Remember that the filter can take four parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_content_template_output', 'my_callback_function', 101, 4 );
string $content The content to be displayed, whether it’s the one coming from a Content Template or the real post content (if no Template needs to be applied)..
int $template_selected The ID of the Template being applied, can be 0 when there is none.
int $id The ID of the post that the template is being applied to.
string $kind Place where this template is being used: single-{post-type}, archive-{post-type}, archive-{taxonomy}, listing-{post-type}.
This filter must return a string.
More Usage examples
//Wrap single posts of the custom type "teacher" inside a container with a specific class selector if they have a given custom field "role" with value "tutor" and they are using a spcific Content Template:
add_filter( 'wpv_filter_content_template_output', 'prefix_wrap_teacher_by_custom_field', 101, 4 );
function prefix_wrap_teacher_by_custom_field( $content, $template_selected, $id, $kind ) {
if ( $kind = 'single-teacher' && $template_selected = 123 ) { // if it's a single tacher page using the Content Template with ID 123
$meta = get_post_meta($id, 'role');
if ( $meta = 'tutor' ) { // if this teachd also has a tutor value on the role custom field
$content = '<div class="tutor">' . $content . '</div>';
}
}
return $content;
}
When a View listing posts contains a filter by a custom field, this filters the value of the field coming from the View settings and before passing through the check for URL params, shortcode attributes and date functions.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_custom_field_filter_original_value', 'my_callback_function', 101, 3 );
When filering by a custom field, it is possible to set a single value or a series of values to check against. For example:
= comparison function, $value will just be a string containing the value to check against.IN or NOT IN comparison function, $value will contain a comma separated list of values to check against.BETWEEN or NOT BETWEEN comparison function, $value will contain the values in the format minumum value, maximim valueAlso, depending on what kind of value is the one that the filter compares against, the real value can be any of the following:
param, it will be URL_PARAM(param).attrib, it will be VIEW_PARAM(attrib)So, for example, in a filter by a custom field my-numeric-field using a BETWEEN comparison and getting the minimum value from an URL parameter my-minumum and the maximum value from a Views shortcode attribute my_maximum, $value will have the following format:
$value = 'URL_PARAM(my-minimum),VIEW_PARAM(my_maximum)';
string $value The value coming from the View settings filter, and before passing through the check for URL params, shortcode attributes and date functions.
string $meta_name The key of the custom field being used to filter by.
int $view_id The View ID.
This filter must return a string with format compatible with $value.
More Usage examples
/*
Let's reuse a View with a filter by a Types custom field that gets the field value using a URL parameter. We want to use this View on a page that will not get that URL parameter, but still we want to filter the View by a value set on a shortcode attribute in the {{wpv-view}} shortcode.
We can asume that out View has an ID equal to 25 and the custom field is <code>my-post-field</code> (so its real slug is <code>wpcf-my-post-field</code>). Likewise, let's say that the View is filtering by the custom field <code>my-post-field</code> using the URL parameter <code>my-field-param</code> and that we want to pass the value of the fied using the shortcode attribute <code>myvalue</code>, like in {{wpv-view myvalue="xxx"}}.
We are going to find the string <code>URL_PARAM(my-field-param)</code> and replace it with <code>VIEW_PARAM(myvalue)</code>:
*/
add_filter( 'wpv_filter_custom_field_filter_original_value', 'prefix_change_url_to_shortcode_attribute', 10, 3 );
function prefix_change_url_to_shortcode_attribute( $value, $key, $view_id ) {
// We might need to add a check so this filter only gets applied if we are in the specific page where we want to reuse the View: use is_single(), is_page() or is_singular()
if ( $view_id == 25 && $key == 'wpcf-my-post-field' ) { // if we are displaying our View with ID 25 and the filter is for the field with name wpcf-post-date-filter
$value = str_replace( 'URL_PARAM(my-field-param)', 'VIEW_PARAM(myvalue)', $value );
}
return $value;
}
When a View listing posts contains a filter by a custom field, this filters the value of the field coming from the View settings and after passing through the check for URL params, shortcode attributes, and date functions.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_custom_field_filter_processed_value', 'my_callback_function', 101, 3 );
When filtering by a custom field, it is possible to set a single value or a series of values to check against. For example:
= comparison function, $value will just be a string containing the value to check against.IN or NOT IN comparison function, $value will contain a comma separated list of values to check against.BETWEEN or NOT BETWEEN comparison function, $value will contain the values in the format minumum value, maximim valueAlso, depending on what kind of value is the one that the filter compares against, the real value can be any of the following:
param, it will be URL_PARAM(param).attrib, it will be VIEW_PARAM(attrib)So, for example, in a filter by a custom field my-numeric-field using a BETWEEN comparison and getting the minimum value from an URL parameter my-minumum and the maximum value from a Views shortcode attribute my_maximum, $value will have the following format:
$value = 'URL_PARAM(my-minimum),VIEW_PARAM(my_maximum)';
When applying the filter by a custom field, Views replaces each call to URL_PARAM(param), VIEW_PARAM(attribute) or a date function by its actual value set by the URL parameter itself, the View shortcode attribute itself or the date function value.
There can be times when the URL parameter or shortcode attribute being expected are not set. In that case, Views replaces the relevant piece of $value with a static string set by the global variable $no_parameter_found.
This filter is applied to the string $value after all of those modifications have been done.
string $value The value coming from the View settings filter, and after passing through the check for URL params, shortcode attributes and date functions.
string $meta_name The key of the custom field being used to filter by.
int $view_id The View ID.
This filter must return a string with format compatible with $value.
More Usage examples
/*
Let's build a custom search to filter posts between two dates set by a Types date custom field named <code>post-date-field</code> (so its real slug is <code>wpcf-post-date-field</code>). So we create a new View and let's asume it gets an ID equal to 25.
Our goal is to be able to set just one date and filter automatically posts that are between this date and a month after that. We add the date filter in the Filter section and set it to filter between two numeric values given by the two URL parameters <code>post-date-field_min</code> and <code>post-date-field_max</code>.
We only want to show the search input for the minimum date, so we remove the wpv-control shortcode related to the maximum value. After adding out own texts, our Filter section will look like this:
[wpv-filter-start hide="false"]
[wpv-filter-controls]
[wpml-string context="wpv-views"]Posts within one month after:[/wpml-string]
[wpv-control field="post-date-field" url_param="post-date-field_min" type="datepicker"]
[wpv-filter-submit name="Search"]
[/wpv-filter-controls]
[wpv-filter-end]
Now we need to manually set the maximum value to one month after the minimum value using this filter:*/
add_filter( 'wpv_filter_custom_field_filter_processed_value', 'prefix_next_month_filter', 10, 3 );
function prefix_next_month_filter( $value, $key, $view_id ) {
if ( $view_id == 25 && $key == 'wpcf-post-date-field' ) { // if we are displaying our View with ID 25 and the filter is for the field with name wpcf-post-date-filter
global $no_parameter_found; // set the global $no_parameter_found
$values = array_map( 'trim', explode( ",", $value ) ); // explode $value into the two actual values
if ( count( $values ) == 2 ) { // check that there are two values indeed
$this_day = $values[0]; // get the minimum date value
if ( $this_day != $no_parameter_found ) { // if a minimum date vaue has been set - so it only runs after a value has been submited and not on the first pageload
list($y,$m,$d) = explode('-', date('Y-m-d', $this_day));
$next_month_day = mktime(0,0,0,$m+1,$d,$y); // construct the maximum date
$value = str_replace($no_parameter_found, $next_month_day, $value); // replace the $no_parameter_found with the actual maximum date
}
}
}
return $value;
}
//That's all! Once a minimum date is set, the View will only display posts with the custom field between that date and a month after it.
Filters the type of the custom field being used on a Views filter.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_custom_field_filter_type', 'my_callback_function', 30, 3 );
string $type The type of the filter that the current custom field produces.
string $meta_name The name of the custom field being used in the filter.
int $view_id The ID of the View being processed.
This filter must return a string valid as filter type: NUMERIC, BINARY, CHAR, DATE, DATETIME, DECIMAL, SIGNED, TIME, UNSIGNED.
More Usage examples
/*
We have a custom post type with locations, and a custom field storing minimum and maximum temperatures in that location. That field value will take up to two decimal places and will always stay between 100.00 and -30.00 degrees, so it will hold at least 5 ciphers.
We have created a View (with ID 646) listing locations, and added a filter by this temperature custom field, but we really need it to be able to use those dcimal places. By default, Views just produces integer filters when dealing with numbers even if you set the filter to use 'DECIMAL' instead of 'INTEGER', but we can fix this by passing the number of ciphers and decimal places it should expect:
*/
add_filter( 'wpv_filter_custom_field_filter_type', 'prefix_temperature_decimal_filter', 10, 3 );
function prefix_temperature_decimal_filter( $type, $meta_name, $view_id ) {
if ( $type == 'DECIMAL' && $view_id == 646 ) { // if this is our View and this field is set as DECIMAL
$type = 'DECIMAL(5,2)'; // set the DECIMAL to use 2 decimal places among 5 ciphers
}
return $type;
}
Filters the output generated by the {{wpv-filter-end}} shortcode.
Remember that the filter can take four parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_end_filter_form', 'my_callback_function', 101, 4 );
The {{wpv-filter-end}} shortcode is part of a View Filter section content by default. It is used to render the closing tag for the HTML form needed for Views pagination, table sorting or custom searches.
Some Views will not need that HTML form, so this {{wpv-filter-end}} shortcode will return nothing. You can check whether a particular View needs a form or not by using the $is_required parameter.
string $out The default form closing tag, if needed, or an empty string otherwise.
array $view_settings The current View settings.
int $view_settings The ID of the View being displayed.
bool $is_required Whether this View requires a form to be displayed (has a custom search OR uses table sorting OR uses pagination).
This filter must return a string.
More Usage examples
//Add a hidden field on all Views listing a custom post type "cars" that indeed need this HTML form:
add_filter( 'wpv_filter_end_filter_form', 'prefix_add_hidden_field', 101, 4 );
function prefix_add_hidden_field( $out, $view_settings, $view_id, $is_required ) {
if ( is_array( $view_settings['post_type'] ) && in_array( 'cars', $view_settings['query_type'] ) && $is_required ) { // if this View lists cars and indeed needs the form
$out = '<input type="hidden" id="my-hidden-field" name="my-hidden-field" value="my-hidden-field" />' . $out;
}
return $out;
}
Filters the ID of the Content Template that is going to be applied to a post.
Note that the $kind parameter can be sometimes ambiguous. For single pages, it should point to single-{post-type} for the main post being displayed and to listing-{post-type} on any View used inside that page. But on archives, it will point to archive-{taxonomy} on taxonomy archive pages and to archive-{post-type} elsewhere, no matter if the post is being displayed in a widget or in a View embedded inside a post shown on the archive.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_force_template', 'my_callback_function', 101, 3 );
int $template_selected The ID of the Template being applied, can be 0 when there is none.
int $id The ID of the post that the template is being applied to.
string $kind Place where this template is being used: single-{post-type}, archive-{post-type}, archive-{taxonomy}, listing-{post-type}.
This filter must return a number.
More Usage examples
//Show a specific Content Template applied to a given post for not logged in visitors and in every place where this post appears:
add_filter( 'wpv_filter_force_template', 'prefix_fixed_content_for_visitors', 101, 3 );
function prefix_fixed_content_for_visitors( $template_selected, $id, $kind ) {
if ( !is_user_logged_in() && $id == 345 ) { // if the user is not logged in and is trying to view the post with ID 345
$template_selected = 123; // assign a fixed Content Template with ID 123 that contains a static text
}
return $template_selected;
}
Filters the ID of the WordPress Archive to be used on a given archive loop.
Remember that the filter can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_force_wordpress_archive', 'my_callback_function', 30, 2 );
The name of the loop being displayed has a special format. This list will guide you on the values used:
view_home-blog-page for the last entries home page of the site.view_day-page, view_month-page, view_year-page for date-based archive loops.view_author-page for author-based archive loops.view_search-page for the search results archive page.view_cpt_{post_type} for custom post type archives.view_taxonomy_loop_{taxonomy} for taxonomy archive loops.int $wpa_assigned The ID of the WordPress Archive assigned to that particular loop, or 0 if it is not set.
string $wpa_loop The name of the loop being displayed.
This filter must return an integer.
More Usage examples
//Display the search results page using a WordPress Archive with ID 4 on Tuesday, Thursday and Saturday, and with ID 8 the oher days:
add_filter( 'wpv_filter_force_wordpress_archive', 'prefix_different_search_results', 30, 2 );
function prefix_different_search_results( $wpa_assigned, $wpa_loop ) {
$wpa_to_apply = $wpa_assigned;
if ( $wpa_loop == 'view_search-page' ) {
$weekday_wpa = array(
0 => 4,
1 => 8,
2 => 4,
3 => 8,
4 => 4,
5 => 8,
6 => 4
);
$current_weekday = date( 'w' );
if ( isset( $weekday_wpa[ $current_weekday ] ) ) {
$wpa_to_apply = $weekday_wpa[ $current_weekday ];
}
}
return $wpa_to_apply;
}
Allows third-party shortcode’s attribute translation when used in the Filter or Loop Output editor.
array $atts List of the already existing fake shortcodes array. The user needs to add his own callback and return the array.
This filter must return an array.
More Usage examples
function add_shortcode_atts_for_translation( array $fake_shortcodes ) {
$fake_shortcodes['my-shortcode'] = array( $this, 'register_my-shortcode_atts_for_translation_callback' );
return $fake_shortcodes;
}
This filter allows you to override the error messages, or add custom styling through CSS classes to the error messages generated by the Toolset Password management shortcodes on failure. This also includes the shortcodes that display a login form or a form to reset the password.
string $message The error message that will be displayed.
string $class CSS class for custom styling.
string $code The error name that identifies the failing action. Available values are based on the usage. For the form to login, invalid_username, incorrect_password, empty_password and empty_username. For the form to reset the password, expiredkey, invalidkey or invalid_key when the key to reset the password is not valid, invalid_email, invalidcombo for invalid username or email, password_reset_mismatch, password_reset_empty and empty_username.
String
More Usage examples
//Following example provides a way to override messages based on <code>$code</code> and adds the custom class to the message.
add_filter( 'wpv_filter_override_auth_errors', 'custom_wpv_override_auth_errors', 30, 3 );
function custom_wpv_override_auth_errors( $message, $class = '', $code = '' ) {
if ( $code != '') {
$message = __( '<strong>ERROR</strong>: ', 'wpv-views' );
switch( $code ) {
case 'invalid_username':
$message .= __( 'Invalid username.', 'wpv-views' );
break;
case 'incorrect_password':
$message .= __( 'The password you entered is incorrect.', 'wpv-views' );
break;
case 'empty_password':
$message .= __( 'The password field is empty.', 'wpv-views' );
break;
case 'empty_username':
$message .= __( 'The username field is empty.', 'wpv-views' );
break;
default:
$message .= __( 'Unknown error.', 'wpv-views' );
break;
}
if( !empty( $class ) ) {
$message = '<div class="' . $class . '">' . $message . '</div>';
}
return $message;
}
}
Filters the output generated by the {{wpv-post-excerpt}} shortcode.
This filter lets you modify the string that will generate the excerpt before expanding the shortcodes it may contain and before the length attribute is applied.
This way you can parse and delete specific shortcodes from the excerpt, like the {{caption}} one.
string $excerpt The string we will generate the excerpt from the real $post->excerpt or the $post->content, before stretching and parsing the inner shortcodes.
This filter must return a string.
More Usage examples
// Remove any {{caption}} shortcode that the excerpt might include, mainly if it is being taken from the post content:
// For this example to work with PHP 7+ version, you need to use preg_replace_callback instead of preg_replace. For details see the official PHP documentation here: http://php.net/manual/en/function.preg-replace-callback.php
add_filter('wpv_filter_post_excerpt', 'prefix_strip_captions');
function prefix_strip_captions($excerpt) {
$excerpt = preg_replace('#([[]caption)(.*)([[]/caption[]])#e', '', $excerpt);
return $excerpt;
}
When displaying a View listing posts, this filter is applied to the arguments being generated by the View settings before they are passed to the WP_Query class.
Note that the filters that you can add to the View are also hooked here, each of them using a different priority that gets up to 100. To ensure that your filter runs after them, you would need to use a higher priority number.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_query', 'my_callback_function', 101, 3 );
array $query_args Τhe query arguments as in WP_Query.
array $view_settings The View settings.
int $view_id The View ID.
Αn array of arguments $query_args that will be used by the WP_Query class.
More Usage examples
//Return only posts from the current author when listing posts of type company:
add_filter( 'wpv_filter_query', 'prefix_show_only_current_author', 101, 1 );
function prefix_show_only_current_author( $query_args ) {
global $current_user;
$types = (array) $query_args['post_type'];
if ( !is_admin() && in_array( 'company', $types ) ) {
$query_args['author'] = empty( $current_user->ID ) ? -1 : $current_user->ID;
}
return $query_args;
}
When displaying a View listing posts, this filter is applied after the WP_Query has been run.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_query_post_process', 'my_callback_function', 101, 2 );
array $query_args The queried object returned by the WordPress query.
array $view_settings Τhe View settings.
int $view_id Τhe View ID.
This filter must return an object $query compatible with the first parameter.
More Usage examples
//If the query does not find any posts, return a specific post with ID equal to 1
add_filter( 'wpv_filter_query_post_process', 'prefix_modify_empty_query', 101, 3 );
function prefix_modify_empty_query( $query, $view_settings, $view_id ) {
if ( empty( $query->posts ) ) { // if the query found no posts
$default_post = get_post(1); // get the post with ID equal to 1
$query->posts = array( $default_post ); // add the default post to the posts result array
$query->found_posts = 1; // modify the count of found posts
$query->post_count = 1; // modify the count of displayed posts
}
return $query;
}
Filters the output generated by the {{wpv-filter-start}} shortcode.
Remember that the filter can take four parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_start_filter_form', 'my_callback_function', 101, 4 );
The {{wpv-filter-start}} shortcode is part of a View Filter section by default. It is used to render the opening tag for the HTML form needed for Views pagination, table sorting or custom searches. In addition to the form tag, it renders some hidden inputs needed for the form to work properly.
Some Views will not need that HTML form, so this {{wpv-filter-start}} shortcode will return nothing. You can check whether a particular View needs a form or not by using the $is_required parameter.
string $out The default form opening tag followed by the required hidden input tags needed for pagination and table sorting, if needed, or an empty string otherwise.
array $view_settings The current View settings.
int $view_id The ID of the View being displayed.
bool $is_required Whether this View requires a form to be displayed (has a custom search OR uses table sorting OR uses pagination).
This filter must return a string.
More Usage examples
//Add a hidden field on all Views listing a custom post type "cars" that indeed need this HTML form:
add_filter( 'wpv_filter_start_filter_form', 'prefix_add_hidden_field', 101, 4 );
function prefix_add_hidden_field( $out, $view_settings, $view_id, $is_required ) {
if ( is_array( $view_settings['post_type'] ) && in_array( 'cars', $view_settings['query_type'] ) && $is_required ) { // if this View lists cars and indeed needs the form
$out .= '<input type="hidden" id="my-hidden-field" name="my-hidden-field" value="my-hidden-field" />';
}
return $out;
}
Allows to include or exclude posts assigned to Child Terms in a Hierarchical Taxonomy when filtering a View by their Parent Term.
This filter allows you to alter the WordPress’ native behavior of including posts assigned to Child terms in a Query filtering by a taxonomy Related Parent terms Only and decide whether or not to consider those Child Terms in each View.
boolean $include_child True or false, whether to include child terms or not.
string $category_name The slug of the taxonomy.
int $view_id The ID of the View.
Returns true or false.
More Usage examples
add_filter('wpv_filter_tax_filter_include_children', 'no_child_term_func', 101, 3);
function no_child_term_func($include_child, $category_name, $view_id){
if($view_id == xx && $category_name == taxonomy_slug){
$include_child = false;
}
return $include_child;
}
Use this filter to modify the retrieved list of terms that will be offered in the front-end filter.
array $terms An array of WP_Term objects representing a term.
string $taxonomy The slug of the taxonomy being used to filter by.
int $view_id The ID of the relevant View.
More Usage examples
// Following example filters the terms offered in the frontend filter to ones with slug cat-one.
add_filter( 'wpv_filter_taxonomy_frontend_search_available_terms', 'prefix_modify_list_of_terms', 10, 3 );
function prefix_modify_list_of_terms( $terms, $taxonomy, $view_id ) {
$curated_terms = array();
foreach ( $terms as $term ) {
if ( $term->slug === 'cat-one' ) {
$curated_terms[] = $term;
}
}
return $curated_terms;
}
Use this filter to modify the arguments used for getting the terms that will be offered in the front-end filter.
array $args An array of arguments for the get_terms function, see https://developer.wordpress.org/reference/functions/get_terms/ for a complete list of supported attributes.
string $taxonomy The slug of the taxonomy being used to filter by.
int $view_id The ID of the relevant View.
More Usage examples
// Following example limits the terms offered in the frontend filter to those which slug is either cat-one or cat-three.
add_filter( 'wpv_filter_taxonomy_frontend_search_get_terms_args', 'prefix_modify_get_terms_args', 10, 3 );
function prefix_modify_get_terms_args( $args, $taxonomy, $view_id ) {
$args['slug'] = array(
'cat-one',
'cat-three',
);
return $args;
}
When displaying a View listing taxonomy terms, this filter is applied to the results of the get_terms() call.
Note that in the current implementation, the number – being it the View setting limit – and offset arguments are applied here with a priority of 10. This might change in the future for the sake of consistency.
Remember that the filter can take four parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_taxonomy_post_query', 'my_callback_function', 101, 4 );
array $items The terms returned by the get_terms() call.
array $tax_query_settings The relevant elements of the View settings in an array to be used as arguments in a get_terms() call.
array $view_settings The View settings.
int $view_id The View ID.
This filter must return an array of terms compatible with $items: an array of term objects returned by the get_terms() function.
More Usage examples
//If the View returns just the terms given in an array, do not display any term at all
add_filter( 'wpv_filter_taxonomy_post_query', 'prefix_check_items', 20, 4 );
function prefix_check_items( $items, $tax_query_settings, $view_settings, $view_id ) {
$terms_flag_array = array( 1, 2, 3 ); // set the terms we want to check against
$items_count = count( $items ); // count all the returned terms
$match_count = 0; // initiate a match counter
foreach( $items as $item ) {
if ( in_array( $item->term_id, $terms_flag_array ) ) { // if the term is in the array to check against
$match_count = $match_count + 1; // then add 1 to the match counter
}
}
if ( $items_count == $match_count ) { // if all the returned items are in the array to check against
$items = array(); // we set the $items array to be empty
}
return $items;
}
When displaying a View listing taxonomy terms, this filter is applied to the arguments that will be passed to the get_terms() call.
Note that:
number – being it the View setting limit – and offset arguments are applied in the wpv_filter_taxonomy_post_query filter, so it’s not a good idea to add them here. This might change in the future for the sake of consistency.So this filter allows for changes in the values set on the Query options section of the View, and also gives a way to pass other parameters to the get_terms() function that do not have a GUI.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_taxonomy_query', 'my_callback_function', 101, 3 );
array $tax_query_settings The relevant elements of the View settings in an array to be used as arguments in a get_terms() call.
array $view_settings The View settings.
int $view_id The View ID.
This filter must return an array of arguments compatible with $tax_query_settings that will be used as the second parameter in the get_terms() function.
[code="lang"]$tax_query_settings = array(
'hide_empty' => $view_settings['taxonomy_hide_empty'], // the View setting "Don't show empty terms"
'hierarchical' => $view_settings['taxonomy_include_non_empty_decendants'], // the View setting "Include terms that have non-empty descendants"
'pad_counts' => $view_settings['taxonomy_pad_counts'], // the View setting "Include children in the post count"
'orderby' => $view_settings['taxonomy_orderby'],
'order' => $view_settings['taxonomy_order']
);[/code]
More Usage examples
//Return only terms with the string <code>needle</code> in their name
add_filter( 'wpv_filter_taxonomy_query', 'prefix_modify_tax_query', 101, 3 );
function prefix_modify_tax_query( $tax_query_settings, $view_settings, $view_id ) {
$tax_query_settings['name__like'] = 'needle';
return $tax_query_settings;
}
When displaying a View listing users, this filter is applied after the WP_User_Query has been run.
Remember that the filter can take four parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_user_post_query', 'my_callback_function', 101, 4 );
array $items The user objects returned by the WP_User_Query.
array $query_args The query arguments that were passed to the WP_User_Query.
array $view_settings The View settings.
int $view_id Τhe View ID.
This filter must return an array of user objects $items.
More Usage examples
//If the query does not find any user, return a specific user with ID equal to 6
add_filter( 'wpv_filter_user_post_query', 'prefix_modify_empty_user_query', 10, 4 );
function prefix_modify_empty_user_query( $items, $query_args, $view_settings, $view_id ) {
if ( empty( $items ) ) {
$default_user = get_user_by( 'id', 6 );
$items = array( $default_user );
}
return $items;
}
When displaying a View listing users, this filter is applied to the arguments being generated by the View settings before they are passed to the WP_User_Query class.
Note that the filters that you can add to the View are applied before this filter.
Remember that the filter can take three parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_filter_user_query', 'my_callback_function', 101, 3 );
array $query_args The Query arguments as in WP_User_Query.
array $view_settings The View settings.
int $view_id The View ID.
This filter must return an array of arguments $query_args that will be used by the WP_User_Query class.
More Usage examples
//If you have a filter in the View to include users from different roles and do not want the role set in the Content selection section to be applied, you can do something like this
add_filter( 'wpv_filter_user_query', 'prefix_unset_user_roles', 101, 1 );
function prefix_unset_user_roles( $query_args ) {
if ( isset( $query_args['role'] ) ) {
unset( $query_args['role'] );
}
return $query_args;
}
Filters the text used to display page numbers in Views pagination.
int $page_number The displayed number of the page.
This filter must return a string.
More Usage examples
//Change the value of the first element in the select dropdown used in pagination:
add_filter( 'wpv_pagination_page_number', 'prefix_pagination_change_values' );
function prefix_pagination_change_values( $page_number ) {
if ( $page_number == 1 ) {
$new_page_number = __('first');
}
return $new_page_number;
}
Filters the titles of the <a> HTML tags when using links as page selectors in Views pagination.
Remember that the filter can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_pagination_page_title', 'my_callback_function', 101, 2 );
string $page_title The title for the page link.
int $page_number The displayed number of the page.
This filter must return a string.
More Usage examples
//Change the titles of the pagination links so they show an "Element X" value:
add_filter( 'wpv_pagination_page_title', 'prefix_pagination_change_titles', 20, 2 );
function prefix_pagination_change_values( $page_title, $page_number ) {
$newtitle = sprintf( __( 'Element %s'), $page_number );
return $newtitle;
}
Filters the View settings for a given View before it’s processed and output
Remember that the filter can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv_view_settings', 'my_callback_function', 101, 2 );
array $view_settings Τhe View settings.
int $view_id Τhe View ID.
This filter must return an array compatible with the $view_settings structure. It gets applied inside the get_view_settings() method for the WP_Views class, used to get the settings of the View that is going to be rendered.
More Usage examples
//Add a wrapper with a classname <code>wrapper</code> around a particular View custom search filters and pagination section:
add_filter( 'wpv_view_settings', 'prefix_modify_rendered_view', 30, 2 );
function prefix_modify_rendered_view( $view_settings, $view_id ) {
if ( $view_id == 23 ) { // if displaying a View with ID equal to 23
$view_settings['filter_meta_html'] = '<div class="wrapper">' . $view_settings['filter_meta_html'] .'</div>';
}
return $view_settings;
}
//Modify the limit and/or offset settings of a given View to use a number greater than 50:
add_filter( 'wpv_view_settings', 'prefix_modify_filter_offset_view', 5, 2 ); // use a low priority number of 5, so this runs early
function prefix_modify_filter_offset_view( $view_settings, $view_id ) {
if ( $view_id == 374 ) { // if displaying a View with ID equal to 374
$view_settings['limit'] = 75; // show 75 posts
$view_settings['offset'] = 60; // skip the first 60 posts
}
return $view_settings;
}
When displaying a View listing posts, this action is executed after each post in the Views loop.
Remember that the action can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_action( 'wpv-after-display-post', 'my_callback_function', 101, 2 );
object $post The post object coming from the Views loop.
int $view_id Τhe View ID.
Actions do not need to return anything.
More Usage examples
//Increment a custom field for a given post after it is being displayed using a specific View:
add_action( 'wpv-after-display-post', 'prefix_count_views', 10, 2 );
function prefix_count_views( $post, $view_id ) {
if ( $post->ID == 33 && $view_id == 44 ) { // after displaying post with ID 33 using the View with ID 44
// Update the postmeta to increment a numeric custom field
}
}
When displaying a View listing taxonomies, this action is executed after each term in the Views loop.
Remember that the action can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_action( 'wpv-after-display-taxonomy', 'my_callback_function', 101, 2 );
object $term The term object coming from the Views loop.
int $view_id Τhe View ID.
Actions do not need to return anything.
More Usage examples
//Store all term slugs being displayed by a specific View into a global variable to be used later
add_action( 'wpv-after-display-taxonomy', 'prefix_store_slugs', 10, 2 );
function prefix_store_slugs( $term, $view_id ) {
if ( $view_id == 44 ) { // if displaying the View with ID 44
global $prefix_my_slugs;
if ( isset( $prefix_my_slugs ) && is_array( $prefix_my_slug ) ) {
$prefix_my_slug[] = $term->slug;
} else {
$prefix_my_slug = array( $term->slug );
}
}
}
When displaying a View listing users, this action is executed after each user in the Views loop.
Remember that the action can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_action( 'wpv-after-display-user', 'my_callback_function', 101, 2 );
object $user The user object coming from the Views loop.
int $view_id The View ID.
Actions do not need to return anything.
More Usage examples
//Store all user IDs being displayed by a specific View into a global variable to be used later
add_action( 'wpv-after-display-user', 'prefix_store_ids', 10, 2 );
function prefix_store_ids( $user, $view_id ) {
if ( $view_id == 44 ) { // if displaying the View with ID 44
global $prefix_my_ids;
if ( isset( $prefix_my_ids ) && is_array( $prefix_my_ids ) ) {
$prefix_my_ids[] = $user->ID;
} else {
$prefix_my_ids = array( $user->ID );
}
}
}
When displaying a View listing posts, this action is executed before each post in the Views loop.
Remember that the action can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_action( 'wpv-before-display-post', 'my_callback_function', 101, 2 );
object $post The post object coming from the Views loop.
int $view_id Τhe View ID.
Actions do not need to return anything.
More Usage examples
//Increment a custom field for a given post when it is being displayed using a specific View:
add_action( 'wpv-before-display-post', 'prefix_count_views', 10, 2 );
function prefix_count_views( $post, $view_id ) {
if ( $post->ID == 33 && $view_id == 44 ) { // if displaying post with ID 33 using the View with ID 44
// Update the postmeta to increment a numeric custom field
}
}
When displaying a View listing taxonomies, this action is executed before each term in the Views loop.
Remember that the action can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_action( 'wpv-before-display-taxonomy', 'my_callback_function', 101, 2 );
object $term Τhe term object coming from the Views loop.
int $view_id The View ID.
Actions do not need to return anything.
More Usage examples
// Store all term slugs being displayed by a specific View into a global variable to be used later
add_action( 'wpv-before-display-taxonomy', 'prefix_store_slugs', 10, 2 );
function prefix_store_slugs( $term, $view_id ) {
if ( $view_id == 44 ) { // if displaying the View with ID 44
global $prefix_my_slugs;
if ( isset( $prefix_my_slugs ) && is_array( $prefix_my_slug ) ) {
$prefix_my_slug[] = $term->slug;
} else {
$prefix_my_slug = array( $term->slug );
}
}
}
When displaying a View listing users, this action is executed before each user in the Views loop.
Remember that the action can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_action( 'wpv-before-display-user', 'my_callback_function', 101, 2 );
object $user The user object coming from the Views loop.
int $view_id The View ID.
Actions do not need to return anything.
More Usage examples
//Store all user IDs being displayed by a specific View into a global variable to be used later
add_action( 'wpv-before-display-user', 'prefix_store_ids', 10, 2 );
function prefix_store_ids( $user, $view_id ) {
if ( $view_id == 44 ) { // if displaying the View with ID 44
global $prefix_my_ids;
if ( isset( $prefix_my_ids ) && is_array( $prefix_my_ids ) ) {
$prefix_my_ids[] = $user->ID;
} else {
$prefix_my_ids = array( $user->ID );
}
}
}
Filters the output of the {{wpv-post-featured-image}} shortcode
string $out The {{wpv-post-featured-image}} shortcode output.
This filter must return a string.
More Usage examples
//Wrap the featured image of the on a span element with classname <code>featured-image</code>:
add_filter( 'wpv-post-featured-image', 'prefix_wrap_featured_image' );
function prefix_wrap_featured_image( $out ) {
$out = sprintf( '<span class="featured-image">%s</span>', $out );
return $out;
}
Filters the output of the {{wpv-post-field}} shortcode
Remember that the filter can take two parameters. If you pass more than one, you need to specify it in your code using the fourth argument:
add_filter( 'wpv-post-field-customfield', 'my_callback_function', 101, 2 );
string $out The output value.
string $meta The value of the custom field following this {{wpv-post-field} shortcode attributes.
This filter must return a string.
More Usage examples
//Add a wrapper around the output of the {{wpv-post-field name="customfield"}}:
add_filter( 'wpv-post-field-customfield', 'prefix_wrap_customfield_field', 20, 2 );
function prefix_wrap_customfield_field( $out, $meta ) {
$out = sprintf( '<span class="custom-field customfield-field">%s</span>', $out );
return $out;
}
Filters the value of the custom field before the {{wpv-post-field}} shortcode output
string $meta The value of the custom field as being returned by the get_post_meta() function
.
This filter must return an array, since the WordPress get_post_meta() function returns an array by default.
More Usage examples
//Return a specific string if the field <em>customfield</em> is not defined:
add_filter( 'wpv-post-field-meta-customfield', 'prefix_empty_customfield_field' );
function prefix_empty_customfield_field( $meta ) {
if ( empty( $meta ) ) {
$meta = array( __('No value') );
}
return $meta;
}
Filters a string being passed to wpv_do_shortcode() before parsing the shortcodes
Views uses a lot of shortcodes, and sometimes we nest them inside other shortcodes to get rich structures. Also, Views has a number of editors – like the Filter or Loop Output editors – that do not get through the natural WordPress filters that expand the shortcodes.
To solve that problem, Views uses the function wpv_do_shortcode() to expand the shortcodes in every output that it renders. This function is just a wrapper for the natural do_shortcode(), with a little extra magic.
This method is helpful in two main areas:
Views uses that wpv_do_shortcode() function in several places. For example:
This means that this filter should be used carefully, because it will have an impact in multiple places.
string $content The content going to be filtered.
This filter must return a string.
More Usage examples
//Change a link hardcoded inside some content rendered inside a View to a new target:
add_filter('wpv-pre-do-shortcode', 'prefix_update_link_target');
function prefix_update_link_target( $content ) {
$contentnew = str_replace( 'http://link-to-old-resource', 'http://link-to-new-resource', $content );
return $contentnew;
}