Difference between revisions of "Tag API before 3.1"

Jump to: navigation, search
(Tag)
 
(21 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Moodle 2.0}}
+
<p class="note">This API has been significantly changed in Moodle 3.1. Please see [[Tag API]]</p>
{| style="border: 1px solid #aaaaff; background-color: #eeeeff; width: 80%; margin: 0 auto 1em auto; padding: .2em; text-align: {{{align|left}}}"
 
|{{{image|}}}
 
| '''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 [{{SERVER}}{{localurl:{{NAMESPACE}}:{{PAGENAME}}|action=history}} 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.
 
|}
 
<noinclude>
 
  
 +
==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 files. 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 overview==
+
==Tag API Usage==
  
The Tag API has been implemented in lib/moodlelib.php.
+
Tags associate a value with an instance of a type of item. In that sense tags are generic, but they can be put to specific uses by creative plugin developers, for example:
 +
* adding tag values to an instance of a forum post;
 +
* adding tag values to an instance of a blog;
 +
* adding tag values to a specific user's profile; or
 +
* associating tag values with specific instances of any identifiable item.
  
====examplefunction()====
+
The follow examples work with tags associated with a specific user for their profile. The examples form a series however the calls demonstrated could happen in isolation. If you read these examples in sequence, you should gain an understanding of the Tag API.
Example function description.
 
  
==Tag API Usage==
+
===Remove tags===
  
===Example===
+
Suppose we want to remove all tags associated with a user.
  
 
<code php>
 
<code php>
$id = mt_rand(1000000000, 9999999999); // Generating a key that is unlikely to be taken
+
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()
 +
</code>
 +
 
 +
===Add a tag===
  
tag_set('foo_user', $id, array()); // Delete all foo_user->$id tags by passing an empty array
+
Now suppose we want to add 'chess' to the list of tags for the given user.
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
+
<code php>
tag_get_tags('foo_user', $id); /*
+
tag_set_add('user', $userId, 'chess'); // Add chess to the list of tags for user->$userId
 +
tag_get_tags('user', $userId);
 +
/*
 
returns: Array
 
returns: Array
 
(
 
(
Line 39: Line 50:
 
)
 
)
 
*/
 
*/
 +
</code>
  
tag_set_delete('foo_user', $id, 'chess'); //Delete the chess tag for foo_user->$id
+
===Delete a tag===
tag_get_tags('foo_user', $id);  // returns an empty array()
 
  
 +
Suppose we want to delete the newly created chess tag.
  
br("");
+
<code php>
tag_set('foo_user', $id, array('table tennis', 'foosball', 'programming')); //Add some more tags for foo_user->$id
+
tag_set_delete('user', $userId, 'chess'); //Delete the chess tag for user->$userId
$tags = tag_get_tags('foo_user', $id); /*
+
tag_get_tags('user', $userId); // returns an empty array()
$tags = Array
+
</code>
 +
 
 +
===Adding a number of tags at once===
 +
 
 +
We could now add 'table tennis', 'foosball' and 'programming' as tags for the given user in a single call.
 +
 
 +
<code php>
 +
tag_set('user', $userId, array('table tennis', 'foosball', 'programming')); //Add some more tags for user->$userId
 +
</code>
 +
 
 +
===Get tags===
 +
 
 +
We may want to check all tags associated with the given user.
 +
 
 +
<code php>
 +
$tags = tag_get_tags('user', $userId);
 +
/*
 +
$tags value is: Array
 
(
 
(
 
     [15] => stdClass Object
 
     [15] => stdClass Object
Line 81: Line 110:
 
)
 
)
 
*/
 
*/
 +
</code>
 +
 +
===Make a tag official===
 +
 +
We could make the first element from the last example (the table tennis tag) an official tag.
  
 +
<code php>
 
$firstTagKey = key($tags); // Grab the first key (which happens to be the key for table tennis).
 
$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  
+
if($firstTagKey) {
// output only official foo_user->$id tags
+
    tag_type_set($firstTagKey, 'official'); // Make table tennis an official tag
tag_get_tags('foo_user', $id, 'official'); /*
+
</code>
 +
 
 +
===Get official tags===
 +
 
 +
We can output official tags for the given user.
 +
 
 +
<code php>
 +
tag_get_tags('user', $userId, 'official');
 +
/*
 
Returns: Array
 
Returns: Array
 
(
 
(
Line 100: Line 143:
 
)
 
)
 
*/
 
*/
 +
</code>
  
// Set a description for the table tennis tag.
+
===Set a description===
 +
 
 +
We could now set a description for the table tennis tag.
 +
 
 +
<code php>
 
tag_description_set($firstTagKey, '<p>Another name for <strong><em>wiff-waff"</em></strong></p>', FORMAT_HTML);
 
tag_description_set($firstTagKey, '<p>Another name for <strong><em>wiff-waff"</em></strong></p>', FORMAT_HTML);
 +
</code>
 +
 +
===Get details of a specific tag===
 +
 +
We can get the details of the table tennis tag.
 +
 +
The last parameter is a filter which allows you to specify with fields you wish to have returned. Setting it to an asterisk acts as a wildcard and returns everything.
 +
 +
<code php>
 +
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
 +
)
 +
*/
 +
</code>
  
// Output a tag cloud for all tags in the system.
+
===Output a tag cloud===
 +
 
 +
We can output a tag cloud for all tags in the system.
 +
 
 +
<code php>
 
tag_print_cloud();
 
tag_print_cloud();
 
</code>
 
</code>
Line 132: Line 208:
 
| varchar(255)
 
| varchar(255)
 
| null
 
| null
| the name of the tag
+
| The name of the tag
 
|-
 
|-
 
| rawname
 
| rawname
 
| varchar(255)
 
| varchar(255)
 
|
 
|
| a version of the name which has been normalised with functions such as clean_param and strtolower
+
| A version of the name which has been normalised with functions such as clean_param and strtolower
 
|-
 
|-
 
| tagtype
 
| tagtype
 
| varchar(255) NULL  
 
| varchar(255) NULL  
 
| 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
 
| description
 
| text NULL  
 
| text NULL  
 
|
 
|
| a description of the tag. It's format is specified by the descriptionformat field of this table
+
| A description of the tag. It's format is specified by the descriptionformat field of this table
 
|-
 
|-
 
| descriptionformat
 
| descriptionformat
 
| tinyint(2) unsigned
 
| tinyint(2) unsigned
 
| 0
 
| 0
| specifies the MOODLE TEXT format of the description (see: https://docs.moodle.org/dev/Text_formats_2.0#Database_structure)
+
| Specifies the MOODLE TEXT format of the description (see: https://docs.moodle.org/dev/Text_formats_2.0#Database_structure)
 
|-
 
|-
 
| flag
 
| flag
Line 202: Line 278:
 
| int(10)
 
| int(10)
 
|
 
|
|
+
| See http://tracker.moodle.org/browse/MDL-31150
 
|-
 
|-
 
| timemodified
 
| timemodified
 
| int(10)
 
| int(10)
 
| 0
 
| 0
|
+
| The time that the tag instace was last updated.
 
|}
 
|}
  
 
==See also==
 
==See also==
 +
 +
* [[Core APIs]]
 +
 +
[[Category:API]]

Latest revision as of 11:36, 18 May 2016

This API has been significantly changed in Moodle 3.1. Please see Tag API

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 files. 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

Tags associate a value with an instance of a type of item. In that sense tags are generic, but they can be put to specific uses by creative plugin developers, for example:

  • adding tag values to an instance of a forum post;
  • adding tag values to an instance of a blog;
  • adding tag values to a specific user's profile; or
  • associating tag values with specific instances of any identifiable item.

The follow examples work with tags associated with a specific user for their profile. The examples form a series however the calls demonstrated could happen in isolation. If you read these examples in sequence, you should gain an understanding of the Tag API.

Remove tags

Suppose we want to 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 a tag

Now suppose we want to 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 a tag

Suppose we want to 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()

Adding a number of tags at once

We could now 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

Get tags

We may want to check all tags associated with the given user.

$tags = tag_get_tags('user', $userId);
/*
$tags value is: 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 a tag official

We could 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).
if($firstTagKey) {
    tag_type_set($firstTagKey, 'official'); // Make table tennis an official tag

Get official tags

We can 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

We could now 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);

Get details of a specific tag

We can get the details of the table tennis tag.

The last parameter is a filter which allows you to specify with fields you wish to have returned. Setting it to an asterisk acts as a wildcard and returns everything.

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

We can 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