From 48d4fad10cb7c85cfc6653a4c86264d4cff65084 Mon Sep 17 00:00:00 2001 From: Sam Hemelryk Date: Thu, 5 Jan 2012 13:28:24 +1300 Subject: [PATCH] MDL-30979 output: Fixed up phpdocs for page requirements code --- lib/outputrequirementslib.php | 129 ++++++++++++++++++++++++---------- 1 file changed, 90 insertions(+), 39 deletions(-) diff --git a/lib/outputrequirementslib.php b/lib/outputrequirementslib.php index 2737fe5063b..1be25eab0ec 100644 --- a/lib/outputrequirementslib.php +++ b/lib/outputrequirementslib.php @@ -1,5 +1,4 @@ . - /** * Library functions to facilitate the use of JavaScript in Moodle. * - * @package core - * @subpackage lib - * @copyright 2009 Tim Hunt, 2010 Petr Skoda - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * Note: you can find history of this file in lib/ajax/ajaxlib.php + * + * @copyright 2009 Tim Hunt, 2010 Petr Skoda + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package core + * @subpackage output */ defined('MOODLE_INTERNAL') || die(); -// note: you can find history of this file in lib/ajax/ajaxlib.php - /** * This class tracks all the things that are needed by the current page. * @@ -53,63 +51,114 @@ defined('MOODLE_INTERNAL') || die(); * individual methods for details. * * @copyright 2009 Tim Hunt, 2010 Petr Skoda - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @since Moodle 2.0 + * @package core + * @subpackage output */ class page_requirements_manager { - /** List of string available from JS */ + + /** + * List of string available from JS + * @var array + */ protected $stringsforjs = array(); - /** List of JS variables to be initialised */ + + /** + * List of JS variables to be initialised + * @var array + */ protected $jsinitvariables = array('head'=>array(), 'footer'=>array()); - /** Included JS scripts */ + + /** + * Included JS scripts + * @var array + */ protected $jsincludes = array('head'=>array(), 'footer'=>array()); - /** List of needed function calls */ + + /** + * List of needed function calls + * @var array + */ protected $jscalls = array('normal'=>array(), 'ondomready'=>array()); + /** * List of skip links, those are needed for accessibility reasons * @var array */ protected $skiplinks = array(); + /** * Javascript code used for initialisation of page, it should be relatively small * @var array */ protected $jsinitcode = array(); + /** * Theme sheets, initialised only from core_renderer * @var array of moodle_url */ protected $cssthemeurls = array(); + /** * List of custom theme sheets, these are strongly discouraged! * Useful mostly only for CSS submitted by teachers that is not part of the theme. * @var array of moodle_url */ protected $cssurls = array(); + /** * List of requested event handlers * @var array */ protected $eventhandlers = array(); + /** * Extra modules * @var array */ protected $extramodules = array(); - /** Flag indicated head stuff already printed */ + + /** + * Flag indicated head stuff already printed + * @var bool + */ protected $headdone = false; - /** Flag indicating top of body already printed */ + + /** + * Flag indicating top of body already printed + * @var bool + */ protected $topofbodydone = false; - /** YUI PHPLoader instance responsible for YUI2 loading from PHP only */ + /** + * YUI PHPLoader instance responsible for YUI2 loading from PHP only + * @var YAHOO_util_Loader + */ protected $yui2loader; - /** YUI PHPLoader instance responsible for YUI3 loading from PHP only */ + + /** + * YUI PHPLoader instance responsible for YUI3 loading from PHP only + * @var stdClass + */ protected $yui3loader; - /** YUI loader information for YUI3 loading from javascript */ + + /** + * YUI loader information for YUI3 loading from javascript + * @var stdClass + */ protected $M_yui_loader; - /** some config vars exposed in JS, please no secret stuff there */ + + /** + * Some config vars exposed in JS, please no secret stuff there + * @var array + */ protected $M_cfg; - /** stores debug backtraces from when JS modules were included in the page */ + + /** + * Stores debug backtraces from when JS modules were included in the page + * @var array + */ protected $debug_moduleloadstacktraces = array(); /** @@ -205,8 +254,8 @@ class page_requirements_manager { } /** - * This method adds yui2 modules into the yui3 JS loader- - * @return void + * This method adds yui2 modules into the yui3 JS loader so that they can + * be easily included for use in JavaScript. */ protected function add_yui2_modules() { //note: this function is definitely not perfect, because @@ -319,9 +368,8 @@ class page_requirements_manager { * @param string|moodle_url $url The path to the .js file, relative to $CFG->dirroot / $CFG->wwwroot. * For example '/mod/mymod/customscripts.js'; use moodle_url for external scripts * @param bool $inhead initialise in head - * @return void */ - public function js($url, $inhead=false) { + public function js($url, $inhead = false) { $url = $this->js_fix_url($url); $where = $inhead ? 'head' : 'footer'; $this->jsincludes[$where][$url->out()] = $url; @@ -342,7 +390,6 @@ class page_requirements_manager { * is put into the page header, otherwise it is loaded in the page footer. * * @param string|array $libname the name of the YUI2 library you require. For example 'autocomplete'. - * @return void */ public function yui2_lib($libname) { $libnames = (array)$libname; @@ -353,6 +400,7 @@ class page_requirements_manager { /** * Returns the actual url through which a script is served. + * * @param moodle_url|string $url full moodle url, or shortened path to script * @return moodle_url */ @@ -380,6 +428,7 @@ class page_requirements_manager { /** * Find out if JS module present and return details. + * * @param string $component name of component in frankenstyle, ex: core_group, mod_forum * @return array description of module or null if not found */ @@ -388,7 +437,6 @@ class page_requirements_manager { $module = null; - if (strpos($component, 'core_') === 0) { // must be some core stuff - list here is not complete, this is just the stuff used from multiple places // so that we do nto have to repeat the definition of these modules over and over again @@ -488,7 +536,8 @@ class page_requirements_manager { /** * Append YUI3 module to default YUI3 JS loader. - * The structure of module array is described at http://developer.yahoo.com/yui/3/yui/: + * The structure of module array is described at {@link http://developer.yahoo.com/yui/3/yui/} + * * @param string|array $module name of module (details are autodetected), or full module specification as array * @return void */ @@ -616,6 +665,7 @@ class page_requirements_manager { /** * Add theme stylkesheet to page - do not use from plugin code, * this should be called only from the core renderer! + * * @param moodle_url $stylesheet * @return void */ @@ -667,9 +717,9 @@ class page_requirements_manager { * @param array $arguments and array of arguments to be passed to the function. * When generating the function call, this will be escaped using json_encode, * so passing objects and arrays should work. - * @param bool $ondomready - * @param int $delay - * @return void + * @param bool $ondomready If tru the function is only called when the dom is + * ready for manipulation. + * @param int $delay The delay before the function is called. */ public function js_function_call($function, array $arguments = null, $ondomready = false, $delay = 0) { $where = $ondomready ? 'ondomready' : 'normal'; @@ -739,7 +789,6 @@ class page_requirements_manager { * already loaded. * @param bool $ondomready wait for dom ready (helps with some IE problems when modifying DOM) * @param array $module JS module specification array - * @return void */ public function js_init_call($function, array $extraarguments = null, $ondomready = false, array $module = null) { $jscode = js_writer::function_call_with_Y($function, $extraarguments); @@ -761,7 +810,6 @@ class page_requirements_manager { * @param string $jscode * @param bool $ondomready wait for dom ready (helps with some IE problems when modifying DOM) * @param array $module JS module specification array - * @return void */ public function js_init_code($jscode, $ondomready = false, array $module = null) { $jscode = trim($jscode, " ;\n"). ';'; @@ -905,7 +953,6 @@ class page_requirements_manager { * @param string $event A valid DOM event (click, mousedown, change etc.) * @param string $function The name of the function to call * @param array $arguments An optional array of argument parameters to pass to the function - * @return void */ public function event_handler($selector, $event, $function, array $arguments = null) { $this->eventhandlers[] = array('selector'=>$selector, 'event'=>$event, 'function'=>$function, 'arguments'=>$arguments); @@ -944,7 +991,7 @@ class page_requirements_manager { /** * Returns js code to be executed when Y is available. - * @return unknown_type + * @return string */ protected function get_javascript_init_code() { if (count($this->jsinitcode)) { @@ -1028,6 +1075,7 @@ class page_requirements_manager { /** * Returns html tags needed for inclusion of theme CSS + * * @return string */ protected function get_css_code() { @@ -1057,6 +1105,7 @@ class page_requirements_manager { /** * Adds extra modules specified after printing of page header + * * @return string */ protected function get_extra_modules_code() { @@ -1205,14 +1254,18 @@ class page_requirements_manager { } /** - * @return boolean Have we already output the code in the tag? + * Have we already output the code in the tag? + * + * @return boolean */ public function is_head_done() { return $this->headdone; } /** - * @return boolean Have we already output the code at the start of the tag? + * Have we already output the code at the start of the tag? + * + * @return boolean */ public function is_top_of_body_done() { return $this->topofbodydone; @@ -1221,7 +1274,6 @@ class page_requirements_manager { /** * Invalidate all server and client side JS caches. - * @return void */ function js_reset_all_caches() { global $CFG; @@ -1229,5 +1281,4 @@ function js_reset_all_caches() { set_config('jsrev', empty($CFG->jsrev) ? 1 : $CFG->jsrev+1); fulldelete("$CFG->cachedir/js"); -} - +} \ No newline at end of file