Proyectos de Subversion Moodle

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Standard Ajax wrapper for Moodle. It calls the central Ajax script,
 * which can call any existing webservice using the current session.
 * In addition, it can batch multiple requests and return multiple responses.
 *
 * @module     core/ajax
 * @copyright  2015 Damyon Wiese <damyon@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      2.9
 */
define(['jquery', 'core/config', 'core/log', 'core/url'], function($, config, Log, URL) {

/**
 * A request to be performed.
 *
 * @typedef {object} request
 * @property {string} methodname The remote method to be called
 * @property {object} args The arguments to pass when fetching the remote content
 */

    // Keeps track of when the user leaves the page so we know not to show an error.
    var unloading = false;

    /**
     * Success handler. Called when the ajax call succeeds. Checks each response and
     * resolves or rejects the deferred from that request.
     *
     * @method requestSuccess
     * @private
     * @param {Object[]} responses Array of responses containing error, exception and data attributes.
     */
    var requestSuccess = function(responses) {
        // Call each of the success handlers.
        var requests = this,
            exception = null,
            i = 0,
            request,
            response,
            nosessionupdate;

        if (responses.error) {
            // There was an error with the request as a whole.
            // We need to reject each promise.
            // Unfortunately this may lead to duplicate dialogues, but each Promise must be rejected.
            for (; i < requests.length; i++) {
                request = requests[i];
                request.deferred.reject(responses);
            }

            return;
        }

        for (i = 0; i < requests.length; i++) {
            request = requests[i];

            response = responses[i];
            // We may not have responses for all the requests.
            if (typeof response !== "undefined") {
                if (response.error === false) {
                    // Call the done handler if it was provided.
                    request.deferred.resolve(response.data);
                } else {
                    exception = response.exception;
                    nosessionupdate = requests[i].nosessionupdate;
                    break;
                }
            } else {
                // This is not an expected case.
                exception = new Error('missing response');
                break;
            }
        }
        // Something failed, reject the remaining promises.
        if (exception !== null) {
            // Redirect to the login page.
            if (exception.errorcode === "servicerequireslogin" && !nosessionupdate) {
                window.location = URL.relativeUrl("/login/index.php");
            } else {
                requests.forEach(function(request) {
                    request.deferred.reject(exception);
                });
            }
        }
    };

    /**
     * Fail handler. Called when the ajax call fails. Rejects all deferreds.
     *
     * @method requestFail
     * @private
     * @param {jqXHR} jqXHR The ajax object.
     * @param {string} textStatus The status string.
     * @param {Error|Object} exception The error thrown.
     */
    var requestFail = function(jqXHR, textStatus, exception) {
        // Reject all the promises.
        var requests = this;

        var i = 0;
        for (i = 0; i < requests.length; i++) {
            var request = requests[i];

            if (unloading) {
                // No need to trigger an error because we are already navigating.
                Log.error("Page unloaded.");
                Log.error(exception);
            } else {
                request.deferred.reject(exception);
            }
        }
    };

    return /** @alias module:core/ajax */ {
        // Public variables and functions.
        /**
         * Make a series of ajax requests and return all the responses.
         *
         * @method call
         * @param {request[]} requests Array of requests with each containing methodname and args properties.
         *                   done and fail callbacks can be set for each element in the array, or the
         *                   can be attached to the promises returned by this function.
         * @param {Boolean} [async=true] If false this function will not return until the promises are resolved.
         * @param {Boolean} [loginrequired=true] When false this function calls an endpoint which does not use the
         *                  session.
         *                  Note: This may only be used with external functions which have been marked as
         *                  `'loginrequired' => false`
         * @param {Boolean} [nosessionupdate=false] If true, the timemodified for the session will not be updated.
         * @param {Number}  [timeout] number of milliseconds to wait for a response. Defaults to no limit.
         * @param {Number}  [cachekey] A cache key used to improve browser-side caching.
         *                  Typically the same `cachekey` is used for all function calls.
         *                  When the key changes, this causes the URL used to perform the fetch to change, which
         *                  prevents the existing browser cache from being used.
         *                  Note: This option is only availbale when `loginrequired` is `false`.
         *                  See {@link https://tracker.moodle.org/browser/MDL-65794} for more information.
         * @return {Promise[]} The Promises for each of the supplied requests.
         *                  The order of the Promise matches the order of requests exactly.
         *
         * @example <caption>A simple example that you might find in a repository module</caption>
         *
         * 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 <caption>An example of fetching a string using the cachekey parameter</caption>
         * import {call as fetchMany} from 'core/ajax';
         * import * as Notification from 'core/notification';
         *
         * export const performAction = (some, args) => {
         *     Promises.all(fetchMany([{methodname: 'core_get_string', args: {
         *         stringid: 'do_not_copy',
         *         component: 'core',
         *         lang: 'en',
         *         stringparams: [],
         *     }}], true, false, false, undefined, M.cfg.langrev))
         *     .then(([doNotCopyString]) => {
         *         window.console.log(doNotCopyString);
         *     })
         *     .catch(Notification.exception);
         * };
         *
         */
        call: function(requests, async, loginrequired, nosessionupdate, timeout, cachekey) {
            $(window).bind('beforeunload', function() {
                unloading = true;
            });
            var ajaxRequestData = [],
                i,
                promises = [],
                methodInfo = [],
                requestInfo = '';

            var maxUrlLength = 2000;

            if (typeof loginrequired === "undefined") {
                loginrequired = true;
            }
            if (typeof async === "undefined") {
                async = true;
            }
            if (typeof timeout === 'undefined') {
                timeout = 0;
            }
            if (typeof cachekey === 'undefined') {
                cachekey = null;
            } else {
                cachekey = parseInt(cachekey);
                if (cachekey <= 0) {
                    cachekey = null;
                } else if (!cachekey) {
                    cachekey = null;
                }
            }

            if (typeof nosessionupdate === "undefined") {
                nosessionupdate = false;
            }
            for (i = 0; i < requests.length; i++) {
                var request = requests[i];
                ajaxRequestData.push({
                    index: i,
                    methodname: request.methodname,
                    args: request.args
                });
                request.nosessionupdate = nosessionupdate;
                request.deferred = $.Deferred();
                promises.push(request.deferred.promise());
                // Allow setting done and fail handlers as arguments.
                // This is just a shortcut for the calling code.
                if (typeof request.done !== "undefined") {
                    request.deferred.done(request.done);
                }
                if (typeof request.fail !== "undefined") {
                    request.deferred.fail(request.fail);
                }
                request.index = i;
                methodInfo.push(request.methodname);
            }

            if (methodInfo.length <= 5) {
                requestInfo = methodInfo.sort().join();
            } else {
                requestInfo = methodInfo.length + '-method-calls';
            }

            ajaxRequestData = JSON.stringify(ajaxRequestData);
            var settings = {
                type: 'POST',
                context: requests,
                dataType: 'json',
                processData: false,
                async: async,
                contentType: "application/json",
                timeout: timeout
            };

            var script = 'service.php';
            var url = config.wwwroot + '/lib/ajax/';
            if (!loginrequired) {
                script = 'service-nologin.php';
                url += script + '?info=' + requestInfo;
                if (cachekey) {
                    url += '&cachekey=' + cachekey;
                    settings.type = 'GET';
                }
            } else {
                url += script + '?sesskey=' + config.sesskey + '&info=' + requestInfo;
            }

            if (nosessionupdate) {
                url += '&nosessionupdate=true';
            }

            if (settings.type === 'POST') {
                settings.data = ajaxRequestData;
            } else {
                var urlUseGet = url + '&args=' + encodeURIComponent(ajaxRequestData);

                if (urlUseGet.length > maxUrlLength) {
                    settings.type = 'POST';
                    settings.data = ajaxRequestData;
                } else {
                    url = urlUseGet;
                }
            }

            // Jquery deprecated done and fail with async=false so we need to do this 2 ways.
            if (async) {
                $.ajax(url, settings)
                    .done(requestSuccess)
                    .fail(requestFail);
            } else {
                settings.success = requestSuccess;
                settings.error = requestFail;
                $.ajax(url, settings);
            }

            return promises;
        }
    };
});