The latest Elgg 1.0 code changes how the river works slightly from that discussed in my previous article on the subject. These changes are entirely under the hood so they’ll only be noticeable to plugin writers, however it simplifies matters immeasurably and makes it possible to do some quite funky things.

In a nutshell, the river generation function now passes a variable called "statement" to your river views instead of passing the object, event etc as separate values. "statement" is a class called ElggRiverStatement.

Loosely speaking all river items are in the form of “X does something to Y”, where X is usually a user and Y is either an entity or another statement. I borrowed a bit from linguistics, and X is called the Subject and Y is the Object.

Subject, as I said, is the user, so this is easy. The ElggRiverStatement will provide you with a fully created user entity.

The statement “does something to” translates to the event in the system which you will be used to if you’ve implemented plugins for Elgg 1.0 already… so that’s “create”, “update”, etc.

Object will either by an ElggEntity in the case of simple statements like “User X updated their Profile”, or an array which represents compound statements.

What do I mean by compound statements? Well, take the following for example:

“User X is now friends with User Y”

As far as the system is concerned, what you are actually saying is:

“User X created a new friend relationship between User X and User Y”

In terms of language, User X is the Subject and “a new friend relationship between User X and User Y” (yes, the whole thing) is the Object (and yes, before someone jumps in I am aware this is highly simplified!).

I use the terms Subject and Object again in the array, so to take the above example our array would look something like this:

Array (
    "subject" => User X (ElggUser object),
    "relationship" => "friend",
    "object" => User Y (ElggUser object again)
)

If you take the example of adding some metadata (writing a note on a file for example), you’ve got another compound query. You are making the statement:

“User X has created some metadata which relates to File Y”

In this instance “some metadata which relates to File Y” is our Object, and the array returned would look something like this:

Array (
    "subject" => Metadata object,
    "object" => File Y
)

In summary then, the ElggRiverStatement provides a pretty flexible way of representing diverse river statements with a common interface. The entities referenced are provided in full to your view so that you do not have to load them yourself.

Although this is a small change under the hood it makes it possible to do some other cool stuff (which I will discuss a little bit later).