Tag API: Difference between revisions
No edit summary |
|||
Line 22: | Line 22: | ||
First, developer must define the tag areas in the file '''db/tag.php'''. This will usually look like: | First, developer must define the tag areas in the file '''db/tag.php'''. This will usually look like: | ||
< | <code php> | ||
$tagareas = array( | $tagareas = array( | ||
array( | array( | ||
'itemtype' => 'course', | 'itemtype' => 'course', // This must be a name of the database table (without prefix). | ||
'component' => 'core', | 'component' => 'core', // This can be omitted for plugins since it can only be full frankenstyle name of the plugin. | ||
'callback' => 'course_get_tagged_courses', | 'callback' => 'course_get_tagged_courses', | ||
'callbackfile' => '/course/lib.php', | 'callbackfile' => '/course/lib.php', | ||
), | ), | ||
); | ); | ||
</ | </code> | ||
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 | 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 [[https://github.com/moodle/moodle/blob/master/lib/db/tag.php 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. | 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=== | ===Adding tags element to the editing form=== |
Revision as of 10:23, 18 May 2016
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', // This must be a name of the database table (without prefix).
'component' => 'core', // This can be omitted for plugins since it can only be full frankenstyle name of the plugin.
'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]