Tag API before 3.1: Difference between revisions
Line 46: | Line 46: | ||
</code> | </code> | ||
===Add 'table tennis', 'foosball' and 'programming' as tags in a single call=== | ===Add 'table tennis', 'foosball' and 'programming' as tags for the given user in a single call=== | ||
<code php> | <code php> | ||
tag_set('user', $userId, array('table tennis', 'foosball', 'programming')); //Add some more tags for user->$userId | tag_set('user', $userId, array('table tennis', 'foosball', 'programming')); //Add some more tags for user->$userId |
Revision as of 05:38, 15 February 2012
Moodle 2.0
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 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
The follow examples all flow on from one another. If you read them all in sequence you should gain a very good understanding of the Tag API in a short time.
Include the Tag API and remove all tags associated with a user
require_once($CFG->dirroot.'/tag/locallib.php');
// Lets pretend we want to update the tags for a user who has an ID of 9969959299
$userId = 9969959299;
tag_set('user', $userId, array()); // Delete all user->$userId tags by passing an empty array
tag_get_tags('user', $userId); // returns an empty array()
Add chess to the list of tags for the given user
tag_set_add('user', $userId, 'chess'); // Add chess to the list of tags for user->$userId
tag_get_tags('user', $userId); /*
returns: Array
(
[14] => stdClass Object
(
[id] => 14
[tagtype] => default
[name] => chess
[rawname] => chess
[flag] => 0
[ordering] => 0
)
)
- /
Delete the newly created chess tag
tag_set_delete('user', $userId, 'chess'); //Delete the chess tag for user->$userId
tag_get_tags('user', $userId); // returns an empty array()
Add 'table tennis', 'foosball' and 'programming' as tags for the given user in a single call
tag_set('user', $userId, array('table tennis', 'foosball', 'programming')); //Add some more tags for user->$userId
Return all tags associated with the given user
$tags = tag_get_tags('user', $userId); /*
$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
)
)
- /
Make the first element from the last example (the table tennis tag) an official tag
$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 official tags for the given user
tag_get_tags('user', $userId, '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, '
Another name for wiff-waff"
', FORMAT_HTML);
Grab the details of the table tennis tag
tag_get('name', 'table tennis', '*'); /*
Returns: stdClass Object
(
[id] => 15
[userid] => 2
[name] => table tennis
[rawname] => table tennis
[tagtype] => official
[description] =>
Another name for wiff-waff"
[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. |