Database¶

Adding content¶

By passing along the group as container_guid via a hidden input field, you can use a single form and action to add both user and group content.

Use can_write_to_container to determine whether or not the current user has the right to add content to a group.

Be aware that you will then need to pass the container GUID or username to the page responsible for posting and the accompanying value, so that this can then be stored in your form as a hidden input field, for easy passing to your actions. Within a “create” action, you’ll need to take in this input field and save it as a property of your new element (defaulting to the current user’s container):

$user = elgg_get_logged_in_user_entity();
$container_guid = (int)get_input('container_guid');
if ($container_guid) {
    if (!can_write_to_container($user->guid, $container_guid)) {
        // register error and forward
    }
} else {
    $container_guid = elgg_get_logged_in_user_guid();
}

$object = new ElggObject;
$object->container_guid = $container_guid;

...

$container = get_entity($container_guid);
forward($container->getURL());

Usernames and page ownership¶

Groups have a simulated username of the form group:GUID, which you can get the value of by checking $group->username. If you pass this username to a page on the URL line as part of the username variable (i.e., /yourpage?username=group:nnn), Elgg will automatically register that group as being the owner of the page (unless overridden).

Juggling users and groups¶

In fact, [[Engine/DataModel/Entities/ElggGroup|ElggGroup]] simulates most of the methods of [[Engine/DataModel/Entities/ElggUser|ElggUser]]. You can grab the icon, name etc using the same calls, and if you ask for a group’s friends, you’ll get its members. This has been designed specifically for you to alternate between groups and users in your code easily.

Menu options¶

*This section is deprecated as of Elgg 1.8*

The final piece of the puzzle, for default groups, is to add a link to your functionality from the group’s profile. Here we’ll use the file plugin as an example.

This involves creating a view within your plugin - in this case file/menu - which will extend the group’s menu. File/menu consists of a link within paragraph tags that points to the file repository of the page_owner():

<p>
  <a href="<?php echo $vars['url']; ?>pg/file/<?php echo page_owner_entity()->username; ?>">
    <?php echo elgg_echo("file"); ?>
  </a>
</p>

You can then extend the group’s menu view with this one, within your plugin’s input function (in this case file_init):

extend_view('groups/menu/links', 'file/menu');

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)

Adding metadata¶

To add a piece of metadata to an entity, just call:

$entity->metadata_name = $metadata_value;

For example, to add a date of birth to a user:

$user->dob = $dob_timestamp;

Or to add a couple of tags to an object:

$object->tags = array('tag one', 'tag two', 'tag three');

When adding metadata like this:

• The owner is set to the currently logged-in user
• Access permissions are inherited from the entity
• Reassigning a piece of metadata will overwrite the old value

This is suitable for most purposes. Be careful to note which attributes are metadata and which are built in to the entity type that you are working with. You do not need to save an entity after adding or updating metadata. You do need to save an entity if you have changed one of its built in attributes. As an example, if you changed the access id of an ElggObject, you need to save it or the change isn’t pushed to the database.

Reading metadata¶

To retrieve metadata, treat it as a property of the entity:

$tags_value = $object->tags;

Note that this will return the absolute value of the metadata. To get metadata as an ElggMetadata object, you will need to use the methods described in the finer control section below.

If you stored multiple values in this piece of metadata (as in the “tags” example above), you will get an array of all those values back. If you stored only one value, you will get a string or integer back. Storing an array with only one value will return a string back to you. E.g.

$object->tags = array('tag');
$tags = $object->tags;
// $tags will be the string "tag", NOT array('tag')

To always get an array back, simply cast to an array;

$tags = (array)$object->tags;

Adding metadata¶

If you need more control, for example to assign an access ID other than the default, you can use the create_metadata function, which is defined as follows:

function create_metadata(
    $entity_guid,           // The GUID of the parent entity
    $name,                  // The name of the metadata (eg 'tags')
    $value,                 // The metadata value
    $value_type,            // Currently either 'string' or 'integer'
    $owner_guid,            // The owner of the metadata
    $access_id = 0,         // The access restriction
    $allow_multiple = false // Do we have more than one value?
    )

For single values, you can therefore write metadata as follows (taking the example of a date of birth attached to a user):

create_metadata($user_guid, 'dob', $dob_timestamp, 'integer', $_SESSION['guid'], $access_id);

For multiple values, you will need to iterate through and call create_metadata on each one. The following piece of code comes from the profile save action:

$i = 0;
foreach ($value as $interval) {
    $i++;
    $multiple = ($i != 1);
    create_metadata($user->guid, $shortname, $interval, 'text', $user->guid, $access_id, $multiple);
}

Note that the allow multiple setting is set to false in the first iteration and true thereafter.

Reading metadata¶

elgg_get_metadata is the best function for retrieving metadata as ElggMetadata objects:

E.g., to retrieve a user’s DOB

elgg_get_metadata(array(
    'metadata_name' => 'dob',
    'metadata_owner_guid' => $user_guid,
));

Or to get all metadata objects:

elgg_get_metadata(array(
    'metadata_owner_guid' => $user_guid,
    'limit' => 0,
));

“Appending” metadata¶

Note that you cannot “append” values to metadata arrays as if they were normal php arrays. For example, the following will not do what it looks like it should do.

$object->tags[] = "tag four";

Trying to store hashmaps¶

Elgg does not support storing ordered maps (name/value pairs) in metadata. For example, the following does not work as you might first expect it to:

// Won't work!! Only the array values are stored
$object->tags = array('one' => 'a', 'two' => 'b', 'three' => 'c');

You can instead store the information like so:

$object->one = 'a';
$object->two = 'b';
$object->three = 'c';

Storing GUIDs in metadata¶

Though there are some cases to store entity GUIDs in metadata, Relationships are a much better construct for relating entities to each other.

Creating a relationship¶

E.g. to establish that “$user is a fan of $artist” (user is the subject, artist is the target):

// option 1
$success = add_entity_relationship($user->guid, 'fan', $artist->guid);

// option 2
$success = $user->addRelationship($artist->guid, 'fan');

This triggers the event [create, relationship], passing in the created ElggRelationship object. If a handler returns false, the relationship will not be created and $success will be false.

Verifying a relationship¶

E.g. to verify that “$user is a fan of $artist”:

if (check_entity_relationship($user->guid, 'fan', $artist->guid)) {
    // relationship exists
}

Note that, if the relationship exists, check_entity_relationship() returns an ElggRelationship object:

$relationship = check_entity_relationship($user->guid, 'fan', $artist->guid);
if ($relationship) {
    // use $relationship->id or $relationship->time_created
}

Deleting a relationship¶

E.g. to be able to assert that “$user is no longer a fan of $artist”:

$was_removed = remove_entity_relationship($user->guid, 'fan', $artist->guid);

This triggers the event [delete, relationship], passing in the associated ElggRelationship object. If a handler returns false, the relationship will remain, and $was_removed will be false.

Other useful functions:

• delete_relationship() : delete by ID
• remove_entity_relationships() : delete those relating to an entity (note: in versions before Elgg 1.9, this did not trigger delete events)

Finding relationships and related entities¶

Below are a few functions to fetch relationship objects and/or related entities. A few are listed below:

• get_entity_relationships() : fetch relationships by subject or target entity
• get_relationship() : get a relationship object by ID
• elgg_get_entities_from_relationship() : fetch entities in relationships in a variety of ways

E.g. retrieving users who joined your site in January 2014.

$entities = elgg_get_entities_from_relationship(array(
    'relationship' => 'member_of_site',
    'relationship_guid' => elgg_get_site_entity()->guid,
    'inverse_relationship' => true,

    'relationship_created_time_lower' => 1388534400, // January 1st 2014
    'relationship_created_time_upper' => 1391212800, // February 1st 2014
));

Pre-defined access controls¶

• ACCESS_PRIVATE (value: 0) Private.
• ACCESS_LOGGED_IN (value: 1) Logged in users.
• ACCESS_PUBLIC (value: 2) Public data.
• ACCESS_FRIENDS (value: -2) Owner and his/her friends.

User defined access controls¶

You may define additional access groups and assign them to an entity, annotation or metadata. A number of functions have been defined to assist you; see the access library reference for more information.

Table: entities¶

This is the main Entities table containing Elgg users, sites, objects and groups. When you first install Elgg this is automatically populated with your first site.

It contains the following fields:

• guid An auto-incrementing counter producing a GUID that uniquely identifies this entity in the system.
• type The type of entity - object, user, group or site
• subtype A link to the entity_subtypes table.
• owner_guid The GUID of the owner’s entity.
• site_guid The site the entity belongs to.
• container_guid The GUID this entity is contained by - either a user or a group.
• access_id Access controls on this entity.
• time_created Unix timestamp of when the entity is created.
• time_updated Unix timestamp of when the entity was updated.
• enabled If this is ‘yes’ an entity is accessible, if ‘no’ the entity has been disabled (Elgg treats it as if it were deleted without actually removing it from the database).

Table: entity_subtypes¶

This table contains entity subtype information:

• id A counter.
• type The type of entity - object, user, group or site.
• subtype The subtype name as a string.
• class Optional class name if this subtype is linked with a class

Table: metadata¶

This table contains Metadata, extra information attached to an entity.

• id A counter.
• entity_guid The entity this is attached to.
• name_id A link to the metastrings table defining the name table.
• value_id A link to the metastrings table defining the value.
• value_type The value class, either text or an integer.
• owner_guid The owner GUID of the owner who set this item of metadata.
• access_id An Access controls on this item of metadata.
• time_created Unix timestamp of when the metadata is created.
• enabled If this is ‘yes’ an item is accessible, if ‘no’ the item has been deleted.

Table: annotations¶

This table contains Annotations, this is distinct from Metadata.

• id A counter.
• entity_guid The entity this is attached to.
• name_id A link to the metastrings table defining the type of annotation.
• value_id A link to the metastrings table defining the value.
• value_type The value class, either text or an integer.
• owner_guid The owner GUID of the owner who set this item of metadata.
• access_id An Access controls on this item of metadata.
• time_created Unix timestamp of when the metadata is created.
• enabled If this is ‘yes’ an item is accessible, if ‘no’ the item has been deleted.

Table: relationships¶

This table defines Relationships, these link one entity with another.

• guid_one The GUID of the subject entity.
• relationship The type of the relationship.
• guid_two The GUID of the target entity.

Table: objects_entity¶

Extra information specifically relating to objects. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata.

Table: sites_entity¶

Extra information specifically relating to sites. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata.

Table: users_entity¶

Extra information specifically relating to users. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata.

Table: groups_entity¶

Extra information specifically relating to groups. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata.

Table: metastrings¶

Metastrings contain the actual string of metadata which is linked to by the metadata and annotations tables.

This is to avoid duplicating strings, saving space and making database lookups more efficient.