From d48b00b40ee99b04cc8876085b2ede095751c754 Mon Sep 17 00:00:00 2001 From: dhawes Date: Thu, 23 Sep 2004 04:36:43 +0000 Subject: [PATCH] Added some more skeleton phpdoc comments and fixed a few more quote conversion issues --- lib/weblib.php | 811 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 594 insertions(+), 217 deletions(-) diff --git a/lib/weblib.php b/lib/weblib.php index a252c282ee..156760f0c6 100644 --- a/lib/weblib.php +++ b/lib/weblib.php @@ -1,11 +1,5 @@ ", etc.) properly quoted, if (empty($var)) { return ''; @@ -105,14 +98,13 @@ function s($var) { /** * Add quotes to HTML characters * - * Returns $var with HTML characters (like "<", ">", etc.) properly quoted. + * Prints $var with HTML characters (like "<", ">", etc.) properly quoted. * This function is very similar to {@link s()} * * @param string $var the string potentially containing HTML characters * @return string */ function p($var) { -/// prints $var with HTML characters (like "<", ">", etc.) properly quoted, if (empty($var)) { echo ''; @@ -132,7 +124,6 @@ function p($var) { * @return mixed */ function nvl(&$var, $default='') { -/// if $var is undefined, return $default, otherwise return $var return isset($var) ? $var : $default; } @@ -146,7 +137,6 @@ function nvl(&$var, $default='') { * @return string */ function strip_querystring($url) { -/// takes a URL and returns it without the querystring portion if ($commapos = strpos($url, '?')) { return substr($url, 0, $commapos); @@ -160,7 +150,6 @@ function nvl(&$var, $default='') { * @return string */ function get_referer() { -/// returns the URL of the HTTP_REFERER, less the querystring portion return strip_querystring(nvl($_SERVER['HTTP_REFERER'])); } @@ -171,14 +160,11 @@ function get_referer() { * this function is necessary because PHP_SELF and REQUEST_URI and SCRIPT_NAME * return different things depending on a lot of things like your OS, Web * server, and the way PHP is compiled (ie. as a CGI, module, ISAPI, etc.) - * NOTE: This function returns false if the global variables needed are not set. + * NOTE: This function returns false if the global variables needed are not set. + * * @return string */ function me() { -/// returns the name of the current script, WITH the querystring portion. -/// this function is necessary because PHP_SELF and REQUEST_URI and SCRIPT_NAME -/// return different things depending on a lot of things like your OS, Web -/// server, and the way PHP is compiled (ie. as a CGI, module, ISAPI, etc.) if (!empty($_SERVER['REQUEST_URI'])) { return $_SERVER['REQUEST_URI']; @@ -208,13 +194,11 @@ function get_referer() { } /** - * Like me() but returns a full URL + * Like {@link me()} but returns a full URL * @see me() - * @link me() * @return string */ function qualified_me() { -/// like me() but returns a full URL if (!empty($_SERVER['SERVER_NAME'])) { $hostname = $_SERVER['SERVER_NAME']; @@ -247,13 +231,12 @@ function qualified_me() { * the referer to test is not specified, use {@link qualified_me()}. * If the admin has not set secure forms ($CFG->secureforms) then * this function returns true regardless of a match. + * * @uses $CFG * @param string $goodreferer the url to compare to referer * @return boolean */ function match_referer($goodreferer = '') { -/// returns true if the referer is the same as the goodreferer. If -/// goodreferer is not specified, use qualified_me as the goodreferer global $CFG; if (empty($CFG->secureforms)) { // Don't bother checking referer @@ -283,20 +266,14 @@ function match_referer($goodreferer = '') { * * Checks that submitted POST data exists, and also * checks the referer against the given url (it uses - * the current page if none was specified + * the current page if none was specified. + * * @uses $CFG * @param string $url the url to compare to referer for secure forms * @return boolean */ function data_submitted($url='') { -/// Used on most forms in Moodle to check for data -/// Returns the data as an object, if it's found. -/// This object can be used in foreach loops without -/// casting because it's cast to (array) automatically -/// -/// Checks that submitted POST data exists, and also -/// checks the referer against the given url (it uses -/// the current page if none was specified. + global $CFG; @@ -322,14 +299,11 @@ function data_submitted($url='') { * even from strings - so C:\temp becomes C:temp - this isn't good. * This function should work as a fairly safe replacement * to be called on quoted AND unquoted strings (to be sure) + * * @param string the string to remove unsafe slashes from * @return string */ function stripslashes_safe($string) { -/// stripslashes() removes ALL backslashes even from strings -/// so C:\temp becomes C:temp ... this isn't good. -/// The following should work as a fairly safe replacement -/// to be called on quoted AND unquoted strings (to be sure) $string = str_replace("\\'", "'", $string); $string = str_replace('\\"', '"', $string); @@ -338,16 +312,15 @@ function stripslashes_safe($string) { } /** - * Given some normal text, this function will break up any - * long words to a given size, by inserting the given character + * Given some normal text this function will break up any + * long words to a given size by inserting the given character + * * @param string $string the string to be modified * @param integer $maxsize maximum length of the string to be returned * @param string $cutchar the string used to represent word breaks * @return string */ function break_up_long_words($string, $maxsize=20, $cutchar=' ') { -/// Given some normal text, this function will break up any -/// long words to a given size, by inserting the given character if (in_array(current_language(), array('ja', 'zh_cn', 'zh_tw', 'zh_tw_utf8'))) { // Multibyte languages return $string; @@ -378,6 +351,7 @@ function break_up_long_words($string, $maxsize=20, $cutchar=' ') { * This function is only used for versions of PHP older than version 5 * which do not have a native version of this function. * Taken from the PHP manual, by bradhuizenga @ softhome.net + * * @param string $find the string to search for * @param string $replace the string to replace $find with * @param string $string the string to search through @@ -385,10 +359,6 @@ function break_up_long_words($string, $maxsize=20, $cutchar=' ') { */ if (!function_exists('str_ireplace')) { /// Only exists in PHP 5 function str_ireplace($find, $replace, $string) { - /// This does a search and replace, ignoring case - /// This function is only used for versions of PHP older than version 5 - /// which do not have a native version of this function. - /// Taken from the PHP manual, by bradhuizenga @ softhome.net if (!is_array($find)) { $find = array($find); @@ -427,15 +397,14 @@ if (!function_exists('str_ireplace')) { /// Only exists in PHP 5 * This function is only used for versions of PHP older than version 5 * which do not have a native version of this function. * Taken from the PHP manual, by dmarsh @ spscc.ctc.edu + * * @param string $haystack The string to be searched * @param string $needle The string to search for * @param integer $offset The position in $haystack where the search should begin. */ if (!function_exists('stripos')) { /// Only exists in PHP 5 function stripos($haystack, $needle, $offset=0) { - /// This function is only used for versions of PHP older than version 5 - /// which do not have a native version of this function. - /// Taken from the PHP manual, by dmarsh @ spscc.ctc.edu + return strpos(strtoupper($haystack), strtoupper($needle), $offset); } } @@ -448,15 +417,11 @@ if (!function_exists('stripos')) { /// Only exists in PHP 5 * object (whatever you decide to use). * * WARNING: do not use this on big files!! + * * @param string $filename Location on the server's filesystem where template can be found. * @param mixed $var Passed in by reference. An array or object which will be loaded with data from the template file. */ function read_template($filename, &$var) { -/// return a (big) string containing the contents of a template file with all -/// the variables interpolated. all the variables must be in the $var[] array or -/// object (whatever you decide to use). -/// -/// WARNING: do not use this on big files!! $temp = str_replace("\\", "\\\\", implode(file($filename), '')); $temp = str_replace('"', '\"', $temp); @@ -470,14 +435,12 @@ function read_template($filename, &$var) { * If variable is set, set it to the set_value otherwise set it to the * unset_value. used to handle checkboxes when you are expecting them from * a form + * * @param mixed $var Passed in by reference. The variable to check. * @param mixed $set_value The value to set $var to if $var already has a value. * @param mixed $unset_value The value to set $var to if $var does not already have a value. */ function checked(&$var, $set_value = 1, $unset_value = 0) { -/// if variable is set, set it to the set_value otherwise set it to the -/// unset_value. used to handle checkboxes when you are expecting them from -/// a form if (empty($var)) { $var = $unset_value; @@ -488,14 +451,13 @@ function checked(&$var, $set_value = 1, $unset_value = 0) { /** * Prints the word "checked" if a variable is true, otherwise prints nothing, - * used for printing the word "checked" in a checkbox form element + * used for printing the word "checked" in a checkbox form element. + * * @param boolean $var Variable to be checked for true value * @param string $true_value Value to be printed if $var is true * @param string $false_value Value to be printed if $var is false */ function frmchecked(&$var, $true_value = 'checked', $false_value = '') { -/// prints the word "checked" if a variable is true, otherwise prints nothing, -/// used for printing the word "checked" in a checkbox form input if ($var) { echo $true_value; @@ -508,6 +470,7 @@ function frmchecked(&$var, $true_value = 'checked', $false_value = '') { * This function will create a HTML link that will work on both * Javascript and non-javascript browsers. * Relies on the Javascript function openpopup in javascript.php + * * $url must be relative to home page eg /mod/survey/stuff.php * @param string $url Web link relative to home page * @param string $name Name to be assigned to the popup window @@ -523,10 +486,6 @@ function frmchecked(&$var, $true_value = 'checked', $false_value = '') { */ function link_to_popup_window ($url, $name='popup', $linkname='click here', $height=400, $width=500, $title='Popup window', $options='none', $return=false) { -/// This will create a HTML link that will work on both -/// Javascript and non-javascript browsers. -/// Relies on the Javascript function openpopup in javascript.php -/// $url must be relative to home page eg /mod/survey/stuff.php global $CFG; @@ -552,6 +511,7 @@ function link_to_popup_window ($url, $name='popup', $linkname='click here', * This function will print a button submit form element * that will work on both Javascript and non-javascript browsers. * Relies on the Javascript function openpopup in javascript.php + * * $url must be relative to home page eg /mod/survey/stuff.php * @param string $url Web link relative to home page * @param string $name Name to be assigned to the popup window @@ -566,10 +526,6 @@ function link_to_popup_window ($url, $name='popup', $linkname='click here', */ function button_to_popup_window ($url, $name='popup', $linkname='click here', $height=400, $width=500, $title='Popup window', $options='none') { -/// This will create a HTML link that will work on both -/// Javascript and non-javascript browsers. -/// Relies on the Javascript function openpopup in javascript.php -/// $url must be relative to home page eg /mod/survey/stuff.php global $CFG; @@ -587,7 +543,6 @@ function button_to_popup_window ($url, $name='popup', $linkname='click here', * Prints a simple button to close a window */ function close_window_button() { -/// Prints a simple button to close a window echo '
' . "\n"; echo ''."\n"; } - +/** + * Returns a turn edit on/off button for course in a self contained form. + * Used to be an icon, but it's now a simple form button + * + * @param type description + * @todo Finish documenting this function + */ function update_course_icon($courseid) { -// Used to be an icon, but it's now a simple form button +// global $CFG, $USER; if (isteacheredit($courseid)) { @@ -2116,8 +2324,14 @@ function update_course_icon($courseid) { } } +/** + * Prints the editing button on a module "view" page + * + * @uses $CFG + * @param type description + * @todo Finish documenting this function + */ function update_module_button($moduleid, $courseid, $string) { -// Prints the editing button on a module "view" page global $CFG; if (isteacheredit($courseid)) { @@ -2131,8 +2345,15 @@ function update_module_button($moduleid, $courseid, $string) { } } +/** + * Prints the editing button on a category page + * + * @uses $CFG + * @uses $USER + * @param type description + * @todo Finish documenting this function + */ function update_category_button($categoryid) { -// Prints the editing button on a category page global $CFG, $USER; if (iscreator()) { @@ -2150,8 +2371,13 @@ function update_category_button($categoryid) { } } +/** + * Prints the editing button on categories listing + * + * @param type description + * @todo Finish documenting this function + */ function update_categories_button() { -// Prints the editing button on categories listing global $CFG, $USER; if (isadmin()) { @@ -2168,8 +2394,13 @@ function update_categories_button() { } } +/** + * Prints the editing button on group page + * + * @param type description + * @todo Finish documenting this function + */ function update_group_button($courseid, $groupid) { -// Prints the editing button on group page global $CFG, $USER; if (isteacheredit($courseid)) { @@ -2182,8 +2413,13 @@ function update_group_button($courseid, $groupid) { } } +/** + * Prints the editing button on groups page + * + * @param type description + * @todo Finish documenting this function + */ function update_groups_button($courseid) { -// Prints the editing button on groups page global $CFG, $USER; if (isteacheredit($courseid)) { @@ -2201,8 +2437,13 @@ function update_groups_button($courseid) { } } +/** + * Prints an appropriate group selection menu + * + * @param type description + * @todo Finish documenting this function + */ function print_group_menu($groups, $groupmode, $currentgroup, $urlroot) { -/// Prints an appropriate group selection menu /// Add an "All groups" to the start of the menu $groupsmenu[0] = get_string('allparticipants'); @@ -2223,13 +2464,17 @@ function print_group_menu($groups, $groupmode, $currentgroup, $urlroot) { } - +/** + * Given a course and a (current) coursemodule + * This function returns a small popup menu with all the + * course activity modules in it, as a navigation menu + * The data is taken from the serialised array stored in + * the course record + * + * @param type description + * @todo Finish documenting this function + */ function navmenu($course, $cm=NULL, $targetwindow='self') { -// Given a course and a (current) coursemodule -// This function returns a small popup menu with all the -// course activity modules in it, as a navigation menu -// The data is taken from the serialised array stored in -// the course record global $CFG; @@ -2334,10 +2579,16 @@ function navmenu($course, $cm=NULL, $targetwindow='self') { ''. $nextmod .''; } - +/** + * Prints form items with the names $day, $month and $year + * + * @param ? $day ? + * @param ? $month ? + * @param ? $year ? + * @param integer $currenttime A default timestamp in GMT + * @todo Finish documenting this function + */ function print_date_selector($day, $month, $year, $currenttime=0) { -// Currenttime is a default timestamp in GMT -// Prints form items with the names $day, $month and $year if (!$currenttime) { $currenttime = time(); @@ -2358,9 +2609,16 @@ function print_date_selector($day, $month, $year, $currenttime=0) { choose_from_menu($years, $year, $currentdate['year'], ''); } +/** + *Prints form items with the names $hour and $minute + * + * @param ? $hour ? + * @param ? $minute ? + * @param $currenttime A default timestamp in GMT + * @param integer $step ? + * @todo Finish documenting this function + */ function print_time_selector($hour, $minute, $currenttime=0, $step=5) { -// Currenttime is a default timestamp in GMT -// Prints form items with the names $hour and $minute if (!$currenttime) { $currenttime = time(); @@ -2379,8 +2637,15 @@ function print_time_selector($hour, $minute, $currenttime=0, $step=5) { choose_from_menu($minutes, $minute, $currentdate['minutes'], ''); } +/** + * Prints time limit value selector + * + * @uses $CFG + * @param integer $timelimit ? + * @param string $unit ? + * @todo Finish documenting this function + */ function print_timer_selector($timelimit = 0, $unit = '') { -/// Prints time limit value selector global $CFG; @@ -2397,9 +2662,14 @@ function print_timer_selector($timelimit = 0, $unit = '') { choose_from_menu($minutes, 'timelimit', $timelimit, get_string('none')); } -function print_grade_menu($courseid, $name, $current, $includenograde=true) { -/// Prints a grade menu (as part of an existing form) with help -/// Showing all possible numerical grades and scales +/** + * Prints a grade menu (as part of an existing form) with help + * Showing all possible numerical grades and scales + * + * @param type description + * @todo Finish documenting this function + */ +function print_grade_menu($courseid, $name, $current, $includenograde=true) { global $CFG; @@ -2424,9 +2694,14 @@ function print_grade_menu($courseid, $name, $current, $includenograde=true) { $linkobject, 400, 500, $strscales); } +/** + * Prints a scale menu (as part of an existing form) including help button + * Just like print_grade_menu but without the numerical grades + * + * @param type description + * @todo Finish documenting this function + */ function print_scale_menu($courseid, $name, $current) { -/// Prints a scale menu (as part of an existing form) including help button -/// Just like print_grade_menu but without the numerical grades global $CFG; @@ -2438,10 +2713,15 @@ function print_scale_menu($courseid, $name, $current) { $linkobject, 400, 500, $strscales); } - +/** + * Prints a help button about a scale + * + * @uses $CFG + * @param id $courseid ? + * @param object $scale ? + * @todo Finish documenting this function + */ function print_scale_menu_helpbutton($courseid, $scale) { -/// Prints a help button about a scale -/// scale is an object global $CFG; @@ -2452,7 +2732,12 @@ function print_scale_menu_helpbutton($courseid, $scale) { $linkobject, 400, 500, $scale->name); } - +/** + * Print an error page displaying an error message. + * + * @param string $message The message to display to the user about the error. + * @param string $link The url where the user will be prompted to continue. If no url is provided the user will be directed to the site index page. + */ function error ($message, $link='') { global $CFG, $SESSION; @@ -2473,6 +2758,12 @@ function error ($message, $link='') { die; } +/** + * Print a help button. + * + * @param type description + * @todo Finish documenting this function + */ function helpbutton ($page, $title='', $module='moodle', $image=true, $linktext=false, $text='', $return=false) { // $page = the keyword that defines a help page // $title = the title of links, rollover tips, alt tags etc @@ -2513,6 +2804,12 @@ function helpbutton ($page, $title='', $module='moodle', $image=true, $linktext= } } +/** + * Print a help button. + * + * @param type description + * @todo Finish documenting this function + */ function emoticonhelpbutton($form, $field) { /// Prints a special help button that is a link to the "live" emoticon popup global $CFG, $SESSION; @@ -2527,6 +2824,12 @@ function emoticonhelpbutton($form, $field) { echo '
'; } +/** + * Print a message and exit. + * + * @param type description + * @todo Finish documenting this function + */ function notice ($message, $link='') { global $CFG, $THEME; @@ -2545,22 +2848,32 @@ function notice ($message, $link='') { die; } +/** + * Print a message along with "Yes" and "No" links for the user to continue. + * + * @param type description + * @todo Finish documenting this function + */ function notice_yesno ($message, $linkyes, $linkno) { global $THEME; print_simple_box_start('center', '60%', $THEME->cellheading); echo '

'. $message .'

'; - echo '

'; + echo '

'; echo ''. get_string('yes') .''; echo '      '; echo ''. get_string('no') .''; - echo '

'; + echo '

'; print_simple_box_end(); } +/** + * Redirects the user to another page, after printing a notice + * + * @param type description + * @todo Finish documenting this function + */ function redirect($url, $message='', $delay='0') { -// Redirects the user to another page, after printing a notice - // '&' needs to be encoded into '&' for XHTML compliance, // however, this is not true for javascript. Therefore we // first decode all entities in $url (since we cannot rely on) @@ -2587,12 +2900,25 @@ function redirect($url, $message='', $delay='0') { die; } +/** + * Print a bold message in an optional color. + * + * @param type description + * @todo Finish documenting this function + */ function notify ($message, $color='red', $align='center') { - echo '

'. $message .'

' . "\n"; + echo '

'. $message .'

' . "\n"; } -function obfuscate_email($email) { -/// Given an email address, this function will return an obfuscated version of it + +/** + * Given an email address, this function will return an obfuscated version of it + * + * @param type description + * @todo Finish documenting this function + */ + function obfuscate_email($email) { + $i = 0; $length = strlen($email); $obfuscated = ''; @@ -2607,9 +2933,15 @@ function obfuscate_email($email) { return $obfuscated; } +/** + * This function takes some text and replaces about half of the characters + * with HTML entity equivalents. Return string is obviously longer. + * + * @param type description + * @todo Finish documenting this function + */ function obfuscate_text($plaintext) { -/// This function takes some text and replaces about half of the characters -/// with HTML entity equivalents. Return string is obviously longer. + $i=0; $length = strlen($plaintext); $obfuscated=''; @@ -2631,9 +2963,14 @@ function obfuscate_text($plaintext) { return $obfuscated; } +/** + * This function uses the above two functions to generate a fully + * obfuscated email link, ready to use. + * + * @param type description + * @todo Finish documenting this function + */ function obfuscate_mailto($email, $label='', $dimmed=false) { -/// This function uses the above two functions to generate a fully -/// obfuscated email link, ready to use. if (empty($label)) { $label = $email; @@ -2650,8 +2987,13 @@ function obfuscate_mailto($email, $label='', $dimmed=false) { obfuscate_text($label)); } +/** + * Prints a single paging bar to provide access to other pages (usually in a search) + * + * @param type description + * @todo Finish documenting this function + */ function print_paging_bar($totalcount, $page, $perpage, $baseurl) { -/// Prints a single paging bar to provide access to other pages (usually in a search) $maxdisplay = 18; @@ -2694,8 +3036,13 @@ function print_paging_bar($totalcount, $page, $perpage, $baseurl) { } } -//This function is used to rebuild the tag because some formats (PLAIN and WIKI) -//will transform it to html entities +/** + * This function is used to rebuild the tag because some formats (PLAIN and WIKI) + * will transform it to html entities + * + * @param type description + * @todo Finish documenting this function + */ function rebuildnolinktag($text) { $text = preg_replace('/<(\/*nolink)>/i','<$1>',$text); @@ -2710,9 +3057,14 @@ function rebuildnolinktag($text) { // THREE FUNCTIONS MOVED HERE FROM course/lib.php // ================================================ -function print_side_block($heading='', $content='', $list=NULL, $icons=NULL, $footer='', $attributes = array()) { -// Prints a nice side block with an optional header. The content can either -// be a block of HTML or a list of text with optional icons. +/** + * Prints a nice side block with an optional header. The content can either + * be a block of HTML or a list of text with optional icons. + * + * @param type description + * @todo Finish documenting this function + */ +function print_side_block($heading='', $content='', $list=NULL, $icons=NULL, $footer='', $attributes = array()) { global $THEME; @@ -2751,8 +3103,13 @@ function print_side_block($heading='', $content='', $list=NULL, $icons=NULL, $fo print_side_block_end(); } +/** + * Starts a nice side block with an optional header. + * + * @param type description + * @todo Finish documenting this function + */ function print_side_block_start($heading='', $attributes = array()) { -// Starts a nice side block with an optional header. global $THEME; // If there are no special attributes, give a default CSS class @@ -2784,14 +3141,25 @@ function print_side_block_start($heading='', $attributes = array()) { } - +/** + * Print table ending tags for a side block box. + * + * @param type description + * @todo Finish documenting this function + */ function print_side_block_end() { echo '
'; echo "\n"; } -function print_editor_config() { -/// prints out the editor config. + +/** + * prints out the editor config. + * + * @param type description + * @todo Finish documenting this function + */ + function print_editor_config() { global $CFG; @@ -2836,9 +3204,14 @@ function print_editor_config() { } } -function print_speller_code ($usehtmleditor=false) { -/// Prints out code needed for spellchecking. -/// Original idea by Ludo (Marc Alier). +/** + * Prints out code needed for spellchecking. + * Original idea by Ludo (Marc Alier). + * + * @param type description + * @todo Finish documenting this function + */ +function print_speller_code ($usehtmleditor=false) { global $CFG; if(!$usehtmleditor) { @@ -2863,10 +3236,14 @@ function print_speller_code ($usehtmleditor=false) { } } +/** + * Print button for spellchecking when editor is disabled + * + * @param type description + * @todo Finish documenting this function + */ function print_speller_button () { -// print button for spellchecking -// when editor is disabled echo ''."\n"; } // vim:autoindent:expandtab:shiftwidth=4:tabstop=4:tw=140: -?> +?> \ No newline at end of file -- 2.39.5