Filtering

Notes on how to use the filtering capabilities of the API.

activity_get_activity() has a very underutilized (meaning non-ui) way of being able to filter out the activity that is pulled form the activity table. That is by way of the second parameter (@param $filters). This often sought after control is indeed within the API, yet since there is not User Interface for it currently, most think the module incapable of being able to filter what is displayed to their users.

I envision a nice little settings UI for users that will allow them to be able to filter their own list of activity (such as facebook allows) but until that task is complete (see: #328437: User filter settings) I'll at least provide some programmer documentation on how to construct some basic filters in order to limit the activity that is displayed. As this concept is understood, I'm sure someone will come up with a way to dynamically create these and allow for a user UI in order to do so.

So let's being with the module's current documentation within the activity.module file.

While somewhat unimaginative (at best) this little piece of information gives you everything you need to be able to start building your own $filter arrays. A more common one that I've had requests for, has been to be able to filter out usernodes. Usernode module turns users into nodes and it serves as a prime example of activity that you do not want to show up in your activity list. When a user is created, updated or deleted this would then show up in your activity list, but maybe you don't want to announce to all of your users that some-guy-out-there just created an account on your site... and then updated their account 20 times... you can see how this might become ugly.

The very quickest way to filter out this kind of data is to simply exclude any and all usernode activity. Since users are now nodes, and you may still want to have other node activity displayed, you can't just disable nodeactivity.module, you need a way to filter node of this type. Luckily, with the $filter parameter, you can now do this.

The filter parameter is essentially a way of targeting fields within the activity table, and saying whether they should be included or not when you go to retrieve the activity from the table. Think of it as an SQL WHERE clause, or even a views filter (if you're on that wavelength ;). So in order to figure out what you want to filter from your results, you need to be familiar with what the fields of the table are. Here's a quick dump of the structure.

So this tells us all of the 'keys' that we can filter by.

_{Just tell us how to do this already!}
Ok, ok... here's the filter, but I'm STILL going to explain a few things afterward. *grumble*

Now let's take this apart a bit so you can understand how this relates to the database table:
'type'
This is the field in the table described above that we are looking for. It holds the name of the module from which we are recording the given activity. So by setting 'exclude' to 'usernode' (you guessed it!) we're not going to show any activity that is of that type. :)

We can further limit this to an 'operation'. The operation field holds the node operation that is being recorded ('insert', 'update', 'delete', etc.) as defined by that particular module (a full list of these can be found in each activity/contrib/[module]activity.module within the hook_info() function).

So as long as you know what you're trying to get, and understand how it is recorded in the table, you just have create the correct filter array and pass this in as the second parameter anytime you call activity_get_activity().

Happy filtering! :-D