Tag API 3 Specification
This page is a specification and API not have been implemented exactly this way. Please see Tag API for actual documentation
Tag API 3
See also MDL-50851
Summary
This is designed to make the Tag API in Moodle more flexible. The main changes:
- allow to use different tag collections for different tag areas (for example, user interests would be a completely different set of keywords than blog posts)
- allow to enable/disable tagging in individual areas, not just one-for-all global $CFG->usetags setting
- introduce callbacks in the components that will be responsible for displaying entries related to the tag
Other related changes:
- coursetags is no longer an option in block_tags, courses are now tagged with more conventional way
- block_tags can display tag cloud from one tag collection only and also only tags used in specific context (course/module/etc)
- improve "Manage tags" interface - it definitely needs some upgrade to 21st century
- introduce templates for tag cloud and tag list
Implementation
There are two new DB tables: tag_coll and tag_area
The unque index on table {tag} that used to have only tag name now contains tag collection id and tag name
Each plugin can define plugindir/db/tag.php that would contain the list of the tag areas and, if needed, completely isolated tag collections. They are registered in tables tag_area and tag_coll. Manager can create more collections, allocate tag areas to them and also enable/disable each tag area independently.
When developer wants to check if the tag area is enabled, they should call
core_tag::is_enabled($component, $itemtype);
for example: core_tag::is_enabled('core', 'user') or core_tag::is_enabled('mod_wiki', 'wiki_pages')
In order to add a form element to the moodleform developer also needs to specify the itemtype and component:
$mform->addElement('tags', 'tags', get_string('tags'), array('component' => 'core', 'itemtype' => 'post'));
Functions tag_set_tags(), tag_get_tags_array(), tag_get_tags(), tag_get_tag_csv(), tag_get_related_tags(), tag_get_related_tags_csv(), etc. will continue working and don't need changes.
Functions tag_find_records(), will be deprecated because it needs another required argument and it is not good to add it after the optional arguments.
Lots of tag-related functions will be deprecated because they require more arguments but good news is that plugins don't really need to use them and they are already defined in tag/lib as "access private": tag_type_set(), tag_description_set(), tag_get(), tag_get_id(), tag_rename(), tag_assign(), tag_autocomplete(), tag_record_count(), tag_record_tagged_with(), tag_set_flag(), etc. The complete list can be found in the file /tag/upgrade.txt
