Tag API before 3.1

Revision as of 18:30, 23 January 2012 by Gerard Caulfield (talk | contribs) (Example)

Jump to: navigation, search

Moodle 2.0


WORK IN PROGRESS: I've currently just created a template, so please ignore this page until this wip notices has been removed. However, you are free to help in the construction of this page by improving it. Please review the edit history if you would like to contact the user who put up this notice. If this article has not been edited by that user in a while, please remove this template.


Tag API overview

The Tag API allows you to assign labels to information in Moodle. This makes finding this information easier and also facilitates the grouping of similar information. The Tag API allows you to create, modify, delete and search tags in the Moodle system. The main of tag related functions can be found in the tag/lib.php and tab/locallib.php. For a through overview of all of the functions available for working with Tags please see SYSTEM X, however the following examples should give you a general understanding of how to get started with tags.

Tag API Usage

Example

require_once($CFG->dirroot.'/tag/locallib.php');
 
$id = mt_rand(1000000000, 9999999999); // Generating a key that is unlikely to be taken
 
tag_set('foo_user', $id, array()); // Delete all foo_user->$id tags by passing an empty array
tag_get_tags('foo_user', $id); // returns an empty array()
 
tag_set_add('foo_user', $id, 'chess'); // Add chess to the list of tags for foo_user->$id
tag_get_tags('foo_user', $id); /*
returns: Array
(
    [14] => stdClass Object
        (
            [id] => 14
            [tagtype] => default
            [name] => chess
            [rawname] => chess
            [flag] => 0
            [ordering] => 0
        )
)
*/
 
tag_set_delete('foo_user', $id, 'chess'); //Delete the chess tag for foo_user->$id
tag_get_tags('foo_user', $id);  // returns an empty array()
 
 
br("");
tag_set('foo_user', $id, array('table tennis', 'foosball', 'programming')); //Add some more tags for foo_user->$id
$tags = tag_get_tags('foo_user', $id); /*
$tags = Array
(
    [15] => stdClass Object
        (
            [id] => 15
            [tagtype] => official
            [name] => table tennis
            [rawname] => table tennis
            [flag] => 0
            [ordering] => 0
        )
 
    [16] => stdClass Object
        (
            [id] => 16
            [tagtype] => default
            [name] => foosball
            [rawname] => foosball
            [flag] => 0
            [ordering] => 1
        )
 
    [17] => stdClass Object
        (
            [id] => 17
            [tagtype] => default
            [name] => programming
            [rawname] => programming
            [flag] => 0
            [ordering] => 2
        )
 
)
*/
 
$firstTagKey = key($tags); // Grab the first key (which happens to be the key for table tennis).
tag_type_set($firstTagKey, 'official'); // Make table tennis an official tag 
// output only official foo_user->$id tags 
tag_get_tags('foo_user', $id, 'official'); /*
Returns: Array
(
    [15] => stdClass Object
        (
            [id] => 15
            [tagtype] => official
            [name] => table tennis
            [rawname] => table tennis
            [flag] => 0
            [ordering] => 0
        )
 
)
*/
 
// Set a description for the table tennis tag.
tag_description_set($firstTagKey, '<p>Another name for <strong><em>wiff-waff"</em></strong></p>', FORMAT_HTML);
 
// Grab the details of the table tennis field
tag_get('name', 'table tennis', '*'); /*
Returns: stdClass Object
(
    [id] => 15
    [userid] => 2
    [name] => table tennis
    [rawname] => table tennis
    [tagtype] => official
    [description] => <p>Another name for <strong><em>wiff-waff"</em></strong></p>
    [descriptionformat] => 1
    [flag] => 0
    [timemodified] => 1327343334
)
*/
 
 
// Output a tag cloud for all tags in the system.
tag_print_cloud();

Tag API database tables

Tag

This table holds all of the tags which are currently available in the system.

Field Type Default Info
id int(10) auto-incrementing The unique ID for this Tag.
userid int(10) The user that the Tag belongs to
name varchar(255) null The name of the tag
rawname varchar(255) A version of the name which has been normalised with functions such as clean_param and strtolower
tagtype varchar(255) NULL null Specifies the type of the tag. Currently there are only two types of tags, official and default. Official is used for tags that have been accepted by administrators.
description text NULL A description of the tag. It's format is specified by the descriptionformat field of this table
descriptionformat tinyint(2) unsigned 0 Specifies the MOODLE TEXT format of the description (see: https://docs.moodle.org/dev/Text_formats_2.0#Database_structure)
flag smallint(4) 0 Used to identify tags that have been marked as inappropriate
timemodified bigint(10) The time that the tag was last updated.

Tag_Instance

This table is use to record the instances of each tag's use. It has a many to one relationship with the tag table shown above.

Field Type Default Info
id int(10) auto-incrementing The unique ID for this tag instance
tagid int(10) The foreign key which relates to the primary tagid key in the tag table
itemtype varchar(255) null The category that the tag belongs to (eg. user, course)
itemid int(10) The ID of the particular item you are linking to. So for an itemtype of user you would use the user's ID for the itemid.
tiuserid int(10) 0 The userid of the user who created the tag instance.
ordering int(10) See http://tracker.moodle.org/browse/MDL-31150
timemodified int(10) 0 The time that the tag instace was last updated.

See also