river.rst 2.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475
  1. River
  2. #####
  3. Elgg natively supports the "river", an activity stream containing descriptions
  4. of activities performed by site members. This page gives an overview of adding
  5. events to the river in an Elgg plugin.
  6. Pushing river items
  7. ===================
  8. Items are pushed to the activity river through a function call, which you must
  9. include in your plugins for the items to appear.
  10. Here we add a river item telling that a user has created a new blog post:
  11. .. code:: php
  12. <?php
  13. elgg_create_river_item(array(
  14. 'view' => 'river/object/blog/create',
  15. 'action_type' => 'create',
  16. 'subject_guid' => $blog->owner_guid,
  17. 'object_guid' => $blog->getGUID(),
  18. ));
  19. All available parameters:
  20. * ``view`` => STR The view that will handle the river item (must exist)
  21. * ``action_type`` => STR An arbitrary string to define the action (e.g. 'create', 'update', 'vote', 'review', etc)
  22. * ``subject_guid`` => INT The GUID of the entity doing the action
  23. * ``object_guid`` => INT The GUID of the entity being acted upon
  24. * ``target_guid`` => INT The GUID of the the object entity's container (optional)
  25. * ``access_id`` => INT The access ID of the river item (default: same as the object)
  26. * ``posted`` => INT The UNIX epoch timestamp of the river item (default: now)
  27. * ``annotation_id`` => INT The annotation ID associated with this river entry (optional)
  28. When an item is deleted or changed, the river item will be updated automatically.
  29. River views
  30. ===========
  31. In order for events to appear in the river you need to provide a corresponding
  32. :doc:`view <views>` with the name specified in the function above.
  33. We recommend ``/river/{type}/{subtype}/{action}``, where:
  34. * {type} is the entity type of the content we're interested in (``object`` for objects, ``user`` for users, etc)
  35. * {subtype} is the entity subtype of the content we're interested in (``blog`` for blogs, ``photo_album`` for albums, etc)
  36. * {action} is the action that took place (''create'', ''update'', etc)
  37. River item information will be passed in an object called ``$vars['item']``, which contains the following important parameters:
  38. * ``$vars['item']->subject_guid`` The GUID of the user performing the action
  39. * ``$vars['item']->object_guid`` The GUID of the entity being acted upon
  40. Timestamps etc will be generated for you.
  41. For example, the blog plugin uses the following code for its river view:
  42. .. code:: php
  43. <?php
  44. $object = $vars['item']->getObjectEntity();
  45. $excerpt = $object->excerpt ? $object->excerpt : $object->description;
  46. $excerpt = strip_tags($excerpt);
  47. $excerpt = elgg_get_excerpt($excerpt);
  48. echo elgg_view('river/elements/layout', array(
  49. 'item' => $vars['item'],
  50. 'message' => $excerpt,
  51. ));