Codex Home → Developer Resources → Using bp_parse_args() to filter BuddyPress template loops

Using bp_parse_args() to filter BuddyPress template loops

Prologue

In the past, it has been extremely difficult to filter any BuddyPress template loop.

For example, let’s say I wanted all activity loops to show the last five entries instead of the default of 20. It was possible, but basically you’d either have to requery the activity loop to grab the last five entries and override the 'bp_has_activities' filter or override the activity SQL statement using the 'bp_activity_paged_activities_sql' filter.

Both methods are totally not cool.

Introducing bp_parse_args()!

The introduction of the bp_parse_args() function in BuddyPress 2.0 makes this way simpler. Let’s take a look at the bp_has_activities() loop with the bp_parse_args() function:
https://buddypress.trac.wordpress.org/browser/tags/2.0/bp-activity/bp-activity-template.php#L525

Once you’ve analyzed that a bit, let’s move on to the specific usage of bp_parse_args() in the bp_has_activities() loop:

$r = bp_parse_args( $args, $defaults, 'has_activities' );

In particular:

The first argument, $args, are the parameters for the activity loop initially passed by bp_has_activities().
The second argument, $defaults, are some default parameters for the activity loop that are used if the $args variable does not contain them.
The third argument, 'has_activities', is a unique identifier used for this instance of bp_parse_args(). More on this later.

Now that you know how bp_parse_args() is used in bp_has_activites(), let’s analyze the bp_parse_args() function and how we can use this to our advantage.

bp_parse_args() in depth

The bp_parse_args() function can be found here:
https://buddypress.trac.wordpress.org/browser/branches/2.0/bp-core/bp-core-functions.php#L205

In this function, there are two filters:

'bp_before_{$filter_key}_parse_args' – Allows you to filter the initial arguments, $args.
'bp_after_{$filter_key}_parse_args' – Allows you to filter the arguments after $args has been merged with $defaults.

You’re probably wondering what $filter_key is. $filter_key is the third argument from bp_parse_args().

In our case, it is 'has_activities'.

So if I wanted to filter the activity loop parameters, the filters would look like this:

'bp_before_has_activities_parse_args'
'bp_after_has_activities_parse_args'

Now that we’ve taken a look at the bp_parse_args() function and how it applies filters to the arguments. Let’s actually write our override filter!

Filtering bp_parse_args()

Let’s go back to the original issue. I want to filter all activity loops to show only the last five entries instead of the default of 20.

Using the 'bp_after_has_activities_parse_args' filter that we’ve determined above, let’s write our override function:

// Fetch only the last five entries for all activity loops
function my_bp_activities_per_page_5( $retval ) {
	$retval['per_page'] = 5;

	return $retval;
}
add_filter( 'bp_after_has_activities_parse_args', 'my_bp_activities_per_page_5' );

So what did we just do? We’re overriding the 'per_page' parameter so only the last five entries are fetched instead of the default of 20. It’s as simple as that!

Note that this overrides all activity loops across BuddyPress. What if I only wanted to fetch the last five entries only on a user’s activity page? Easy, just add your conditionals:

function my_bp_activities_per_page_5_on_user_activity( $retval ) {
	// only fetch the last five entries if we're on a user's activity page
	if ( bp_is_user_activity() ) {
		$retval['per_page'] = 5;
	}

	return $retval;
}
add_filter( 'bp_after_has_activities_parse_args', 'my_bp_activities_per_page_5_on_user_activity' );

You can get uber-creative by filtering all the other parameters in the activity loop:
https://buddypress.trac.wordpress.org/browser/tags/2.2.1/src/bp-activity/bp-activity-template.php#L442

Conclusion

Now that you know how to use the bp_parse_args() function, you should be able to easily filter any BuddyPress template loop!

For convenience, here are the other template loops using bp_parse_args():

BuddyPress Codex

Using bp_parse_args() to filter BuddyPress template loops

Prologue

Introducing bp_parse_args()!

bp_parse_args() in depth

Filtering bp_parse_args()

Conclusion

Contents

Article Contributors

Want to help?