Elgg Entities

As mentioned, Elgg defines four basic entity types, ElggSite, ElggUser, ElggObject and ElggGroup. As an example we'll focus on creating an object.

Creating an object

To create an object in your code, you need to instantiate an ElggObject. Setting data is simply a matter of adding instance variables or properties. The built-in properties are:

• guid Set automatically
• owner_guid The owning user's guid
• site_guid The owning site's guid. This is set automatically when an instance of ElggObject gets created)
• subtype A single-word arbitrary string that defines what kind of object it is, for example blog
• access_id An integer representing the access level of the object
• title The title of the object
• description The description of the object

The object subtype is a special property. This is an arbitrary string that describes what the object is. For example, if you were writing a blog plugin, your subtype string might be blog. It's a good idea to make this unique, so that other plugins don't accidentally try and use the same subtype. For the purposes of this document, let's assume we're building a simple forum. Therefore, the subtype will be forum:

$object = new ElggObject();
 
$object->subtype = "forum";
 
$object->access_id = 2;
 
$object->save();

access_id is another important property. If you don't set this, your object will be private, and only the creator user will be able to see it. The special values for access_id are: 0 (private), 1 (logged in users only), 2 (public).

Saving the object will automatically populate the $object->id property if successful. If you change any more base properties, you can call $object->save() again, and it will update the database for you. Once you've saved your object to the database – and only then – you can set metadata on it. Metadata has an arbitrary name and a value, and can be set just like a standard property. Let's say we want to set the parent GUID of our forum post to be 0.

$object->parent_guid = 0;

If you assign an array, all the values will be set for that metadata. This is how, for example, you set tags.

Loading an object

If you know the GUID

If you know the GUID of your object, you can simply load it with get_entity($guid), where $guid is the object GUID. The object it returns will be autopopulated with the object's properties, which can be read with $object->parent_guid to retrieve the parent GUID we had set in the previous example.

But what if you don't know the GUID? There are several options.

Get users by user, subtype or site

If you know the user ID you want to get objects for, or the subtype, or the site, you have several options. The easiest is probably to call the procedural function get_entities($entity_type, $subtype, $owner_guid) where entity type is user, object or site. You can leave user_id to 0 to get all objects and leave subtype or type blank to get objects of all types/subtypes. Limit defaults to 10; offset to 0. This will return an array of ElggEntity objects that you can iterate through.

If you already have an ElggUser – eg $_SESSION['user'], which always has the current user's object when you're logged in – you can simply use $object_array = $user->getObjects($subtype, $limit, $offset).

But what about getting objects with a particular piece of metadata? Let's say we want everything with a parent_guid of 0.

Get objects by metadata

Currently two functions are available to retrieve entities by metadata, get_entities_from_metadata() and get_entities_from_metadata_multi(). The former can be used to get entities based on a single piece of metadata, the latter can handle multiple metedata values. Following our example, to retrieve all entities with parent_guid of 0, you would use the following call:

get_entities_from_metadata('parent_guid', 0, 'object');

This will return an array of entities you can iterate through.

Displaying entities

In order for entities to be displayed in listing functions you need to provide a view for the entity in the views system.

To display an entity, create a view EntityType/subtype where EntityType is one of the following:

• object: for entities derived from ElggObject
• user: for entities derived from ElggUser
• site: for entities derived from ElggSite
• group: for entities derived from ElggGroup

A default view for all entities has already been created, this is called EntityType/default.

Entity Icons

Entities all have a method called ->getIcon($size).

This method accepts a $size variable, which can be either 'large', 'medium', 'small' or 'tiny'.

The method triggers a plugin hook - 'entity:icon:url'. This is passed the following parameters:

• 'entity' : The entity in question
• 'viewtype' : The type of view e.g. 'default' or 'mobile'.
• 'size' : The size.

The hook should return a url.

Hooks have already been defined, and will look in the following places for default values:

• views/$viewtype/graphics/icons/$type/$subtype/$size.png
• views/$viewtype/graphics/icons/$type/default/$size.png
• views/$viewtype/graphics/icons/default/$size.png

Where

• $viewtype : The type of view e.g. 'default' or 'mobile'.
• $type : The type of entity - group, site, user, object.
• $subtype : Subtype of $type, e.g. blog, page.
• $size : Size - 'large', 'medium', 'small' or 'tiny'

Adding, reading and deleting annotations

Annotations could for example be comments and ratings. To annotate an entity you can use the object's annotate(), which expects four parameters, name, which is the name of the annotation type, value, which is the value of the annotation, access_id and owner_guid. For example, to add a comment to a blog post you could use:

$entity->annotate('comments', 'Hi!  I'm making a comment.', 2);

To retrieve the comments on the blog post, use $blogpost->getAnnotations('comments') and if you want to delete an annotation, you can operate on the ElggAnnotation class, eg $annotation->delete().

Retrieving an annotation can be done with get_annotation() if you have the annotation's ID. Deleting it is simply a matter of calling the delete() function of the annotation object. If you delete an ElggEntity, whether it be a site, user, object or group all its metadata and annotations will be automatically deleted.

Also see

• ElggEntity class reference

elggentity, entities

Last updated 520 days ago by Dave