From bcdcee903c567a9800f67d07ac8612e9d43afdbf Mon Sep 17 00:00:00 2001 From: "Gerard (Gerry) Caulfield" Date: Mon, 9 Jan 2012 17:27:45 +0800 Subject: [PATCH] MDL-30992 Updating Tag API DocBlocks --- tag/coursetags_add.php | 22 +- tag/coursetags_edit.php | 24 +- tag/coursetags_more.php | 25 ++- tag/coursetagslib.php | 137 ++++++++---- tag/edit.php | 6 +- tag/edit_form.php | 20 +- tag/index.php | 6 +- tag/lib.php | 476 ++++++++++++++++++++++++---------------- tag/locallib.php | 106 ++++++--- 9 files changed, 534 insertions(+), 288 deletions(-) diff --git a/tag/coursetags_add.php b/tag/coursetags_add.php index e5c316a3f8c..969dda3e3ac 100644 --- a/tag/coursetags_add.php +++ b/tag/coursetags_add.php @@ -1,7 +1,27 @@ . + + /** * coursetags_add.php - * @author j.beedell@open.ac.uk June07 + * + * @package core_tag + * @category tag + * @copyright 2007 j.beedell@open.ac.uk + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once('../config.php'); diff --git a/tag/coursetags_edit.php b/tag/coursetags_edit.php index 18d40a45da8..8bb33b4a74f 100644 --- a/tag/coursetags_edit.php +++ b/tag/coursetags_edit.php @@ -1,9 +1,27 @@ . + /** - * coursetags_edit.php - * displays personal tags for a course with some editing facilites - * @author j.beedell@open.ac.uk June07 + * Displays personal tags for a course with some editing facilites + * + * @package core_tag + * @category tag + * @copyright 2007 j.beedell@open.ac.uk + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once('../config.php'); diff --git a/tag/coursetags_more.php b/tag/coursetags_more.php index ee7c75c454b..60b18207be1 100644 --- a/tag/coursetags_more.php +++ b/tag/coursetags_more.php @@ -1,8 +1,27 @@ . + + /** - * coursetags_more.php - * a full display of tags allowing some filtering and reordering - * @author j.beedell@open.ac.uk June07 + * A full display of tags allowing some filtering and reordering + * + * @package core_tag + * @category tag + * @copyright 2007 j.beedell@open.ac.uk + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once('../config.php'); diff --git a/tag/coursetagslib.php b/tag/coursetagslib.php index f022dfc5f77..c83b9543084 100644 --- a/tag/coursetagslib.php +++ b/tag/coursetagslib.php @@ -1,7 +1,26 @@ . + + /** * coursetagslib.php - * @author j.beedell@open.ac.uk July07 + * + * @package core_tag + * @copyright 2007 j.beedell@open.ac.uk + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once $CFG->dirroot.'/tag/lib.php'; @@ -10,13 +29,15 @@ require_once $CFG->dirroot.'/tag/lib.php'; * Returns an ordered array of tags associated with visible courses * (boosted replacement of get_all_tags() allowing association with user and tagtype). * - * @uses $CFG - * @param int $courseid, a 0 will return all distinct tags for visible courses - * @param int $userid optional the user id, a default of 0 will return all users tags for the course - * @param string $tagtype optional 'official' or 'default', empty returns both tag types - * @param int $numtags optional number of tags to display, default of 80 is set in the block, 0 returns all - * @param string $sort optional selected sorting, default is alpha sort (name) also timemodified or popularity - * @return array + * @package core_tag + * @category tag + * @param int $courseid A course id. Passing 0 will return all distinct tags for all visible courses + * @param int $userid (optional) the user id, a default of 0 will return all users tags for the course + * @param string $tagtype (optional) The type of tag, empty string returns all types. Currently (Moodle 2.2) there are two + * types of tags which are used within Moodle, they are 'official' and 'default'. + * @param int $numtags (optional) number of tags to display, default of 80 is set in the block, 0 returns all + * @param string $sort (optional) selected sorting, default is alpha sort (name) also timemodified or popularity + * @return array */ function coursetag_get_tags($courseid, $userid=0, $tagtype='', $numtags=0, $sort='name') { @@ -93,10 +114,11 @@ function coursetag_get_tags($courseid, $userid=0, $tagtype='', $numtags=0, $sort * Returns an ordered array of tags * (replaces popular_tags_count() allowing sorting). * - * @uses $CFG - * @param string $sort optional selected sorting, default is alpha sort (name) also timemodified or popularity - * @param int $numtags optional number of tags to display, default of 20 is set in the block, 0 returns all - * @return array + * @package core_tag + * @category tag + * @param string $sort (optional) selected sorting, default is alpha sort (name) also timemodified or popularity + * @param int $numtags (optional) number of tags to display, default of 20 is set in the block, 0 returns all + * @return array */ function coursetag_get_all_tags($sort='name', $numtags=0) { @@ -135,8 +157,21 @@ function coursetag_get_all_tags($sort='name', $numtags=0) { } /** - * Callback function for coursetag_get_tags() and coursetag_get_all_tags() only - * @uses $CFG + * Sorting callback function for coursetag_get_tags() and coursetag_get_all_tags() only + * + * This function does a comparision on a field withing two variables, $a and $b. The field used is specified by + * $CFG->tagsort or we just use the 'name' field if $CFG->tagsort is empty. The comparison works as follows: + * If $a->$tagsort is greater than $b->$tagsort, 1 is returned. + * If $a->$tagsort is equal to $b->$tagsort, 0 is returned. + * If $a->$tagsort is less than $b->$tagsort, -1 is returned. + * + * Also if $a->$tagsort is not numeric or a string, 0 is returned. + * + * @package core_tag + * @access private + * @param int|string|mixed $a Variable to compare against $b + * @param int|string|mixed $b Variable to compare against $a + * @return int The result of the comparison/validation 1, 0 or -1 */ function coursetag_sort($a, $b) { // originally from block_blog_tags @@ -161,10 +196,12 @@ function coursetag_sort($a, $b) { /** * Prints a tag cloud * - * @param array $tagcloud array of tag objects (fields: id, name, rawname, count and flag) - * @param int $max_size maximum text size, in percentage - * @param int $min_size minimum text size, in percentage - * @param $return if true return html string + * @package core_tag + * @category tag + * @param array $tagcloud array of tag objects (fields: id, name, rawname, count and flag) + * @param mixed $return if true return html string + * @param int $max_size maximum text size, in percentage + * @param int $min_size minimum text size, in percentage */ function coursetag_print_cloud($tagcloud, $return=false, $max_size=180, $min_size=80) { @@ -237,8 +274,11 @@ function coursetag_print_cloud($tagcloud, $return=false, $max_size=180, $min_siz /** * Returns javascript for use in tags block and supporting pages - * @param string $coursetagdivs comma separated divs ids - * @uses $CFG + * + * @package core_tag + * @category tag + * @param string $coursetagdivs comma separated divs ids + * @return null */ function coursetag_get_jscript($coursetagdivs = '') { global $CFG, $DB, $PAGE; @@ -263,6 +303,12 @@ function coursetag_get_jscript($coursetagdivs = '') { /** * Returns javascript to create the links in the tag block footer. + * + * @package core_tag + * @category tag + * @param string $elementid the element to attach the footer to + * @param array $coursetagslinks links arrays each consisting of 'title', 'onclick' and 'text' elements + * @return string always returns a blank string */ function coursetag_get_jscript_links($elementid, $coursetagslinks) { global $PAGE; @@ -279,12 +325,12 @@ function coursetag_get_jscript_links($elementid, $coursetagslinks) { /** * Returns all tags created by a user for a course * - * @uses $CFG - * @param int $courseid - * @param int $userid + * @package core_tag + * @category tag + * @param int $courseid tags are returned for the course that has this courseid + * @param int $userid return tags which were created by this user */ function coursetag_get_records($courseid, $userid) { - global $CFG, $DB; $sql = "SELECT t.id, name, rawname @@ -300,12 +346,13 @@ function coursetag_get_records($courseid, $userid) { /** * Stores a tag for a course for a user * - * @uses $CFG - * @param array $tags simple array of keywords to be stored - * @param integer $courseid - * @param integer $userid - * @param string $tagtype official or default only - * @param string $myurl optional for logging creation of course tags + * @package core_tag + * @category tag + * @param array $tags simple array of keywords to be stored + * @param int $courseid the id of the course we wish to store a tag for + * @param int $userid the id of the user we wish to store a tag for + * @param string $tagtype official or default only + * @param string $myurl (optional) for logging creation of course tags */ function coursetag_store_keywords($tags, $courseid, $userid=0, $tagtype='official', $myurl='') { @@ -348,11 +395,12 @@ function coursetag_store_keywords($tags, $courseid, $userid=0, $tagtype='officia /** * Deletes a personal tag for a user for a course. * - * @uses $CFG - * @param int $tagid - * @param int $userid - * @param int $courseid - */ + * @package core_tag + * @category tag + * @param int $tagid the tag we wish to delete + * @param int $userid the user that the tag is associated with + * @param int $courseid the course that the tag is associated with + */ function coursetag_delete_keyword($tagid, $userid, $courseid) { global $CFG, $DB; @@ -385,11 +433,12 @@ function coursetag_delete_keyword($tagid, $userid, $courseid) { /** * Get courses tagged with a tag * + * @package core_tag + * @category tag * @param int $tagid * @return array of course objects */ function coursetag_get_tagged_courses($tagid) { - global $DB; $courses = array(); @@ -411,14 +460,13 @@ function coursetag_get_tagged_courses($tagid) { } /** - * Course tagging function used only during the deletion of a - * course (called by lib/moodlelib.php) to clean up associated tags + * Course tagging function used only during the deletion of a course (called by lib/moodlelib.php) to clean up associated tags * - * @param int $courseid - * @param bool $showfeedback + * @package core_tag + * @param int $courseid the course we wish to delete tag instances from + * @param bool $showfeedback if we should output a notification of the delete to the end user */ function coursetag_delete_course_tags($courseid, $showfeedback=false) { - global $DB, $OUTPUT; if ($tags = $DB->get_records_select('tag_instance', "itemtype='course' AND itemid=:courseid", array('courseid'=>$courseid))) { @@ -440,10 +488,9 @@ function coursetag_delete_course_tags($courseid, $showfeedback=false) { } } -/** +/* * Function called by cron to create/update users rss feeds * - * @uses $CFG * @return true * * Function removed. @@ -618,10 +665,10 @@ function coursetag_rss_feeds() { } */ -/** +/* * Get official keywords for the in header.html * use: echo ''; - * @uses $CFG + * * @param int $courseid * @return string * diff --git a/tag/edit.php b/tag/edit.php index 66fd0fbc366..b71c72f2be0 100644 --- a/tag/edit.php +++ b/tag/edit.php @@ -1,5 +1,4 @@ . + /** - * @package core - * @subpackage tag + * @package core_tag + * @category tag * @copyright 2007 Luiz Cruz * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/tag/edit_form.php b/tag/edit_form.php index f1e828620cc..972836755a7 100644 --- a/tag/edit_form.php +++ b/tag/edit_form.php @@ -1,5 +1,4 @@ . + /** - * @package core - * @subpackage tag + * @package core_tag + * @category tag * @copyright 2007 Luiz Cruz * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -28,8 +28,20 @@ if (!defined('MOODLE_INTERNAL')) { require_once($CFG->dirroot.'/lib/formslib.php'); +/** + * Defines the form for editing tags + * + * @package core_tag + * @category tag + * @copyright 2007 Luiz Cruz + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class tag_edit_form extends moodleform { + /** + * Overrides the abstract moodleform::definition method for defining what the form that is to be + * presented to the user. + */ function definition () { $mform =& $this->_form; @@ -62,4 +74,4 @@ class tag_edit_form extends moodleform { } -} +} \ No newline at end of file diff --git a/tag/index.php b/tag/index.php index 5525f0411c8..56e23726aa1 100644 --- a/tag/index.php +++ b/tag/index.php @@ -1,5 +1,4 @@ . + /** - * @package core - * @subpackage tag + * @package core_tag + * @category tag * @copyright 2007 Luiz Cruz * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/tag/lib.php b/tag/lib.php index 2284a41fb22..2859162b61d 100644 --- a/tag/lib.php +++ b/tag/lib.php @@ -1,5 +1,4 @@ . + /** * 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. + * 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. * - * A "record" is a php array (note that an object will work too) that contains - * the following variables : - * - type: the table containing the record that we are tagging (eg: for a - * blog, this is table 'post', and for a user it is 'user') - * - id: the id of the record - * - * TODO: turn this into a full-fledged categorization system. This could start - * by modifying (removing, probably) the 'tag type' to use another table - * describing the relationship between tags (parents, sibling, etc.), which - * could then be merged with the 'course categorization' system... + * A "record" is a php array (note that an object will work too) that contains the following + * variables : + * - type: The database table containing the record that we are tagging (eg: for a blog, this is + * the table named 'post', and for a user it is the table name 'user') + * - id: The id of the record * * BASIC INSTRUCTIONS : * - to "tag a blog post" (for example): @@ -43,23 +38,63 @@ * * Tag set will create tags that need to be created. * - * @package core - * @subpackage tag - * @see http://www.php.net/manual/en/function.urlencode.php + * @package core_tag + * @category tag + * @todo MDL-31090 turn this into a full-fledged categorization system. This could start by + * modifying (removing, probably) the 'tag type' to use another table describing the + * relationship between tags (parents, sibling, etc.), which could then be merged with + * the 'course categorization' system. + * @see http://www.php.net/manual/en/function.urlencode.php * @copyright 2007 Luiz Cruz * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ +/** + * Used to require that the return value from a function is an array. + * @see tag_set() + */ define('TAG_RETURN_ARRAY', 0); +/** + * Used to require that the return value from a function is an object. + * @see tag_set() + */ define('TAG_RETURN_OBJECT', 1); +/** + * Use to specify that HTML free text is expected to be returned from a function. + * @see tag_display_name() + */ define('TAG_RETURN_TEXT', 2); +/** + * Use to specify that encoded HTML is expected to be returned from a function. + * @see tag_display_name() + */ define('TAG_RETURN_HTML', 3); +/** + * Used to specify that we wish a lowercased string to be returned + * @see tag_normal() + */ define('TAG_CASE_LOWER', 0); +/** + * Used to specify that we do not wish the case of the returned string to change + * @see tag_normal() + */ define('TAG_CASE_ORIGINAL', 1); +/** + * Used to specify that we want all related tags returned, no matter how they are related. + * @see tag_get_related_tags() + */ define('TAG_RELATED_ALL', 0); +/** + * Used to specify that we only want back tags that were manually related. + * @see tag_get_related_tags() + */ define('TAG_RELATED_MANUAL', 1); +/** + * Used to specify that we only want back tags where the relationship was automatically correlated. + * @see tag_get_related_tags() + */ define('TAG_RELATED_CORRELATED', 2); /////////////////////////////////////////////////////// @@ -70,15 +105,15 @@ define('TAG_RELATED_CORRELATED', 2); /** * 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. + * This function is meant to be fed the string coming up from the user interface, which contains all tags assigned to a record. * - * @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. - * @return void + * @package core_tag + * @category tag + * @access public + * @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. + * @return bool|null */ function tag_set($record_type, $record_id, $tags) { @@ -142,11 +177,12 @@ function tag_set($record_type, $record_id, $tags) { /** * Adds a tag to a record, without overwriting the current tags. * - * @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 - * @return void + * @package core_tag + * @category tag + * @access public + * @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 */ function tag_set_add($record_type, $record_id, $tag) { @@ -162,11 +198,12 @@ function tag_set_add($record_type, $record_id, $tag) { /** * Removes a tag from a record, without overwriting other current tags. * - * @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 - * @return void + * @package core_tag + * @category tag + * @access public + * @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 */ function tag_set_delete($record_type, $record_id, $tag) { @@ -181,13 +218,15 @@ function tag_set_delete($record_type, $record_id, $tag) { } /** - * Set the type of a tag. At this time (version 1.9) 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). + * 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). * - * @param string $tagid tagid to modify - * @param string $type either 'default' or 'official' - * @return true on success, false otherwise + * @package core_tag + * @category tag + * @access public + * @param string $tagid tagid to modify + * @param string $type either 'default' or 'official' + * @return bool true on success, false otherwise */ function tag_type_set($tagid, $type) { global $DB; @@ -200,14 +239,17 @@ function tag_type_set($tagid, $type) { return false; } - /** * Set the description of a tag * - * @param int $tagid the id of the tag - * @param string $description the description - * @param int $descriptionformat the moodle text format of the description - * @return true on success, false otherwise + * @package core_tag + * @category tag + * @access public + * @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 + * {@link http://docs.moodle.org/dev/Text_formats_2.0#Database_structure} + * @return bool true on success, false otherwise */ function tag_description_set($tagid, $description, $descriptionformat) { global $DB; @@ -231,12 +273,15 @@ function tag_description_set($tagid, $description, $descriptionformat) { /** * Simple function to just return a single tag object when you know the name or something * - * @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? - * @return tag object - * - **/ + * @package core_tag + * @category tag + * @access public + * @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 + * 'id', 'name', 'rawname' or '*' to include all fields. + * @return mixed tag object + */ function tag_get($field, $value, $returnfields='id, name, rawname') { global $DB; @@ -248,15 +293,17 @@ function tag_get($field, $value, $returnfields='id, name, rawname') { /** - * Get the array of db record of tags associated to a record (instances). Use - * tag_get_tags_csv to get the same information in a comma-separated string. - * This should really be called tag_get_tag_instances() + * 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(). * + * @package core_tag + * @category tag + * @access public * @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 + * @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 * @return array the array of tags */ function tag_get_tags($record_type, $record_id, $type=null, $userid=0) { @@ -300,11 +347,13 @@ function tag_get_tags($record_type, $record_id, $type=null, $userid=0) { /** * Get the array of tags display names, 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. - * @return array the array of tags (with the value returned by tag_display_name), indexed by id + * @package core_tag + * @category tag + * @access public + * @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. + * @return array the array of tags (with the value returned by tag_display_name), indexed by id */ function tag_get_tags_array($record_type, $record_id, $type=null) { $tags = array(); @@ -315,16 +364,16 @@ function tag_get_tags_array($record_type, $record_id, $type=null) { } /** - * Get a comma-separated string of tags associated to a record. Use tag_get_tags - * to get the same information in an array. + * Get a comma-separated string of tags associated to a record. Use {@see tag_get_tags()} to get the same information in an array. * - * @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 - * @return string the comma-separated list of tags. + * @package core_tag + * @category tag + * @access public + * @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 + * @return string the comma-separated list of tags. */ function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null) { global $CFG; @@ -343,18 +392,21 @@ function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type /** * Get an array of tag ids associated to a record. * - * @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 - * @return array of tag ids, indexed and sorted by 'ordering' + * @package core_tag + * @category tag + * @access public + * @todo MDL-31150 Update ordering property + * @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 + * @return array tag ids, indexed and sorted by 'ordering' */ function tag_get_tags_ids($record_type, $record_id) { - $tag_ids = array(); foreach (tag_get_tags($record_type, $record_id) as $tag) { if ( array_key_exists($tag->ordering, $tag_ids) ) { // until we can add a unique constraint, in table tag_instance, // on (itemtype, itemid, ordering), this is needed to prevent a bug - // TODO : modify database in 2.0 + // TODO MDL-31150 modify database in 2.0 $tag->ordering++; } $tag_ids[$tag->ordering] = $tag->id; @@ -366,14 +418,16 @@ function tag_get_tags_ids($record_type, $record_id) { /** * Returns the database ID of a set of tags. * - * @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). If TAG_RETURN_ARRAY - * is specified, an array will be returned even if only one tag was - * passed in $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 is given *and* the - * second parameter is null. No value for a key means the tag wasn't found. + * @package core_tag + * @category tag + * @access public + * @todo MDL-31152 Test the commented MDL-31152 todo in this function to see if it helps performance + * without breaking anything. + * @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). + * If TAG_RETURN_ARRAY is specified, an array will be returned even if only one tag was passed in $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 + * is given *and* the second parameter is null. No value for a key means the tag wasn't found. */ function tag_get_id($tags, $return_value=null) { global $CFG, $DB; @@ -390,7 +444,7 @@ function tag_get_id($tags, $return_value=null) { $result = array(); - //TODO: test this and see if it helps performance without breaking anything + //TODO MDL-31152 test this and see if it helps performance without breaking anything //foreach($tags as $key => $tag) { // $clean_tag = moodle_strtolower($tag); // if ( array_key_exists($clean_tag), $tag_id_cache) ) { @@ -434,16 +488,16 @@ function tag_get_id($tags, $return_value=null) { * * 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 a calculated + * - correlated tags, which are calculated * - * @param string $tag_name_or_id 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 (TAG_RELATED_CORRELATED) - * tags. Default is TAG_RELATED_ALL, which returns everything. - * @param int $limitnum return a subset comprising this many records (optional, - * default is 10) - * @return array an array of tag objects + * @package core_tag + * @category tag + * @access public + * @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 + * (TAG_RELATED_CORRELATED) tags. Default is TAG_RELATED_ALL, which returns everything. + * @param int $limitnum (optional) return a subset comprising this many records, the default is 10 + * @return array an array of tag objects */ function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) { @@ -468,9 +522,12 @@ function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) { /** * Get a comma-separated list of tags related to another tag. * - * @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. - * @return string comma-separated list + * @package core_tag + * @category tag + * @access public + * @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. + * @return string comma-separated list */ function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) { global $CFG; @@ -491,9 +548,12 @@ function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) { /** * Change the "value" of a tag, and update the associated 'name'. * - * @param int $tagid the id of the tag to modify - * @param string $newtag the new rawname - * @return bool true on success, false otherwise + * @package core_tag + * @category tag + * @access public + * @param int $tagid the id of the tag to modify + * @param string $newrawname the new rawname + * @return bool true on success, false otherwise */ function tag_rename($tagid, $newrawname) { global $DB; @@ -526,8 +586,11 @@ function tag_rename($tagid, $newrawname) { /** * Delete one or more tag, and all their instances if there are any left. * - * @param mixed $tagids one tagid (int), or one array of tagids to delete - * @return bool true on success, false otherwise + * @package core_tag + * @category tag + * @access public + * @param mixed $tagids one tagid (int), or one array of tagids to delete + * @return bool true on success, false otherwise */ function tag_delete($tagids) { global $DB; @@ -560,13 +623,15 @@ function tag_delete($tagids) { } /** - * Delete one instance of a tag. If the last instance was deleted, it will - * also delete the tag, unless its type is 'official'. + * Delete one instance of a tag. If the last instance was deleted, it will also delete the tag, unless its type is 'official'. * - * @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 - * @return bool true on success, false otherwise + * @package core_tag + * @category tag + * @access public + * @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 + * @return bool true on success, false otherwise */ function tag_delete_instance($record_type, $record_id, $tagid) { global $CFG, $DB; @@ -592,12 +657,14 @@ function tag_delete_instance($record_type, $record_id, $tagid) { /** * Function that returns the name that should be displayed for a specific tag * - * @param object $tag_object 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. - * @return string + * @package core_tag + * @category tag + * @access public + * @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. + * @return string */ function tag_display_name($tagobject, $html=TAG_RETURN_HTML) { - global $CFG; if (!isset($tagobject->name)) { @@ -626,12 +693,14 @@ function tag_display_name($tagobject, $html=TAG_RETURN_HTML) { /** * Find all records tagged with a tag of a given type ('post', 'user', etc.) * - * @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 return a subset of records, starting at this point (optional, required if $limitnum is set). - * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set). - * @return array of matching objects, indexed by record id, from the table containing the type requested + * @package core_tag + * @category tag + * @access public + * @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. + * @return array of matching objects, indexed by record id, from the table containing the type requested */ function tag_find_records($tag, $type, $limitfrom='', $limitnum='') { global $CFG, $DB; @@ -657,15 +726,16 @@ function tag_find_records($tag, $type, $limitfrom='', $limitnum='') { /////////////////// PRIVATE TAG API /////////////////// /** - * Adds one or more tag in the database. This function should not be called - * directly : you should use tag_set. + * Adds one or more tag in the database. This function should not be called directly : you should + * use tag_set. * - * @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 value at this time). An - * official tag is kept even if there are no records tagged with it. - * @return an array of tags ids, indexed by their lowercase normalized names. - * Any boolean false in the array indicates an error while adding the tag. + * @package core_tag + * @access private + * @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 + * value at this time). An official tag is kept even if there are no records tagged with it. + * @return array $tags ids indexed by their lowercase normalized names. Any boolean false in the array indicates an error while + * adding the tag. */ function tag_add($tags, $type="default") { global $USER, $DB; @@ -701,15 +771,16 @@ function tag_add($tags, $type="default") { } /** - * Assigns a tag to a record: if the record already exists, the time and - * ordering will be updated. + * Assigns a tag to a record; if the record already exists, the time and ordering will be updated. * - * @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 - * @return bool true on success, false otherwise + * @package core_tag + * @access private + * @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 + * @return bool true on success, false otherwise */ function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0) { global $DB; @@ -733,8 +804,10 @@ function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0) { /** * Function that returns tags that start with some text, for use by the autocomplete feature * - * @param string $text string that the tag names will be matched against - * @return mixed an array of objects, or false if no records were found or an error occured. + * @package core_tag + * @access private + * @param string $text string that the tag names will be matched against + * @return mixed an array of objects, or false if no records were found or an error occured. */ function tag_autocomplete($text) { global $DB; @@ -746,10 +819,13 @@ function tag_autocomplete($text) { /** * 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. + * 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. + * + * @package core_tag + * @access private + * @todo MDL-31212 Update tag cleanup sql so that it supports multiple types of tags */ function tag_cleanup() { global $DB; @@ -784,7 +860,7 @@ function tag_cleanup() { } $instances->close(); - // TODO: this will only clean tags of type 'default'. This is good as + // TODO MDL-31212 this will only clean tags of type 'default'. This is good as // it won't delete 'official' tags, but the day we get more than two // types, we need to fix this. $unused_tags = $DB->get_recordset_sql("SELECT tg.id @@ -805,20 +881,16 @@ function tag_cleanup() { } /** - * Calculates and stores the correlated tags of all tags. - * The correlations are stored in the 'tag_correlation' table. + * 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". + * 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. + * 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. * - * @global moodle_database $DB - * @param int $mincorrelation Only tags with more than $mincorrelation correlations will - * be identified. - * @return void + * @package core_tag + * @access private + * @param int $mincorrelation Only tags with more than $mincorrelation correlations will be identified. */ function tag_compute_correlations($mincorrelation = 2) { global $DB; @@ -896,14 +968,14 @@ function tag_compute_correlations($mincorrelation = 2) { } /** - * This function processes a tag correlation and makes changes in the database - * as required. + * 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. + * The tag correlation object needs have both a tagid property and a correlatedtags property that is an array. * - * @param stdClass $tagcorrelation - * @return int The id of the tag correlation that was just processed. + * @package core_tag + * @access private + * @param stdClass $tagcorrelation + * @return int/bool The id of the tag correlation that was just processed or false. */ function tag_process_computed_correlation(stdClass $tagcorrelation) { global $DB; @@ -926,6 +998,9 @@ function tag_process_computed_correlation(stdClass $tagcorrelation) { /** * Tasks that should be performed at cron time + * + * @package core_tag + * @access private */ function tag_cron() { tag_compute_correlations(); @@ -935,11 +1010,13 @@ function tag_cron() { /** * Search for tags with names that match some text * - * @param string $text escaped string that the tag names will be matched against - * @param boolean $ordered If true, tags are ordered by their popularity. If false, no ordering. - * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set). - * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set). - * @return mixed an array of objects, or false if no records were found or an error occured. + * @package core_tag + * @access private + * @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. + * @return array/boolean an array of objects, or false if no records were found or an error occured. */ function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') { global $DB; @@ -964,8 +1041,10 @@ function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') { /** * Get the name of a tag * - * @param mixed $tagids the id of the tag, or an array of ids - * @return mixed string name of one tag, or id-indexed array of strings + * @package core_tag + * @access private + * @param mixed $tagids the id of the tag, or an array of ids + * @return mixed string name of one tag, or id-indexed array of strings */ function tag_get_name($tagids) { global $DB; @@ -986,12 +1065,14 @@ function tag_get_name($tagids) { } /** - * 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. + * 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. * - * @param int $tag_id is a single tag id - * @return array an array of tag objects, empty if no correlated tags are found + * @package core_tag + * @access private + * @param int $tag_id is a single tag id + * @param int $limitnum this parameter does not appear to have any function??? + * @return array an array of tag objects or an empty if no correlated tags are found */ function tag_get_correlated($tag_id, $limitnum=null) { global $DB; @@ -1018,11 +1099,12 @@ function tag_get_correlated($tag_id, $limitnum=null) { /** * Function that normalizes a list of tag names. * - * @param mixed $tags 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 - * @return array of lowercased normalized tags, indexed by the normalized tag, - * in the same order as the original array. (Eg: 'Banana' => 'banana'). + * @package core_tag + * @access private + * @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 + * @return array lowercased normalized tags, indexed by the normalized tag, in the same order as the original array. + * (Eg: 'Banana' => 'banana'). */ function tag_normalize($rawtags, $case = TAG_CASE_LOWER) { @@ -1055,11 +1137,13 @@ function tag_normalize($rawtags, $case = TAG_CASE_LOWER) { } /** - * Count how many records are tagged with a specific tag, + * Count how many records are tagged with a specific tag. * - * @param string $record record to look for ('post', 'user', etc.) - * @param int $tag is a single tag id - * @return int number of mathing tags. + * @package core_tag + * @access private + * @param string $record_type record to look for ('post', 'user', etc.) + * @param int $tagid is a single tag id + * @return int number of mathing tags. */ function tag_record_count($record_type, $tagid) { global $DB; @@ -1069,10 +1153,12 @@ function tag_record_count($record_type, $tagid) { /** * Determine if a record is tagged with a specific tag * - * @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 - * @return bool true if it is tagged, false otherwise + * @package core_tag + * @access private + * @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 + * @return bool/int true if it is tagged, 0 (false) otherwise */ function tag_record_tagged_with($record_type, $record_id, $tag) { global $DB; @@ -1086,8 +1172,9 @@ function tag_record_tagged_with($record_type, $record_id, $tag) { /** * Flag a tag as inapropriate * - * @param mixed $tagids one (int) tagid, or an array of tagids - * @return void + * @package core_tag + * @access private + * @param int|array $tagids a single tagid, or an array of tagids */ function tag_set_flag($tagids) { global $DB; @@ -1104,8 +1191,10 @@ function tag_set_flag($tagids) { /** * Remove the inapropriate flag on a tag * - * @param mixed $tagids one (int) tagid, or an array of tagids - * @return bool true if function succeeds, false otherwise + * @package core_tag + * @access private + * @param int|array $tagids a single tagid, or an array of tagids + * @return bool true if function succeeds, false otherwise */ function tag_unset_flag($tagids) { global $DB; @@ -1120,9 +1209,12 @@ function tag_unset_flag($tagids) { /** * 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 + * + * @package core_tag + * @access private + * @param string $pagetype current page type + * @param stdClass $parentcontext Block's parent context + * @param stdClass $currentcontext Current context of block */ function tag_page_type_list($pagetype, $parentcontext, $currentcontext) { return array( diff --git a/tag/locallib.php b/tag/locallib.php index 7b7cd460185..6c750b069b6 100644 --- a/tag/locallib.php +++ b/tag/locallib.php @@ -1,21 +1,40 @@ . + + +/** + * Moodle tag local library - output functions + * + * @package core_tag + * @copyright 2007 Luiz Cruz + * @license http://www.gnu.org/copyleft/gpl.html GNU Public License + */ require_once($CFG->dirroot.'/tag/lib.php'); require_once($CFG->libdir.'/filelib.php'); /** - * locallib.php - moodle tag local library - output functions + * Prints or returns a HTML tag cloud with varying classes styles depending on the popularity and type of each tag. * - * @licence http://www.gnu.org/copyleft/gpl.html GNU Public License - * @package moodlecore - * - */ - -/** - * Prints a tag cloud - * - * @param array $tagcloud array of tag objects (fields: id, name, rawname, count and flag) - * @param $return if true return html string + * @package core_tag + * @access public + * @category tag + * @param int $nr_of_tags Limit for the number of tags to return/display + * @param bool $return if true the function will return the generated tag cloud instead of displaying it. + * @return string|null a HTML string or null if this function does the output */ function tag_print_cloud($nr_of_tags=150, $return=false) { global $CFG, $DB; @@ -69,9 +88,14 @@ function tag_print_cloud($nr_of_tags=150, $return=false) { } /** - * This function is used by print_tag_cloud, to usort() the tags in the cloud. - * See php.net/usort for the parameters documentation. This was originally in - * blocks/blog_tags/block_blog_tags.php, named blog_tags_sort(). + * This function is used by print_tag_cloud, to usort() the tags in the cloud. See php.net/usort for the parameters documentation. + * This was originally in blocks/blog_tags/block_blog_tags.php, named blog_tags_sort(). + * + * @package core_tag + * @access private + * @param string $a Tag name to compare against $b + * @param string $b Tag name to compare against $a + * @return int The result of the comparison/validation 1, 0 or -1 */ function tag_cloud_sort($a, $b) { global $CFG; @@ -94,14 +118,19 @@ function tag_cloud_sort($a, $b) { /** * Prints a box with the description of a tag and its related tags * - * @param stdClass $tag_object - * @param $return if true return html string + * @package core_tag + * @access public + * @todo MDL-31149 create a system setting for $max_tags_displayed, instead of using an in code literal + * @param stdClass $tag_object + * @param bool $return if true the function will return the generated tag cloud instead of displaying it. + * @return string/null a HTML box showing a description of the tag object and it's relationsips or null if output is done directly + * in the function. */ function tag_print_description_box($tag_object, $return=false) { global $USER, $CFG, $OUTPUT; - $max_tags_displayed = 10; // todo: turn this into a system setting + $max_tags_displayed = 10; $tagname = tag_display_name($tag_object); $related_tags = tag_get_related_tags($tag_object->id, TAG_RELATED_ALL, $max_tags_displayed+1); // this gets one more than we want @@ -147,8 +176,10 @@ function tag_print_description_box($tag_object, $return=false) { /** * Prints a box that contains the management links of a tag * - * @param $tagid - * @param $return if true return html string + * @access public + * @param stdClass $tag_object + * @param bool $return if true the function will return the generated tag cloud instead of displaying it. + * @return string|null a HTML string or null if this function does the output */ function tag_print_management_box($tag_object, $return=false) { @@ -192,7 +223,9 @@ function tag_print_management_box($tag_object, $return=false) { /** * Prints the tag search box * - * @param bool $return if true return html string + * @access public + * @param bool $return if true return html string + * @return string|null a HTML string or null if this function does the output */ function tag_print_search_box($return=false) { global $CFG, $OUTPUT; @@ -217,10 +250,12 @@ function tag_print_search_box($return=false) { /** * Prints the tag search results * - * @param string $query text that tag names will be matched against - * @param int $page current page - * @param int $perpage nr of users displayed per page - * @param $return if true return html string + * @access public + * @param string $query text that tag names will be matched against + * @param int $page current page + * @param int $perpage nr of users displayed per page + * @param bool $return if true return html string + * @return string|null a HTML string or null if this function does the output */ function tag_print_search_results($query, $page, $perpage, $return=false) { @@ -290,13 +325,13 @@ function tag_print_search_results($query, $page, $perpage, $return=false) { /** * Prints a table of the users tagged with the tag passed as argument * - * @param $tag_object - * @param int $users_per_row number of users per row to display - * @param int $limitfrom prints users starting at this point (optional, required if $limitnum is set). - * @param int $limitnum prints this many users (optional, required if $limitfrom is set). - * @param $return if true return html string + * @param int $tag_object the tag we wish to return data for + * @param int $limitfrom (optional, required if $limitnum is set) prints users starting at this point. + * @param int $limitnum (optional, required if $limitfrom is set) prints this many users. + * @param bool $return if true return html string + * @return string|null a HTML string or null if this function does the output */ -function tag_print_tagged_users_table($tag_object, $limitfrom='' , $limitnum='', $return=false) { +function tag_print_tagged_users_table($tag_object, $limitfrom='', $limitnum='', $return=false) { //List of users with this tag $userlist = tag_find_records($tag_object->name, 'user', $limitfrom, $limitnum); @@ -314,8 +349,9 @@ function tag_print_tagged_users_table($tag_object, $limitfrom='' , $limitnum='', /** * Prints an individual user box * - * @param $user user object (contains the following fields: id, firstname, lastname and picture) - * @param $return if true return html string + * @param user_object $user (contains the following fields: id, firstname, lastname and picture) + * @param bool $return if true return html string + * @return string|null a HTML string or null if this function does the output */ function tag_print_user_box($user, $return=false) { global $CFG, $OUTPUT; @@ -359,11 +395,13 @@ function tag_print_user_box($user, $return=false) { echo $output; } } + /** * Prints a list of users * - * @param array $userlist an array of user objects - * @param $return if true return html string + * @param array $userlist an array of user objects + * @param bool $return if true return html string, otherwise output the result + * @return string|null a HTML string or null if this function does the output */ function tag_print_user_list($userlist, $return=false) {