River

Elgg natively supports the “river”, an activity stream containing descriptions of activities performed by site members. This page gives an overview of adding events to the river in an Elgg plugin.

Pushing river items

Items are pushed to the activity river through a function call, which you must include in your plugins for the items to appear.

Here we add a river item telling that a user has created a new blog post:

<?php

elgg_create_river_item([
        'view' => 'river/object/blog/create',
        'action_type' => 'create',
        'subject_guid' => $blog->owner_guid,
        'object_guid' => $blog->getGUID(),
]);

All available parameters:

view => STR The view that will handle the river item (must exist)
action_type => STR An arbitrary string to define the action (e.g. ‘create’, ‘update’, ‘vote’, ‘review’, etc)
subject_guid => INT The GUID of the entity doing the action (default: the logged in user guid)
object_guid => INT The GUID of the entity being acted upon
target_guid => INT The GUID of the object entity’s container (optional)
access_id => INT The access ID of the river item (default: same as the object)
posted => INT The UNIX epoch timestamp of the river item (default: now)
annotation_id => INT The annotation ID associated with this river entry (optional)

When an item is deleted or changed, the river item will be updated automatically.

River views

As of Elgg 3.0 the view parameter is no longer required. A fallback logic has been created to check a series of views for you:

/river/{$type}/{$subtype}/{$action_type}: eg. river/object/blog/create only the create action will come to this view
river/{$type}/{$subtype}/default: eg. river/object/blog/default all river activity for object blog will come here
river/{$type}/{$action_type}: eg. river/object/create all create actions for object will come here
river/{$type}/default: eg. river/object/default all actions for all object will come here
river/elements/layout: ultimate fall back view, this should always be called in any of the river views to make a consistent layout

Both type and subtype are based on the type and subtype of the object_guid for which the river item was created.

Summary

If no summary parameter is provided to the river/elements/layout the view will try to create it for you. The basic result will be a text with the text Somebody did something on Object, where Somebody is based on subject_guid and Object is based on object_guid. For both Somebody and Object links will be created. These links are passed to a series of language keys so you can create a meaningfull summary.

The language keys are:

river:{$type}:{$subtype}:{$action_type}: eg. river:object:blog:create
river:{$type}:{$subtype}:default: eg. river:object:blog:default
river:{$type}:{$action_type}: eg. river:object:create
river:{$type}:default: eg. river:object:default

Custom river view

If you wish to add some more information to the river view, like an attachment (image, YouTube embed, etc), you must specify the view when creating the river item. This view MUST exist.

We recommend /river/{type}/{subtype}/{action}, where:

{type} is the entity type of the content we’re interested in (object for objects, user for users, etc)
{subtype} is the entity subtype of the content we’re interested in (blog for blogs, photo_album for albums, etc)
{action} is the action that took place (create, update, etc)

River item information will be passed in an object called $vars['item'], which contains the following important parameters:

$vars['item']->subject_guid The GUID of the user performing the action
$vars['item']->object_guid The GUID of the entity being acted upon

Timestamps etc will be generated for you.

For example, the blog plugin uses the following code for its river view:

$item = elgg_extract('item', $vars);
if (!$item instanceof ElggRiverItem) {
        return;
}

$blog = $item->getObjectEntity();
if (!$blog instanceof ElggBlog) {
        return;
}

$vars['message'] = $blog->getExcerpt();

echo elgg_view('river/elements/layout', $vars);