Tag API

Moodle 3.1

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/classes/tag.php file. For a through overview of all of the functions available for working with Tags please see methods in core_tag_tag, core_tag_collection and core_tag_area classes, however the following examples should give you a general understanding of how to get started with tags.

Tag API usage

When user tags something a tag instance is created in the database linking the item to the actual tag. If tag did not exist before it is created automatically. Do not confuse these two entities - deleting the tag instance does not normally delete tag, however deleting tag deletes all tag instances associated with it.

Developers define tag areas the areas that can be tagged, examples are:

blog posts
courses
users (tags represent user interests)
activity modules
questions
wiki pages

Each tag area is identified by two attributes - component and itemtype. Itemtype must be a name of a table in the database. Component is the core component or plugin responsible for the tagging. This way the same DB table (for example 'user' or 'course') may be independently tagged by several components. Administrator or manager is able to manage the tag areas, collections and tags inside them on the [Manage tags] page. Users are able to search tags and view all items tagged with them that they have access to.

Defining a tag area

First, developer must define the tag areas in the file db/tag.php. This will usually look like:

$tagareas = array(
    array(
        'itemtype' => 'course',
        'component' => 'core',
        'callback' => 'course_get_tagged_courses',
        'callbackfile' => '/course/lib.php',
    ),
);

There are more options such as specifying the default value for "Standard tags", having a fixed collection or excluding from search. They can be found in comments in lib/db/tag.php

After making changes to db/tag.php plugin developer must bump the plugin version in version.php and run upgrade script. This usually applies to any changes in the db/ folder.

Adding tags element to the editing form

After tag area is defined it should appear on "Manage tags" page. Now it is time to allow users to add/change tags when editing the item.

TODO

Displaying tags next to the item

Example of displaying of the tags are user interests on the user profile page. User can see the list of interests, each of them is a link that leads to the page that shows all items tagged with this tag.

Deleting and clearing tags

Cron will automatically remove tag instances that point to non existing items, however it is a good habit to delete tags when the record is deleted.

core_tag_tag::delete_instances($component, $itemtype = null, $contextid = null) - here $component is mandatory in this method, either itemtype or contextid or neither or both can be specified.

Search callback

This is the most difficult part of Tag API. When user searches for the items tagged with a specific tag only the items user has access to must be returned. Running access check on all items can be very costly.

TODO

Advanced usages

Custom plugins may go beyond the standard tags handling and use them without mixing with regular course/user/wiki/blogs tags, hide them from the "Tag search" page and "Tags" block but instead have their own interface to search/categorise using tags. This can be achieved by defining tag collection, make it not searchable and specify a custom URL to link to when the tag is actually displayed. This all can be defined in db/tag.php, see the comments in [lib/db/tag.php]

Documentation