We're rewriting our docs. This page has been ported to github. Join the effort!
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:
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 = "" // 'text' or 'integer' )
For example, to leave a comment on an entity, you might call:
$entity->annotate('comment', $comment_text, $entity->access_id);
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
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)