Search moodle.org's
Developer Documentation


/tag/ -> lib.php (summary)

Moodle tag library Tag strings : you can use any character in tags, except the comma (which is the separator) and the '\' (backslash).  Note that many spaces (or other blank characters) will get "compressed" into one. A tag string is always a rawurlencode'd string. This is the same behavior as http://del.icio.us.

Copyright: 2007 Luiz Cruz <luiz.laydner@gmail.com>
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1566 lines (58 kb)
Included or required: 5 times
Referenced: 28 times
Includes or requires: 0 files

Defines 35 functions


Functions that are not part of a class:

tag_set($record_type, $record_id, $tags, $component = null, $contextid = null)   X-Ref
Set the tags assigned to a record.  This overwrites the current tags.

This function is meant to be fed the string coming up from the user interface, which contains all tags assigned to a record.

return: bool|null
param: string $record_type the type of record to tag ('post' for blogs, 'user' for users, 'tag' for tags, etc.)
param: int $record_id the id of the record to tag
param: array $tags the array of tags to set on the record. If given an empty array, all tags will be removed.
param: string|null $component the component that was tagged
param: int|null $contextid the context id of where this tag was assigned

tag_set_add($record_type, $record_id, $tag, $component = null, $contextid = null)   X-Ref
Adds a tag to a record, without overwriting the current tags.

return: bool|null
param: string $record_type the type of record to tag ('post' for blogs, 'user' for users, etc.)
param: int $record_id the id of the record to tag
param: string $tag the tag to add
param: string|null $component the component that was tagged
param: int|null $contextid the context id of where this tag was assigned

tag_set_delete($record_type, $record_id, $tag, $component = null, $contextid = null)   X-Ref
Removes a tag from a record, without overwriting other current tags.

return: bool|null
param: string $record_type the type of record to tag ('post' for blogs, 'user' for users, etc.)
param: int $record_id the id of the record to tag
param: string $tag the tag to delete
param: string|null $component the component that was tagged
param: int|null $contextid the context id of where this tag was assigned

tag_type_set($tagid, $type)   X-Ref
Set the type of a tag.  At this time (version 2.2) the possible values are 'default' or 'official'.  Official tags will be
displayed separately "at tagging time" (while selecting the tags to apply to a record).

return: bool     true on success, false otherwise
param: string   $tagid tagid to modify
param: string   $type either 'default' or 'official'

tag_description_set($tagid, $description, $descriptionformat)   X-Ref
Set the description of a tag

return: bool     true on success, false otherwise
param: int      $tagid the id of the tag
param: string   $description the tag's description string to be set
param: int      $descriptionformat the moodle text format of the description

tag_get($field, $value, $returnfields='id, name, rawname')   X-Ref
Simple function to just return a single tag object when you know the name or something

return: mixed  tag object
param: string $field        which field do we use to identify the tag: id, name or rawname
param: string $value        the required value of the aforementioned field
param: string $returnfields which fields do we want returned. This is a comma seperated string containing any combination of

tag_get_tags($record_type, $record_id, $type=null, $userid=0)   X-Ref
Get the array of db record of tags associated to a record (instances).  Use {@see tag_get_tags_csv()} if you wish to get the same
data in a comma-separated string, for instances such as needing to simply display a list of tags to the end user. This should
really be called tag_get_tag_instances().

return: array the array of tags
param: string $record_type the record type for which we want to get the tags
param: int $record_id the record id for which we want to get the tags
param: string $type the tag type (either 'default' or 'official'). By default, all tags are returned.
param: int $userid (optional) only required for course tagging

tag_get_tags_array($record_type, $record_id, $type=null)   X-Ref
Get the array of tags display names, indexed by id.

return: array  the array of tags (with the value returned by tag_display_name), indexed by id
param: string $record_type the record type for which we want to get the tags
param: int    $record_id   the record id for which we want to get the tags
param: string $type        the tag type (either 'default' or 'official'). By default, all tags are returned.

tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null)   X-Ref
Get a comma-separated string of tags associated to a record.  Use {@see tag_get_tags()} to get the same information in an array.

return: string   the comma-separated list of tags.
param: string   $record_type the record type for which we want to get the tags
param: int      $record_id   the record id for which we want to get the tags
param: int      $html        either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending on the type of output desired
param: string   $type        either 'official' or 'default', if null, all tags are returned

tag_get_tags_ids($record_type, $record_id)   X-Ref
Get an array of tag ids associated to a record.

return: array     tag ids, indexed and sorted by 'ordering'
param: string    $record_type the record type for which we want to get the tags
param: int       $record_id the record id for which we want to get the tags

tag_get_id($tags, $return_value=null)   X-Ref
Returns the database ID of a set of tags.

return: mixed tag-indexed array of ids (or objects, if second parameter is TAG_RETURN_OBJECT), or only an int, if only one tag
param: mixed $tags one tag, or array of tags, to look for.
param: bool  $return_value specify the type of the returned value. Either TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default).

tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10)   X-Ref
Returns tags related to a tag

Related tags of a tag come from two sources:
- manually added related tags, which are tag_instance entries for that tag
- correlated tags, which are calculated

return: array    an array of tag objects
param: string   $tagid          is a single **normalized** tag name or the id of a tag
param: int      $type           the function will return either manually (TAG_RELATED_MANUAL) related tags or correlated
param: int      $limitnum       (optional) return a subset comprising this many records, the default is 10

tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML)   X-Ref
Get a comma-separated list of tags related to another tag.

return: string   comma-separated list
param: array    $related_tags the array returned by tag_get_related_tags
param: int      $html    either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.

tag_rename($tagid, $newrawname)   X-Ref
Change the "value" of a tag, and update the associated 'name'.

return: bool     true on success, false otherwise
param: int      $tagid  the id of the tag to modify
param: string   $newrawname the new rawname

tag_delete($tagids)   X-Ref
Delete one or more tag, and all their instances if there are any left.

return: bool     true on success, false otherwise
param: mixed    $tagids one tagid (int), or one array of tagids to delete

tag_delete_instances($component, $contextid = null)   X-Ref
Deletes all the tag instances given a component and an optional contextid.

param: string $component
param: int $contextid if null, then we delete all tag instances for the $component

tag_delete_instance($record_type, $record_id, $tagid, $userid = null)   X-Ref
Delete one instance of a tag.  If the last instance was deleted, it will also delete the tag, unless its type is 'official'.

return: bool   true on success, false otherwise
param: string $record_type the type of the record for which to remove the instance
param: int    $record_id   the id of the record for which to remove the instance
param: int    $tagid       the tagid that needs to be removed
param: int    $userid      (optional) the userid

tag_display_name($tagobject, $html=TAG_RETURN_HTML)   X-Ref
Function that returns the name that should be displayed for a specific tag

return: string
param: object   $tagobject a line out of tag table, as returned by the adobd functions
param: int      $html TAG_RETURN_HTML (default) will return htmlspecialchars encoded string, TAG_RETURN_TEXT will not encode.

tag_find_records($tag, $type, $limitfrom='', $limitnum='')   X-Ref
Find all records tagged with a tag of a given type ('post', 'user', etc.)

return: array of matching objects, indexed by record id, from the table containing the type requested
param: string   $tag       tag to look for
param: string   $type      type to restrict search to.  If null, every matching record will be returned
param: int      $limitfrom (optional, required if $limitnum is set) return a subset of records, starting at this point.
param: int      $limitnum  (optional, required if $limitfrom is set) return a subset comprising this many records.

tag_add($tags, $type="default")   X-Ref
Adds one or more tag in the database.  This function should not be called directly : you should
use tag_set.

return: array     $tags ids indexed by their lowercase normalized names. Any boolean false in the array indicates an error while
param: mixed    $tags     one tag, or an array of tags, to be created
param: string   $type     type of tag to be created ("default" is the default value and "official" is the only other supported

tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0, $component = null, $contextid = null)   X-Ref
Assigns a tag to a record; if the record already exists, the time and ordering will be updated.

return: bool true on success, false otherwise
param: string $record_type the type of the record that will be tagged
param: int $record_id the id of the record that will be tagged
param: string $tagid the tag id to set on the record.
param: int $ordering the order of the instance for this record
param: int $userid (optional) only required for course tagging
param: string|null $component the component that was tagged
param: int|null $contextid the context id of where this tag was assigned

tag_cleanup()   X-Ref
Clean up the tag tables, making sure all tagged object still exists.

This should normally not be necessary, but in case related tags are not deleted when the tagged record is removed, this should be
done once in a while, perhaps on an occasional cron run.  On a site with lots of tags, this could become an expensive function to
call: don't run at peak time.


tag_bulk_delete_instances($instances)   X-Ref
This function will delete numerous tag instances efficiently.
This removes tag instances only. It doesn't check to see if it is the last use of a tag.

param: array $instances An array of tag instance objects with the addition of the tagname and tagrawname

tag_compute_correlations($mincorrelation = 2)   X-Ref
Calculates and stores the correlated tags of all tags. The correlations are stored in the 'tag_correlation' table.

Two tags are correlated if they appear together a lot. Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".

The rationale for the 'tag_correlation' table is performance. It works as a cache for a potentially heavy load query done at the
'tag_instance' table. So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.

param: int      $mincorrelation Only tags with more than $mincorrelation correlations will be identified.

tag_process_computed_correlation(stdClass $tagcorrelation)   X-Ref
This function processes a tag correlation and makes changes in the database as required.

The tag correlation object needs have both a tagid property and a correlatedtags property that is an array.

return: int/bool The id of the tag correlation that was just processed or false.
param: stdClass $tagcorrelation

tag_cron()   X-Ref
Tasks that should be performed at cron time


tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='')   X-Ref
Search for tags with names that match some text

return: array/boolean an array of objects, or false if no records were found or an error occured.
param: string        $text      escaped string that the tag names will be matched against
param: bool          $ordered   If true, tags are ordered by their popularity. If false, no ordering.
param: int/string    $limitfrom (optional, required if $limitnum is set) return a subset of records, starting at this point.
param: int/string    $limitnum  (optional, required if $limitfrom is set) return a subset comprising this many records.

tag_get_name($tagids)   X-Ref
Get the name of a tag

return: mixed    string name of one tag, or id-indexed array of strings
param: mixed    $tagids the id of the tag, or an array of ids

tag_get_correlated($tag_id, $notused = null)   X-Ref
Returns the correlated tags of a tag, retrieved from the tag_correlation table. Make sure cron runs, otherwise the table will be
empty and this function won't return anything.

Correlated tags are calculated in cron based on existing tag instances.

This function will return as many entries as there are existing tag instances,
which means that there will be duplicates for each tag.

If you need only one record for each correlated tag please call:
tag_get_related_tags($tag_id, TAG_RELATED_CORRELATED);

return: array    an array of tag objects or an empty if no correlated tags are found
param: int      $tag_id   is a single tag id
param: int      $notused  this argument is no longer used

tag_normalize($rawtags, $case = TAG_CASE_LOWER)   X-Ref
Function that normalizes a list of tag names.

return: array        lowercased normalized tags, indexed by the normalized tag, in the same order as the original array.
param: array/string $rawtags array of tags, or a single tag.
param: int          $case    case to use for returned value (default: lower case). Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL

tag_record_count($record_type, $tagid)   X-Ref
Count how many records are tagged with a specific tag.

return: int      number of mathing tags.
param: string   $record_type record to look for ('post', 'user', etc.)
param: int      $tagid       is a single tag id

tag_record_tagged_with($record_type, $record_id, $tag)   X-Ref
Determine if a record is tagged with a specific tag

return: bool/int true if it is tagged, 0 (false) otherwise
param: string   $record_type the record type to look for
param: int      $record_id   the record id to look for
param: string   $tag         a tag name

tag_set_flag($tagids)   X-Ref
Flag a tag as inappropriate.

param: int|array $tagids a single tagid, or an array of tagids

tag_unset_flag($tagids)   X-Ref
Remove the inappropriate flag on a tag.

param: int|array $tagids a single tagid, or an array of tagids

tag_page_type_list($pagetype, $parentcontext, $currentcontext)   X-Ref
Return a list of page types

param: string   $pagetype       current page type
param: stdClass $parentcontext  Block's parent context
param: stdClass $currentcontext Current context of block

Search This Site: