Commit dc39d0cf authored by Andrew Nicols's avatar Andrew Nicols
Browse files

MDL-63714 javascript: Improve docs for pendingjs

parent daf0b4f0
......@@ -653,16 +653,22 @@ M.util.complete_js = [];
/**
* Register any long running javascript code with a unique identifier.
* Should be followed with a call to js_complete with a matching
* idenfitier when the code is complete. May also be called with no arguments
* to test if there is any js calls pending. This is relied on by behat so that
* it can wait for all pending updates before interacting with a page.
* @param String uniqid - optional, if provided,
* registers this identifier until js_complete is called.
* @return boolean - True if there is any pending js.
* This is used to ensure that Behat steps do not continue with interactions until the page finishes loading.
*
* All calls to M.util.js_pending _must_ be followed by a subsequent call to M.util.js_complete with the same exact
* uniqid.
*
* This function may also be called with no arguments to test if there is any js calls pending.
*
* The uniqid specified may be any Object, including Number, String, or actual Object; however please note that the
* paired js_complete function performs a strict search for the key specified. As such, if using an Object, the exact
* Object must be passed into both functions.
*
* @param {Mixed} uniqid Register long-running code against the supplied identifier
* @return {Number} Number of pending items
*/
M.util.js_pending = function(uniqid) {
if (uniqid !== false) {
if (typeof uniqid !== 'undefined') {
M.util.pending_js.push(uniqid);
}
......@@ -690,11 +696,12 @@ YUI.add('moodle-core-io', function(Y) {
});
/**
* Unregister any long running javascript code by unique identifier.
* This function should form a matching pair with js_pending
* Unregister some long running javascript code using the unique identifier specified in M.util.js_pending.
*
* This function must be matched with an identical call to M.util.js_pending.
*
* @param String uniqid - required, unregisters this identifier
* @return boolean - True if there is any pending js.
* @param {Mixed} uniqid Register long-running code against the supplied identifier
* @return {Number} Number of pending items remaining after removing this item
*/
M.util.js_complete = function(uniqid) {
// Use the Y.Array.indexOf instead of the native because some older browsers do not support
......@@ -702,6 +709,8 @@ M.util.js_complete = function(uniqid) {
var index = Y.Array.indexOf(M.util.pending_js, uniqid);
if (index >= 0) {
M.util.complete_js.push(M.util.pending_js.splice(index, 1));
} else {
window.console.log("Unable to locate key for js_complete call", uniqid);
}
return M.util.pending_js.length;
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment