Modifying the entries displayed in a View
Note: this page is for developers. To filter which entries a View shows without code, use Advanced Filtering.
These hooks change which entries a View shows. Each one runs at a different stage of the query, so pick the first one in the table that can do the job. The GravityKit developer docs list each hook’s parameters.
Choose a hook #
| Hook | Use it to |
|---|---|
gravityview/view/query (action) | Add a condition every entry must meet, or change a condition GravityView built. It runs before the query, so the entry count and page links stay correct. |
gk/gravityview/search/request/search-arguments (filter) | Change or remove what a visitor searched for. It runs while GravityView reads the search. |
gravityview_search_operator (filter) | Change the comparison a search uses. It runs while GravityView builds the search. |
gravityview/view/entries (filter) | Apply logic that SQL can’t express. It runs after the entries are fetched, so the entry count and page links change with what you return. Use this one last. |
Add a condition every entry must meet #
gravityview/view/query is an action that gives you the GF_Query object by reference, so you change it in place and return nothing. This example limits View 123 to entries whose field 5 is active. The condition applies with or without a Search Bar, and a visitor’s search can only narrow the results further.
add_action( 'gravityview/view/query', function ( &$query, $view, $request ) {
if ( ! $view || 123 !== $view->ID ) {
return;
}
$condition = new GF_Query_Condition(
new GF_Query_Column( 5, $view->form->ID ),
GF_Query_Condition::EQ,
new GF_Query_Literal( 'active' )
);
// Keep the conditions GravityView already built, and add yours.
$where = $query->_introspect()['where'];
$query->where( GF_Query_Condition::_and( $where, $condition ) );
}, 20, 3 );Note: Where to put code samples explains how to add these snippets to your site.
Warning: keep $query->_introspect()['where'] in the condition. Calling $query->where() with only your own condition throws away the View’s other conditions, including Advanced Filter rules and approval status.
Change what a visitor searched for #
gk/gravityview/search/request/search-arguments is a filter over the search GravityView reads from the page address, before the search runs. This example turns a search for KC on field 2 into a search for Kansas City:
add_filter(
'gk/gravityview/search/request/search-arguments',
function ( $arguments, $request, $view ) {
if ( ! $view || 123 !== $view->ID ) {
return $arguments;
}
// A search for "KC" on field 2 looks for Kansas City instead.
$value = $arguments['filter_2']['value'] ?? '';
if ( 'KC' === $value ) {
$arguments['filter_2']['value'] = 'Kansas City';
}
return $arguments;
},
10,
3
);The array has one item for each search parameter, keyed by the parameter’s name:
| What the visitor searched | Key in the array | Field the condition applies to |
|---|---|---|
| Field 5 | filter_5 | 5 |
| Input 3 of a multi-part field 5 | filter_5_3 | 5.3 |
| The Search Everything box | gv_search | search_all |
| Entry date range | gv_start and gv_end | entry_date |
| Entry creator | gv_by | created_by |
| Entry ID | gv_id | entry_id |
- The filter runs several times per request, and
$viewisnullon some of those runs. Check it before using it, as the example does. - Return an array. Returning
nullor a string drops the whole search, and the View shows every entry. - GravityView applies a condition only to a field the View’s Search Bar can search: a field listed in the Search Bar, or a field that Search Everything covers when the Search Bar includes it. Other keys are ignored, the same as a
filter_5parameter added to the address by hand. - A condition you add joins the visitor’s search by the Search Bar’s Search Mode. With Match Any Fields, the default, it can widen the results, so use
gravityview/view/queryto limit which entries a View shows.
To ignore what a visitor typed into one search field, remove its key:
add_filter(
'gk/gravityview/search/request/search-arguments',
function ( $arguments, $request, $view ) {
if ( ! $view || 123 !== $view->ID ) {
return $arguments;
}
// Ignore whatever the visitor typed into the field 3 search box.
unset( $arguments['filter_3'] );
return $arguments;
},
10,
3
);Warning: setting operator in this array does not change the comparison. GravityView checks it against the operators the field allows, so a text search stays contains. To change the comparison, use the filter below.
Change how a search compares values #
The gravityview_search_operator filter receives the comparison after GravityView has chosen it, so a new value takes effect on any search field. How to search for an exact match has tested snippets for a whole View and for one field. Check $operator before you return a new one, since forcing is on every comparison breaks date range searches.
Filter entries after they are fetched #
gravityview/view/entries receives a \GV\Entry_Collection with the entries for the current page. To drop some, build a new collection with the entries you want to keep and return it:
add_filter(
'gravityview/view/entries',
function ( $entries, $view = null, $request = null ) {
if ( ! $view instanceof \GV\View || 123 !== $view->ID ) {
return $entries;
}
$keep = new \GV\Entry_Collection();
foreach ( $entries->all() as $entry ) {
// Keep only the entries whose field 5 is "active".
if ( 'active' === $entry['5'] ) {
$keep->add( $entry );
}
}
return $keep;
},
10,
3
);Give the callback default values for $view and $request, and check that $view is a \GV\View, as the example does. GravityEdit’s Inline Edit also runs this filter with two arguments, and a callback that requires three causes a fatal error on Views that have Inline Edit turned on.
The entry count and page links follow what you return. On a View that shows 2 entries per page, this example reports a total of 2 and removes the page links, so visitors have no link to the later pages. Use one of the earlier hooks when SQL can do the job.
Moving from gravityview_fe_search_criteria #
gravityview_fe_search_criteria was deprecated in 2.55. It still runs, so existing code keeps working, and GravityView adds a notice to the WordPress Dashboard when WP_DEBUG is on. The notice names gravityview/view/query as the replacement. Deprecated and renamed hooks lists it with the other renamed hooks.
The right replacement depends on what your callback does.
A callback that adds a condition
Add it with gravityview/view/query, as in the first example on this page. The old filter’s key becomes the field ID in GF_Query_Column, value becomes a GF_Query_Literal, and operator becomes a GF_Query_Condition constant such as EQ or NEQ.
A callback that removes a search condition
Use unset() on gk/gravityview/search/request/search-arguments, as shown in Change what a visitor searched for.
A callback that changes a condition
Rewrite the conditions GravityView built. This example makes a search for NO on field 8 return every entry except those set to SI:
add_action( 'gravityview/view/query', function ( &$query, $view, $request ) {
if ( ! $view || 123 !== $view->ID ) {
return;
}
$rewrite = function ( $condition ) use ( &$rewrite ) {
if ( $condition->expressions ) {
$children = array_map( $rewrite, $condition->expressions );
return GF_Query_Condition::_AND === $condition->operator
? GF_Query_Condition::_and( ...$children )
: GF_Query_Condition::_or( ...$children );
}
$column = $condition->left;
$value = $condition->right;
if (
$column instanceof GF_Query_Column
&& 8 === (int) $column->field_id
&& $value instanceof GF_Query_Literal
&& 'NO' === $value->value
) {
return new GF_Query_Condition(
$column,
GF_Query_Condition::NEQ,
new GF_Query_Literal( 'SI' )
);
}
return $condition;
};
$where = $query->_introspect()['where'];
if ( $where ) {
$query->where( $rewrite( $where ) );
}
}, 20, 3 );- Keep the priority of 20. GravityView’s Search Bar adds its conditions at priority 10, so at the default priority there is nothing to rewrite yet.
- A
NEQcondition also matches entries with no value in that field, so the results include empty entries. - The snippet changes every condition that matches, including an Advanced Filter rule on the same field, even when nobody is searching.