Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/ -> outputrequirementslib.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]
Library functions to facilitate the use of JavaScript in Moodle. 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 |
| File Size: | 2186 lines (89 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
Defines 2 classes
page_requirements_manager:: (44 methods):
__construct()
get_config_for_javascript()
init_requirements_data()
get_jsrev()
get_templaterev()
js()
jquery()
jquery_plugin()
jquery_override_plugin()
get_jquery_headcode()
js_fix_url()
find_module()
js_module()
js_module_loaded()
css()
css_theme()
skip_link_to()
js_function_call()
js_amd_inline()
js_call_amd()
yui_module()
set_yuicssmodules()
js_init_call()
js_init_code()
string_for_js()
strings_for_js()
data_for_js()
event_handler()
get_event_handler_code()
get_javascript_code()
get_javascript_init_code()
get_amd_footercode()
get_yui3lib_headcss()
get_yui3lib_headcode()
get_css_code()
get_extra_modules_code()
get_head_code()
get_top_of_body_code()
get_end_code()
is_head_done()
is_top_of_body_done()
should_create_one_time_item_now()
has_one_time_item_been_created()
set_one_time_item_created()
YUI_config:: (13 methods):
add_group()
update_group()
set_config_function()
set_config_source()
get_config_functions()
update_header_js()
add_module_config()
add_moodle_metadata()
get_moodle_metadata()
get_moodle_path_metadata()
define_patched_core_modules()
template_reset_all_caches()
js_reset_all_caches()
Class: page_requirements_manager - X-Ref
This class tracks all the things that are needed by the current page.Normally, the only instance of this class you will need to work with is the
one accessible via $PAGE->requires.
Typical usage would be
<pre>
$PAGE->requires->js_call_amd('mod_forum/view', 'init');
</pre>
It also supports obsoleted coding style with/without YUI3 modules.
<pre>
$PAGE->requires->js_init_call('M.mod_forum.init_view');
$PAGE->requires->css('/mod/mymod/userstyles.php?id='.$id); // not overridable via themes!
$PAGE->requires->js('/mod/mymod/script.js');
$PAGE->requires->js('/mod/mymod/small_but_urgent.js', true);
$PAGE->requires->js_function_call('init_mymod', array($data), true);
</pre>
There are some natural restrictions on some methods. For example, {@link css()}
can only be called before the <head> tag is output. See the comments on the
individual methods for details.
| __construct() X-Ref |
| Page requirements constructor. |
| get_config_for_javascript(moodle_page $page, renderer_base $renderer) X-Ref |
| Return the safe config values that get set for javascript in "M.cfg". return: array List of safe config values that are available to javascript. |
| init_requirements_data(moodle_page $page, core_renderer $renderer) X-Ref |
| Initialise with the bits of JavaScript that every Moodle page should have. param: moodle_page $page param: core_renderer $renderer |
| get_jsrev() X-Ref |
| Determine the correct JS Revision to use for this load. return: int the jsrev to use. |
| get_templaterev() X-Ref |
| Determine the correct Template revision to use for this load. return: int the templaterev to use. |
| js($url, $inhead = false) X-Ref |
| Ensure that the specified JavaScript file is linked to from this page. NOTE: This function is to be used in RARE CASES ONLY, please store your JS in module.js file and use $PAGE->requires->js_init_call() instead or use /yui/ subdirectories for YUI modules. By default the link is put at the end of the page, since this gives best page-load performance. Even if a particular script is requested more than once, it will only be linked to once. param: string|moodle_url $url The path to the .js file, relative to $CFG->dirroot / $CFG->wwwroot. param: bool $inhead initialise in head |
| jquery() X-Ref |
| Request inclusion of jQuery library in the page. NOTE: this should not be used in official Moodle distribution! {@link https://moodledev.io/docs/guides/javascript/jquery} |
| jquery_plugin($plugin, $component = 'core') X-Ref |
| Request inclusion of jQuery plugin. NOTE: this should not be used in official Moodle distribution! jQuery plugins are located in plugin/jquery/* subdirectory, plugin/jquery/plugins.php lists all available plugins. Included core plugins: - jQuery UI Add-ons may include extra jQuery plugins in jquery/ directory, plugins.php file defines the mapping between plugin names and necessary page includes. Examples: <code> // file: mod/xxx/view.php $PAGE->requires->jquery(); $PAGE->requires->jquery_plugin('ui'); $PAGE->requires->jquery_plugin('ui-css'); </code> <code> // file: theme/yyy/lib.php function theme_yyy_page_init(moodle_page $page) { $page->requires->jquery(); $page->requires->jquery_plugin('ui'); $page->requires->jquery_plugin('ui-css'); } </code> <code> // file: blocks/zzz/block_zzz.php public function get_required_javascript() { parent::get_required_javascript(); $this->page->requires->jquery(); $page->requires->jquery_plugin('ui'); $page->requires->jquery_plugin('ui-css'); } </code> {@link https://moodledev.io/docs/guides/javascript/jquery} param: string $plugin name of the jQuery plugin as defined in jquery/plugins.php param: string $component name of the component return: bool success |
| jquery_override_plugin($oldplugin, $newplugin) X-Ref |
| Request replacement of one jQuery plugin by another. This is useful when themes want to replace the jQuery UI theme, the problem is that theme can not prevent others from including the core ui-css plugin. Example: 1/ generate new jQuery UI theme and place it into theme/yourtheme/jquery/ 2/ write theme/yourtheme/jquery/plugins.php 3/ init jQuery from theme <code> // file theme/yourtheme/lib.php function theme_yourtheme_page_init($page) { $page->requires->jquery_plugin('yourtheme-ui-css', 'theme_yourtheme'); $page->requires->jquery_override_plugin('ui-css', 'yourtheme-ui-css'); } </code> This code prevents loading of standard 'ui-css' which my be requested by other plugins, the 'yourtheme-ui-css' gets loaded only if some other code requires jquery. {@link https://moodledev.io/docs/guides/javascript/jquery} param: string $oldplugin original plugin param: string $newplugin the replacement |
| get_jquery_headcode() X-Ref |
| Return jQuery related markup for page start. return: string |
| js_fix_url($url) X-Ref |
| 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 |
| find_module($component) X-Ref |
| 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 |
| js_module($module) X-Ref |
| Append YUI3 module to default YUI3 JS loader. 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 |
| js_module_loaded($module) X-Ref |
| Returns true if the module has already been loaded. param: string|array $module return: bool True if the module has already been loaded |
| css($stylesheet) X-Ref |
| Ensure that the specified CSS file is linked to from this page. Because stylesheet links must go in the <head> part of the HTML, you must call this function before {@link get_head_code()} is called. That normally means before the call to print_header. If you call it when it is too late, an exception will be thrown. Even if a particular style sheet is requested more than once, it will only be linked to once. Please note use of this feature is strongly discouraged, it is suitable only for places where CSS is submitted directly by teachers. (Students must not be allowed to submit any external CSS because it may contain embedded javascript!). Example of correct use is mod/data. param: string $stylesheet The path to the .css file, relative to $CFG->wwwroot. |
| css_theme(moodle_url $stylesheet) X-Ref |
| Add theme stylesheet to page - do not use from plugin code, this should be called only from the core renderer! param: moodle_url $stylesheet return: void |
| skip_link_to($target, $linktext) X-Ref |
| Ensure that a skip link to a given target is printed at the top of the <body>. You must call this function before {@link get_top_of_body_code()}, (if not, an exception will be thrown). That normally means you must call this before the call to print_header. If you ask for a particular skip link to be printed, it is then your responsibility to ensure that the appropriate <a name="..."> tag is printed in the body of the page, so that the skip link goes somewhere. Even if a particular skip link is requested more than once, only one copy of it will be output. param: string $target the name of anchor this link should go to. For example 'maincontent'. param: string $linktext The text to use for the skip link. Normally get_string('skipto', 'access', ...); |
| js_function_call($function, array $arguments = null, $ondomready = false, $delay = 0) X-Ref |
| !!!DEPRECATED!!! please use js_init_call() if possible Ensure that the specified JavaScript function is called from an inline script somewhere on this page. By default the call will be put in a script tag at the end of the page after initialising Y instance, since this gives best page-load performance and allows you to use YUI3 library. If you request that a particular function is called several times, then that is what will happen (unlike linking to a CSS or JS file, where only one link will be output). The main benefit of the method is the automatic encoding of all function parameters. param: string $function the name of the JavaScritp function to call. Can param: array $arguments and array of arguments to be passed to the function. param: bool $ondomready If tru the function is only called when the dom is param: int $delay The delay before the function is called. |
| js_amd_inline($code) X-Ref |
| This function appends a block of code to the AMD specific javascript block executed in the page footer, just after loading the requirejs library. The code passed here can rely on AMD module loading, e.g. require('jquery', function($) {...}); param: string $code The JS code to append. |
| js_call_amd($fullmodule, $func = null, $params = array() X-Ref |
| Load an AMD module and eventually call its method. This function creates a minimal inline JS snippet that requires an AMD module and eventually calls a single function from the module with given arguments. If it is called multiple times, it will be create multiple snippets. param: string $fullmodule The name of the AMD module to load, formatted as <component name>/<module name>. param: string $func Optional function from the module to call, defaults to just loading the AMD module. param: array $params The params to pass to the function (will be serialized into JSON). |
| yui_module($modules, $function, array $arguments = null, $galleryversion = null, $ondomready = false) X-Ref |
| Creates a JavaScript function call that requires one or more modules to be loaded. This function can be used to include all of the standard YUI module types within JavaScript: - YUI3 modules [node, event, io] - YUI2 modules [yui2-*] - Moodle modules [moodle-*] - Gallery modules [gallery-*] Before writing new code that makes extensive use of YUI, you should consider it's replacement AMD/JQuery. param: array|string $modules One or more modules param: string $function The function to call once modules have been loaded param: array $arguments An array of arguments to pass to the function param: string $galleryversion Deprecated: The gallery version to use param: bool $ondomready |
| set_yuicssmodules(array $modules = array() X-Ref |
| Set the CSS Modules to be included from YUI. param: array $modules The list of YUI CSS Modules to include. |
| js_init_call($function, array $extraarguments = null, $ondomready = false, array $module = null) X-Ref |
| Ensure that the specified JavaScript function is called from an inline script from page footer. param: string $function the name of the JavaScritp function to with init code, param: array $extraarguments and array of arguments to be passed to the function. param: bool $ondomready wait for dom ready (helps with some IE problems when modifying DOM) param: array $module JS module specification array |
| js_init_code($jscode, $ondomready = false, array $module = null) X-Ref |
| Add short static javascript code fragment to page footer. This is intended primarily for loading of js modules and initialising page layout. Ideally the JS code fragment should be stored in plugin renderer so that themes may override it. 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 |
| string_for_js($identifier, $component, $a = null) X-Ref |
| Make a language string available to JavaScript. All the strings will be available in a M.str object in the global namespace. So, for example, after a call to $PAGE->requires->string_for_js('course', 'moodle'); then the JavaScript variable M.str.moodle.course will be 'Course', or the equivalent in the current language. The arguments to this function are just like the arguments to get_string except that $component is not optional, and there are some aspects to consider when the string contains {$a} placeholder. If the string does not contain any {$a} placeholder, you can simply use M.str.component.identifier to obtain it. If you prefer, you can call M.util.get_string(identifier, component) to get the same result. If you need to use {$a} placeholders, there are two options. Either the placeholder should be substituted in PHP on server side or it should be substituted in Javascript at client side. To substitute the placeholder at server side, just provide the required value for the placeholder when you require the string. Because each string is only stored once in the JavaScript (based on $identifier and $module) you cannot get the same string with two different values of $a. If you try, an exception will be thrown. Once the placeholder is substituted, you can use M.str or M.util.get_string() as shown above: // Require the string in PHP and replace the placeholder. $PAGE->requires->string_for_js('fullnamedisplay', 'moodle', $USER); // Use the result of the substitution in Javascript. alert(M.str.moodle.fullnamedisplay); To substitute the placeholder at client side, use M.util.get_string() function. It implements the same logic as {@link get_string()}: // Require the string in PHP but keep {$a} as it is. $PAGE->requires->string_for_js('fullnamedisplay', 'moodle'); // Provide the values on the fly in Javascript. user = { firstname : 'Harry', lastname : 'Potter' } alert(M.util.get_string('fullnamedisplay', 'moodle', user); If you do need the same string expanded with different $a values in PHP on server side, then the solution is to put them in your own data structure (e.g. and array) that you pass to JavaScript with {@link data_for_js()}. param: string $identifier the desired string. param: string $component the language file to look in. param: mixed $a any extra data to add into the string (optional). |
| strings_for_js($identifiers, $component, $a = null) X-Ref |
| Make an array of language strings available for JS. This function calls the above function {@link string_for_js()} for each requested string in the $identifiers array that is passed to the argument for a single module passed in $module. <code> $PAGE->requires->strings_for_js(array('one', 'two', 'three'), 'mymod', array('a', null, 3)); // The above is identical to calling: $PAGE->requires->string_for_js('one', 'mymod', 'a'); $PAGE->requires->string_for_js('two', 'mymod'); $PAGE->requires->string_for_js('three', 'mymod', 3); </code> param: array $identifiers An array of desired strings param: string $component The module to load for param: mixed $a This can either be a single variable that gets passed as extra |
| data_for_js($variable, $data, $inhead=false) X-Ref |
| !!!!!!DEPRECATED!!!!!! please use js_init_call() for everything now. Make some data from PHP available to JavaScript code. For example, if you call <pre> $PAGE->requires->data_for_js('mydata', array('name' => 'Moodle')); </pre> then in JavsScript mydata.name will be 'Moodle'. param: string $variable the the name of the JavaScript variable to assign the data to. param: mixed $data The data to pass to JavaScript. This will be escaped using json_encode, param: bool $inhead initialise in head return: void |
| event_handler($selector, $event, $function, array $arguments = null) X-Ref |
| Creates a YUI event handler. param: mixed $selector standard YUI selector for elements, may be array or string, element id is in the form "#idvalue" 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 |
| get_event_handler_code() X-Ref |
| Returns code needed for registering of event handlers. return: string JS code |
| get_javascript_code($ondomready) X-Ref |
| Get the inline JavaScript code that need to appear in a particular place. param: bool $ondomready return: string |
| get_javascript_init_code() X-Ref |
| Returns js code to be executed when Y is available. return: string |
| get_amd_footercode() X-Ref |
| Returns js code to load amd module loader, then insert inline script tags that contain require() calls using RequireJS. return: string |
| get_yui3lib_headcss() X-Ref |
| Returns basic YUI3 CSS code. return: string |
| get_yui3lib_headcode() X-Ref |
| Returns basic YUI3 JS loading code. return: string |
| get_css_code() X-Ref |
| Returns html tags needed for inclusion of theme CSS. return: string |
| get_extra_modules_code() X-Ref |
| Adds extra modules specified after printing of page header. return: string |
| get_head_code(moodle_page $page, core_renderer $renderer) X-Ref |
| Generate any HTML that needs to go inside the <head> tag. Normally, this method is called automatically by the code that prints the <head> tag. You should not normally need to call it in your own code. param: moodle_page $page param: core_renderer $renderer return: string the HTML code to to inside the <head> tag. |
| get_top_of_body_code(renderer_base $renderer) X-Ref |
| Generate any HTML that needs to go at the start of the <body> tag. Normally, this method is called automatically by the code that prints the <head> tag. You should not normally need to call it in your own code. param: renderer_base $renderer return: string the HTML code to go at the start of the <body> tag. |
| get_end_code() X-Ref |
| Generate any HTML that needs to go at the end of the page. Normally, this method is called automatically by the code that prints the page footer. You should not normally need to call it in your own code. return: string the HTML code to to at the end of the page. |
| is_head_done() X-Ref |
| Have we already output the code in the <head> tag? return: bool |
| is_top_of_body_done() X-Ref |
| Have we already output the code at the start of the <body> tag? return: bool |
| should_create_one_time_item_now($thing) X-Ref |
| Should we generate a bit of content HTML that is only required once on this page (e.g. the contents of the modchooser), now? Basically, we call {@link has_one_time_item_been_created()}, and if the thing has not already been output, we return true to tell the caller to generate it, and also call {@link set_one_time_item_created()} to record the fact that it is about to be generated. That is, a typical usage pattern (in a renderer method) is: <pre> if (!$this->page->requires->should_create_one_time_item_now($thing)) { return ''; } // Else generate it. </pre> param: string $thing identifier for the bit of content. Should be of the form return: bool if true, the caller should generate that bit of output now, otherwise don't. |
| has_one_time_item_been_created($thing) X-Ref |
| Has a particular bit of HTML that is only required once on this page (e.g. the contents of the modchooser) already been generated? Normally, you can use the {@link should_create_one_time_item_now()} helper method rather than calling this method directly. param: string $thing identifier for the bit of content. Should be of the form return: bool whether that bit of output has been created. |
| set_one_time_item_created($thing) X-Ref |
| Indicate that a particular bit of HTML that is only required once on this page (e.g. the contents of the modchooser) has been generated (or is about to be)? Normally, you can use the {@link should_create_one_time_item_now()} helper method rather than calling this method directly. param: string $thing identifier for the bit of content. Should be of the form |
Class: YUI_config - X-Ref
This class represents the YUI configuration.| add_group($name, $config) X-Ref |
| Create a new group within the YUI_config system. param: String $name The name of the group. This must be unique and param: Array $config The configuration for this group. return: void |
| update_group($name, $config) X-Ref |
| Update an existing group configuration Note, any existing configuration for that group will be wiped out. This includes module configuration. param: String $name The name of the group. This must be unique and param: Array $config The configuration for this group. return: void |
| set_config_function($function) X-Ref |
| Set the value of a configuration function used by the YUI Loader's pattern testing. Only the body of the function should be passed, and not the whole function wrapper. The JS function your write will be passed a single argument 'name' containing the name of the module being loaded. param: $function String the body of the JavaScript function. This should be used i return: String the name of the function to use in the group pattern configuration. |
| set_config_source($file) X-Ref |
| Allow setting of the config function described in {@see set_config_function} from a file. The contents of this file are then passed to set_config_function. When jsrev is positive, the function is minified and stored in a MUC cache for subsequent uses. param: $file The path to the JavaScript function used for YUI configuration. return: String the name of the function to use in the group pattern configuration. |
| get_config_functions() X-Ref |
| Retrieve the list of JavaScript functions for YUI_config groups. return: String The complete set of config functions |
| update_header_js($js) X-Ref |
| Update the header JavaScript with any required modification for the YUI Loader. param: $js String The JavaScript to manipulate. return: String the modified JS string. |
| add_module_config($name, $config, $group = null) X-Ref |
| Add configuration for a specific module. param: String $name The name of the module to add configuration for. param: Array $config The configuration for the specified module. param: String $group The name of the group to add configuration for. return: void |
| add_moodle_metadata() X-Ref |
| Add the moodle YUI module metadata for the moodle group to the YUI_config instance. If js caching is disabled, metadata will not be served causing YUI to calculate module dependencies as each module is loaded. If metadata does not exist it will be created and stored in a MUC entry. return: void |
| get_moodle_metadata() X-Ref |
| Determine the module metadata for all moodle YUI modules. This works through all modules capable of serving YUI modules, and attempts to get metadata for each of those modules. return: Array of module metadata |
| get_moodle_path_metadata($path) X-Ref |
| Helper function process and return the YUI metadata for all of the modules under the specified path. param: String $path the UNC path to the YUI src directory. return: Array the complete array for frankenstyle directory. |
| define_patched_core_modules($combobase, $yuiversion, $patchlevel, $patchedmodules) X-Ref |
| Define YUI modules which we have been required to patch between releases. We must do this because we aggressively cache content on the browser, and we must also override use of the external CDN which will serve the true authoritative copy of the code without our patches. param: String combobase The local combobase param: String yuiversion The current YUI version param: Int patchlevel The patch level we're working to for YUI param: Array patchedmodules An array containing the names of the patched modules return: void |
| template_reset_all_caches() X-Ref |
| Invalidate all server and client side template caches. |
| js_reset_all_caches() X-Ref |
| Invalidate all server and client side JS caches. |
