Engine/DataModel/Annotations

Annotations are pieces of data attached to an entity that allow users to leave comments, ratings, or other relevant feedback. In the group forum plugin, each post is an annotation on a topic. A poll plugin might register votes as annotations.

Annotations are stored as instances of the ElggAnnotation class.

Each annotation has:

  • An internal annotation type (like comment)
  • A value (which can be a string or integer)
  • An access permission distinct from the entity it's attached to
  • An owner

Contents

Adding an annotation

The easiest way to annotate is to use the annotate method on an entity, which is defined as: 

function annotate(
                  $name,           // The name of the annotation type (eg 'comment')
                  $value,          // The value of the annotation
                  $access_id = 0,  // The access level of the annotation
                  $owner_id = 0,   // The annotation owner, defaults to current user
                  $vartype = ""    // 'string' or 'integer'
                 )

For example, to leave a comment on an entity, you might call: 

$entity->annotate('comment', $comment_text, $entity->access_id);

Reading annotations

To retrieve annotations on an object, you can call the following method: 

$annotations = $entity->getAnnotations(
                                       $name,    // The type of annotation
                                       $limit,   // The number to return
                                       $offset,  // Any indexing offset
                                       $order,   // 'asc' or 'desc' (default 'asc')
                                      );

If your annotation type largely deals with integer values, a couple of useful mathematical functions are provided: 

$averagevalue = $entity->getAnnotationsAvg($name);  // Get the average value
$total = $entity->getAnnotationsSum($name);         // Get the total value
$minvalue = $entity->getAnnotationsMin($name);      // Get the minimum value
$maxvalue = $entity->getAnnotationsMax($name);      // Get the maximum value

Useful helper functions

Comments

If you want to provide comment functionality on your plugin objects, the following function will provide the full listing, form and actions: 

function elgg_view_comments(ElggEntity $entity)

Also see

Retrieved from "http://docs.elgg.org/wiki/Engine/DataModel/Annotations"

Navigation

Search docs