From 36f21508fbe4b0287c8b9d84850b13e32d70b153 Mon Sep 17 00:00:00 2001 From: Andrew Nicols Date: Thu, 8 Jul 2021 10:33:31 +0800 Subject: [PATCH] MDL-72108 js: Fix incorrect jsdoc examples for core/ajax --- lib/amd/build/ajax.min.js.map | 2 +- lib/amd/src/ajax.js | 32 ++++++++++++++++++++++++-------- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/lib/amd/build/ajax.min.js.map b/lib/amd/build/ajax.min.js.map index 3937de72d9c..fb2eaf46c9a 100644 --- a/lib/amd/build/ajax.min.js.map +++ b/lib/amd/build/ajax.min.js.map @@ -1 +1 @@ -{"version":3,"sources":["../src/ajax.js"],"names":["define","$","config","Log","URL","unloading","requestSuccess","responses","requests","exception","i","request","response","nosessionupdate","error","length","deferred","reject","resolve","data","Error","errorcode","window","location","relativeUrl","forEach","requestFail","jqXHR","textStatus","call","async","loginrequired","timeout","cachekey","bind","ajaxRequestData","promises","methodInfo","requestInfo","parseInt","push","index","methodname","args","Deferred","promise","done","fail","sort","join","JSON","stringify","settings","type","context","dataType","processData","contentType","script","url","wwwroot","sesskey","urlUseGet","encodeURIComponent","ajax","success"],"mappings":"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","sourcesContent":["// This file is part of Moodle - http://moodle.org/\n//\n// Moodle is free software: you can redistribute it and/or modify\n// it under the terms of the GNU General Public License as published by\n// the Free Software Foundation, either version 3 of the License, or\n// (at your option) any later version.\n//\n// Moodle is distributed in the hope that it will be useful,\n// but WITHOUT ANY WARRANTY; without even the implied warranty of\n// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n// GNU General Public License for more details.\n//\n// You should have received a copy of the GNU General Public License\n// along with Moodle. If not, see .\n\n/**\n * Standard Ajax wrapper for Moodle. It calls the central Ajax script,\n * which can call any existing webservice using the current session.\n * In addition, it can batch multiple requests and return multiple responses.\n *\n * @module core/ajax\n * @copyright 2015 Damyon Wiese \n * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later\n * @since 2.9\n */\ndefine(['jquery', 'core/config', 'core/log', 'core/url'], function($, config, Log, URL) {\n\n/**\n * A request to be performed.\n *\n * @typedef {object} request\n * @property {string} methodname The remote method to be called\n * @property {object} args The arguments to pass when fetching the remote content\n */\n\n // Keeps track of when the user leaves the page so we know not to show an error.\n var unloading = false;\n\n /**\n * Success handler. Called when the ajax call succeeds. Checks each response and\n * resolves or rejects the deferred from that request.\n *\n * @method requestSuccess\n * @private\n * @param {Object[]} responses Array of responses containing error, exception and data attributes.\n */\n var requestSuccess = function(responses) {\n // Call each of the success handlers.\n var requests = this,\n exception = null,\n i = 0,\n request,\n response,\n nosessionupdate;\n\n if (responses.error) {\n // There was an error with the request as a whole.\n // We need to reject each promise.\n // Unfortunately this may lead to duplicate dialogues, but each Promise must be rejected.\n for (; i < requests.length; i++) {\n request = requests[i];\n request.deferred.reject(responses);\n }\n\n return;\n }\n\n for (i = 0; i < requests.length; i++) {\n request = requests[i];\n\n response = responses[i];\n // We may not have responses for all the requests.\n if (typeof response !== \"undefined\") {\n if (response.error === false) {\n // Call the done handler if it was provided.\n request.deferred.resolve(response.data);\n } else {\n exception = response.exception;\n nosessionupdate = requests[i].nosessionupdate;\n break;\n }\n } else {\n // This is not an expected case.\n exception = new Error('missing response');\n break;\n }\n }\n // Something failed, reject the remaining promises.\n if (exception !== null) {\n // Redirect to the login page.\n if (exception.errorcode === \"servicerequireslogin\" && !nosessionupdate) {\n window.location = URL.relativeUrl(\"/login/index.php\");\n } else {\n requests.forEach(function(request) {\n request.deferred.reject(exception);\n });\n }\n }\n };\n\n /**\n * Fail handler. Called when the ajax call fails. Rejects all deferreds.\n *\n * @method requestFail\n * @private\n * @param {jqXHR} jqXHR The ajax object.\n * @param {string} textStatus The status string.\n * @param {Error|Object} exception The error thrown.\n */\n var requestFail = function(jqXHR, textStatus, exception) {\n // Reject all the promises.\n var requests = this;\n\n var i = 0;\n for (i = 0; i < requests.length; i++) {\n var request = requests[i];\n\n if (unloading) {\n // No need to trigger an error because we are already navigating.\n Log.error(\"Page unloaded.\");\n Log.error(exception);\n } else {\n request.deferred.reject(exception);\n }\n }\n };\n\n return /** @alias module:core/ajax */ {\n // Public variables and functions.\n /**\n * Make a series of ajax requests and return all the responses.\n *\n * @method call\n * @param {request[]} requests Array of requests with each containing methodname and args properties.\n * done and fail callbacks can be set for each element in the array, or the\n * can be attached to the promises returned by this function.\n * @param {Boolean} [async=true] If false this function will not return until the promises are resolved.\n * @param {Boolean} [loginrequired=true] When false this function calls an endpoint which does not use the\n * session.\n * Note: This may only be used with external functions which have been marked as\n * `'loginrequired' => false`\n * @param {Boolean} [nosessionupdate=false] If true, the timemodified for the session will not be updated.\n * @param {Number} [timeout] number of milliseconds to wait for a response. Defaults to no limit.\n * @param {Number} [cachekey] A cache key used to improve browser-side caching.\n * Typically the same `cachekey` is used for all function calls.\n * When the key changes, this causes the URL used to perform the fetch to change, which\n * prevents the existing browser cache from being used.\n * Note: This option is only availbale when `loginrequired` is `false`.\n * See {@link https://tracker.moodle.org/browser/MDL-65794} for more information.\n * @return {Promise[]} The Promises for each of the supplied requests.\n * The order of the Promise matches the order of requests exactly.\n *\n * @example An example of fetching a string using the cachekey parameter\n * import {call as fetchMany} from 'core/ajax';\n * import * as Notification from 'core/notification';\n *\n * export const performAction = (some, args) => {\n * Promises.all(fetchMany('core_get_string', {\n * stringid: 'do_not_copy',\n * component: 'core',\n * lang: 'en',\n * stringparams: [],\n * }, true, false, false, undefined, M.cfg.langrev))\n * .then(([doNotCopyString]) => {\n * window.console.log(doNotCopyString);\n * })\n * .catch(Notification.exception);\n * };\n *\n * @example A simple example that you might find in a repository function\n *\n * import {call as fetchMany} from 'core/ajax';\n *\n * export const fetchMessages = timeSince => fetchMany('core_message_get_messages', {timeSince}})[0];\n * export const fetchNotifications = timeSince => fetchMany('core_message_get_notifications', {timeSince}})[0];\n */\n call: function(requests, async, loginrequired, nosessionupdate, timeout, cachekey) {\n $(window).bind('beforeunload', function() {\n unloading = true;\n });\n var ajaxRequestData = [],\n i,\n promises = [],\n methodInfo = [],\n requestInfo = '';\n\n var maxUrlLength = 2000;\n\n if (typeof loginrequired === \"undefined\") {\n loginrequired = true;\n }\n if (typeof async === \"undefined\") {\n async = true;\n }\n if (typeof timeout === 'undefined') {\n timeout = 0;\n }\n if (typeof cachekey === 'undefined') {\n cachekey = null;\n } else {\n cachekey = parseInt(cachekey);\n if (cachekey <= 0) {\n cachekey = null;\n } else if (!cachekey) {\n cachekey = null;\n }\n }\n\n if (typeof nosessionupdate === \"undefined\") {\n nosessionupdate = false;\n }\n for (i = 0; i < requests.length; i++) {\n var request = requests[i];\n ajaxRequestData.push({\n index: i,\n methodname: request.methodname,\n args: request.args\n });\n request.nosessionupdate = nosessionupdate;\n request.deferred = $.Deferred();\n promises.push(request.deferred.promise());\n // Allow setting done and fail handlers as arguments.\n // This is just a shortcut for the calling code.\n if (typeof request.done !== \"undefined\") {\n request.deferred.done(request.done);\n }\n if (typeof request.fail !== \"undefined\") {\n request.deferred.fail(request.fail);\n }\n request.index = i;\n methodInfo.push(request.methodname);\n }\n\n if (methodInfo.length <= 5) {\n requestInfo = methodInfo.sort().join();\n } else {\n requestInfo = methodInfo.length + '-method-calls';\n }\n\n ajaxRequestData = JSON.stringify(ajaxRequestData);\n var settings = {\n type: 'POST',\n context: requests,\n dataType: 'json',\n processData: false,\n async: async,\n contentType: \"application/json\",\n timeout: timeout\n };\n\n var script = 'service.php';\n var url = config.wwwroot + '/lib/ajax/';\n if (!loginrequired) {\n script = 'service-nologin.php';\n url += script + '?info=' + requestInfo;\n if (cachekey) {\n url += '&cachekey=' + cachekey;\n settings.type = 'GET';\n }\n } else {\n url += script + '?sesskey=' + config.sesskey + '&info=' + requestInfo;\n }\n\n if (nosessionupdate) {\n url += '&nosessionupdate=true';\n }\n\n if (settings.type === 'POST') {\n settings.data = ajaxRequestData;\n } else {\n var urlUseGet = url + '&args=' + encodeURIComponent(ajaxRequestData);\n\n if (urlUseGet.length > maxUrlLength) {\n settings.type = 'POST';\n settings.data = ajaxRequestData;\n } else {\n url = urlUseGet;\n }\n }\n\n // Jquery deprecated done and fail with async=false so we need to do this 2 ways.\n if (async) {\n $.ajax(url, settings)\n .done(requestSuccess)\n .fail(requestFail);\n } else {\n settings.success = requestSuccess;\n settings.error = requestFail;\n $.ajax(url, settings);\n }\n\n return promises;\n }\n };\n});\n"],"file":"ajax.min.js"} \ No newline at end of file +{"version":3,"sources":["../src/ajax.js"],"names":["define","$","config","Log","URL","unloading","requestSuccess","responses","requests","exception","i","request","response","nosessionupdate","error","length","deferred","reject","resolve","data","Error","errorcode","window","location","relativeUrl","forEach","requestFail","jqXHR","textStatus","call","async","loginrequired","timeout","cachekey","bind","ajaxRequestData","promises","methodInfo","requestInfo","parseInt","push","index","methodname","args","Deferred","promise","done","fail","sort","join","JSON","stringify","settings","type","context","dataType","processData","contentType","script","url","wwwroot","sesskey","urlUseGet","encodeURIComponent","ajax","success"],"mappings":"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","sourcesContent":["// This file is part of Moodle - http://moodle.org/\n//\n// Moodle is free software: you can redistribute it and/or modify\n// it under the terms of the GNU General Public License as published by\n// the Free Software Foundation, either version 3 of the License, or\n// (at your option) any later version.\n//\n// Moodle is distributed in the hope that it will be useful,\n// but WITHOUT ANY WARRANTY; without even the implied warranty of\n// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n// GNU General Public License for more details.\n//\n// You should have received a copy of the GNU General Public License\n// along with Moodle. If not, see .\n\n/**\n * Standard Ajax wrapper for Moodle. It calls the central Ajax script,\n * which can call any existing webservice using the current session.\n * In addition, it can batch multiple requests and return multiple responses.\n *\n * @module core/ajax\n * @copyright 2015 Damyon Wiese \n * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later\n * @since 2.9\n */\ndefine(['jquery', 'core/config', 'core/log', 'core/url'], function($, config, Log, URL) {\n\n/**\n * A request to be performed.\n *\n * @typedef {object} request\n * @property {string} methodname The remote method to be called\n * @property {object} args The arguments to pass when fetching the remote content\n */\n\n // Keeps track of when the user leaves the page so we know not to show an error.\n var unloading = false;\n\n /**\n * Success handler. Called when the ajax call succeeds. Checks each response and\n * resolves or rejects the deferred from that request.\n *\n * @method requestSuccess\n * @private\n * @param {Object[]} responses Array of responses containing error, exception and data attributes.\n */\n var requestSuccess = function(responses) {\n // Call each of the success handlers.\n var requests = this,\n exception = null,\n i = 0,\n request,\n response,\n nosessionupdate;\n\n if (responses.error) {\n // There was an error with the request as a whole.\n // We need to reject each promise.\n // Unfortunately this may lead to duplicate dialogues, but each Promise must be rejected.\n for (; i < requests.length; i++) {\n request = requests[i];\n request.deferred.reject(responses);\n }\n\n return;\n }\n\n for (i = 0; i < requests.length; i++) {\n request = requests[i];\n\n response = responses[i];\n // We may not have responses for all the requests.\n if (typeof response !== \"undefined\") {\n if (response.error === false) {\n // Call the done handler if it was provided.\n request.deferred.resolve(response.data);\n } else {\n exception = response.exception;\n nosessionupdate = requests[i].nosessionupdate;\n break;\n }\n } else {\n // This is not an expected case.\n exception = new Error('missing response');\n break;\n }\n }\n // Something failed, reject the remaining promises.\n if (exception !== null) {\n // Redirect to the login page.\n if (exception.errorcode === \"servicerequireslogin\" && !nosessionupdate) {\n window.location = URL.relativeUrl(\"/login/index.php\");\n } else {\n requests.forEach(function(request) {\n request.deferred.reject(exception);\n });\n }\n }\n };\n\n /**\n * Fail handler. Called when the ajax call fails. Rejects all deferreds.\n *\n * @method requestFail\n * @private\n * @param {jqXHR} jqXHR The ajax object.\n * @param {string} textStatus The status string.\n * @param {Error|Object} exception The error thrown.\n */\n var requestFail = function(jqXHR, textStatus, exception) {\n // Reject all the promises.\n var requests = this;\n\n var i = 0;\n for (i = 0; i < requests.length; i++) {\n var request = requests[i];\n\n if (unloading) {\n // No need to trigger an error because we are already navigating.\n Log.error(\"Page unloaded.\");\n Log.error(exception);\n } else {\n request.deferred.reject(exception);\n }\n }\n };\n\n return /** @alias module:core/ajax */ {\n // Public variables and functions.\n /**\n * Make a series of ajax requests and return all the responses.\n *\n * @method call\n * @param {request[]} requests Array of requests with each containing methodname and args properties.\n * done and fail callbacks can be set for each element in the array, or the\n * can be attached to the promises returned by this function.\n * @param {Boolean} [async=true] If false this function will not return until the promises are resolved.\n * @param {Boolean} [loginrequired=true] When false this function calls an endpoint which does not use the\n * session.\n * Note: This may only be used with external functions which have been marked as\n * `'loginrequired' => false`\n * @param {Boolean} [nosessionupdate=false] If true, the timemodified for the session will not be updated.\n * @param {Number} [timeout] number of milliseconds to wait for a response. Defaults to no limit.\n * @param {Number} [cachekey] A cache key used to improve browser-side caching.\n * Typically the same `cachekey` is used for all function calls.\n * When the key changes, this causes the URL used to perform the fetch to change, which\n * prevents the existing browser cache from being used.\n * Note: This option is only availbale when `loginrequired` is `false`.\n * See {@link https://tracker.moodle.org/browser/MDL-65794} for more information.\n * @return {Promise[]} The Promises for each of the supplied requests.\n * The order of the Promise matches the order of requests exactly.\n *\n * @example A simple example that you might find in a repository module\n *\n * import {call as fetchMany} from 'core/ajax';\n *\n * export const fetchMessages = timeSince => fetchMany([{methodname: 'core_message_get_messages', args: {timeSince}}])[0];\n *\n * export const fetchNotifications = timeSince => fetchMany([{\n * methodname: 'core_message_get_notifications',\n * args: {\n * timeSince,\n * }\n * }])[0];\n *\n * export const fetchSomethingElse = (some, params, here) => fetchMany([{\n * methodname: 'core_get_something_else',\n * args: {\n * some,\n * params,\n * gohere: here,\n * },\n * }])[0];\n *\n * @example An example of fetching a string using the cachekey parameter\n * import {call as fetchMany} from 'core/ajax';\n * import * as Notification from 'core/notification';\n *\n * export const performAction = (some, args) => {\n * Promises.all(fetchMany([{methodname: 'core_get_string', args: {\n * stringid: 'do_not_copy',\n * component: 'core',\n * lang: 'en',\n * stringparams: [],\n * }}], true, false, false, undefined, M.cfg.langrev))\n * .then(([doNotCopyString]) => {\n * window.console.log(doNotCopyString);\n * })\n * .catch(Notification.exception);\n * };\n *\n */\n call: function(requests, async, loginrequired, nosessionupdate, timeout, cachekey) {\n $(window).bind('beforeunload', function() {\n unloading = true;\n });\n var ajaxRequestData = [],\n i,\n promises = [],\n methodInfo = [],\n requestInfo = '';\n\n var maxUrlLength = 2000;\n\n if (typeof loginrequired === \"undefined\") {\n loginrequired = true;\n }\n if (typeof async === \"undefined\") {\n async = true;\n }\n if (typeof timeout === 'undefined') {\n timeout = 0;\n }\n if (typeof cachekey === 'undefined') {\n cachekey = null;\n } else {\n cachekey = parseInt(cachekey);\n if (cachekey <= 0) {\n cachekey = null;\n } else if (!cachekey) {\n cachekey = null;\n }\n }\n\n if (typeof nosessionupdate === \"undefined\") {\n nosessionupdate = false;\n }\n for (i = 0; i < requests.length; i++) {\n var request = requests[i];\n ajaxRequestData.push({\n index: i,\n methodname: request.methodname,\n args: request.args\n });\n request.nosessionupdate = nosessionupdate;\n request.deferred = $.Deferred();\n promises.push(request.deferred.promise());\n // Allow setting done and fail handlers as arguments.\n // This is just a shortcut for the calling code.\n if (typeof request.done !== \"undefined\") {\n request.deferred.done(request.done);\n }\n if (typeof request.fail !== \"undefined\") {\n request.deferred.fail(request.fail);\n }\n request.index = i;\n methodInfo.push(request.methodname);\n }\n\n if (methodInfo.length <= 5) {\n requestInfo = methodInfo.sort().join();\n } else {\n requestInfo = methodInfo.length + '-method-calls';\n }\n\n ajaxRequestData = JSON.stringify(ajaxRequestData);\n var settings = {\n type: 'POST',\n context: requests,\n dataType: 'json',\n processData: false,\n async: async,\n contentType: \"application/json\",\n timeout: timeout\n };\n\n var script = 'service.php';\n var url = config.wwwroot + '/lib/ajax/';\n if (!loginrequired) {\n script = 'service-nologin.php';\n url += script + '?info=' + requestInfo;\n if (cachekey) {\n url += '&cachekey=' + cachekey;\n settings.type = 'GET';\n }\n } else {\n url += script + '?sesskey=' + config.sesskey + '&info=' + requestInfo;\n }\n\n if (nosessionupdate) {\n url += '&nosessionupdate=true';\n }\n\n if (settings.type === 'POST') {\n settings.data = ajaxRequestData;\n } else {\n var urlUseGet = url + '&args=' + encodeURIComponent(ajaxRequestData);\n\n if (urlUseGet.length > maxUrlLength) {\n settings.type = 'POST';\n settings.data = ajaxRequestData;\n } else {\n url = urlUseGet;\n }\n }\n\n // Jquery deprecated done and fail with async=false so we need to do this 2 ways.\n if (async) {\n $.ajax(url, settings)\n .done(requestSuccess)\n .fail(requestFail);\n } else {\n settings.success = requestSuccess;\n settings.error = requestFail;\n $.ajax(url, settings);\n }\n\n return promises;\n }\n };\n});\n"],"file":"ajax.min.js"} \ No newline at end of file diff --git a/lib/amd/src/ajax.js b/lib/amd/src/ajax.js index 761c686e188..9a32c1aea67 100644 --- a/lib/amd/src/ajax.js +++ b/lib/amd/src/ajax.js @@ -150,29 +150,45 @@ define(['jquery', 'core/config', 'core/log', 'core/url'], function($, config, Lo * @return {Promise[]} The Promises for each of the supplied requests. * The order of the Promise matches the order of requests exactly. * + * @example A simple example that you might find in a repository module + * + * import {call as fetchMany} from 'core/ajax'; + * + * export const fetchMessages = timeSince => fetchMany([{methodname: 'core_message_get_messages', args: {timeSince}}])[0]; + * + * export const fetchNotifications = timeSince => fetchMany([{ + * methodname: 'core_message_get_notifications', + * args: { + * timeSince, + * } + * }])[0]; + * + * export const fetchSomethingElse = (some, params, here) => fetchMany([{ + * methodname: 'core_get_something_else', + * args: { + * some, + * params, + * gohere: here, + * }, + * }])[0]; + * * @example An example of fetching a string using the cachekey parameter * import {call as fetchMany} from 'core/ajax'; * import * as Notification from 'core/notification'; * * export const performAction = (some, args) => { - * Promises.all(fetchMany('core_get_string', { + * Promises.all(fetchMany([{methodname: 'core_get_string', args: { * stringid: 'do_not_copy', * component: 'core', * lang: 'en', * stringparams: [], - * }, true, false, false, undefined, M.cfg.langrev)) + * }}], true, false, false, undefined, M.cfg.langrev)) * .then(([doNotCopyString]) => { * window.console.log(doNotCopyString); * }) * .catch(Notification.exception); * }; * - * @example A simple example that you might find in a repository function - * - * import {call as fetchMany} from 'core/ajax'; - * - * export const fetchMessages = timeSince => fetchMany('core_message_get_messages', {timeSince}})[0]; - * export const fetchNotifications = timeSince => fetchMany('core_message_get_notifications', {timeSince}})[0]; */ call: function(requests, async, loginrequired, nosessionupdate, timeout, cachekey) { $(window).bind('beforeunload', function() {