Tag API 3 Specification

Jump to: navigation, search

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