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/>.

/**

 * Encapsules the behavior for creating a tool type and tool proxy from a

 * registration url in Moodle.

 *

 * Manages the UI while operations are occuring, including rendering external

 * registration page within the iframe.

 *

 * See template: mod_lti/external_registration

 *

 * @module     mod_lti/external_registration

 * @copyright  2015 Ryan Wyllie <ryan@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 * @since      3.1

 */

define(['jquery', 'core/ajax', 'core/notification', 'core/templates', 'mod_lti/events',

        'mod_lti/tool_proxy', 'mod_lti/tool_type', 'mod_lti/keys', 'core/str'],

        function($, ajax, notification, templates, ltiEvents, toolProxy, toolType, KEYS, str) {

    var SELECTORS = {

        EXTERNAL_REGISTRATION_CONTAINER: '#external-registration-page-container',

        EXTERNAL_REGISTRATION_TEMPLATE_CONTAINER: '#external-registration-template-container',

        EXTERNAL_REGISTRATION_CANCEL_BUTTON: '#cancel-external-registration',

        TOOL_TYPE_CAPABILITIES_CONTAINER: '#tool-type-capabilities-container',

        TOOL_TYPE_CAPABILITIES_TEMPLATE_CONTAINER: '#tool-type-capabilities-template-container',

        CAPABILITIES_AGREE_CONTAINER: '.capabilities-container',

    };

    /**

     * Return the external registration cancel button element. This button is

     * the cancel button that appears while the iframe is rendered.

     *

     * @method getExternalRegistrationCancelButton

     * @private

     * @return {JQuery} jQuery object

     */

    var getExternalRegistrationCancelButton = function() {

        return $(SELECTORS.EXTERNAL_REGISTRATION_CANCEL_BUTTON);

    };

    /**

     * Return the container that holds all elements for the external registration, including

     * the cancel button and the iframe.

     *

     * @method getExternalRegistrationContainer

     * @private

     * @return {JQuery} jQuery object

     */

    var getExternalRegistrationContainer = function() {

        return $(SELECTORS.EXTERNAL_REGISTRATION_CONTAINER);

    };

    /**

     * Return the container that holds the external registration page template. It should

     * be the iframe.

     *

     * @method getExternalRegistrationTemplateContainer

     * @private

     * @return {JQuery} jQuery object

     */

    var getExternalRegistrationTemplateContainer = function() {

        return $(SELECTORS.EXTERNAL_REGISTRATION_TEMPLATE_CONTAINER);

    };

    /**

     * Return the container that holds the elements for displaying the list of capabilities

     * that this tool type requires. This container wraps the loading indicator and the template

     * container.

     *

     * @method getToolTypeCapabilitiesContainer

     * @private

     * @return {JQuery} jQuery object

     */

    var getToolTypeCapabilitiesContainer = function() {

        return $(SELECTORS.TOOL_TYPE_CAPABILITIES_CONTAINER);

    };

    /**

     * Return the container that holds the template that lists the capabilities that the

     * tool type will require.

     *

     * @method getToolTypeCapabilitiesTemplateContainer

     * @private

     * @return {JQuery} jQuery object

     */

    var getToolTypeCapabilitiesTemplateContainer = function() {

        return $(SELECTORS.TOOL_TYPE_CAPABILITIES_TEMPLATE_CONTAINER);

    };

    /**

     * Triggers a visual indicator to show that the capabilities section is loading.

     *

     * @method startLoadingCapabilitiesContainer

     * @private

     */

    var startLoadingCapabilitiesContainer = function() {

        getToolTypeCapabilitiesContainer().addClass('loading');

    };

    /**

     * Removes the visual indicator that shows the capabilities section is loading.

     *

     * @method stopLoadingCapabilitiesContainer

     * @private

     */

    var stopLoadingCapabilitiesContainer = function() {

        getToolTypeCapabilitiesContainer().removeClass('loading');

    };

    /**

     * Adds a visual indicator that shows the cancel button is loading.

     *

     * @method startLoadingCancel

     * @private

     */

    var startLoadingCancel = function() {

        getExternalRegistrationCancelButton().addClass('loading');

    };

    /**

     * Adds a visual indicator that shows the cancel button is loading.

     *

     * @method startLoadingCancel

     * @private

     */

    var stopLoadingCancel = function() {

        getExternalRegistrationCancelButton().removeClass('loading');

    };

    /**

     * Stops displaying the tool type capabilities container.

     *

     * @method hideToolTypeCapabilitiesContainer

     * @private

     */

    var hideToolTypeCapabilitiesContainer = function() {

        getToolTypeCapabilitiesContainer().addClass('hidden');

    };

    /**

     * Displays the tool type capabilities container.

     *

     * @method showToolTypeCapabilitiesContainer

     * @private

     */

    var showToolTypeCapabilitiesContainer = function() {

        getToolTypeCapabilitiesContainer().removeClass('hidden');

    };

    /**

     * Stops displaying the external registration content.

     *

     * @method hideExternalRegistrationContent

     * @private

     */

    var hideExternalRegistrationContent = function() {

        getExternalRegistrationContainer().addClass('hidden');

    };

    /**

     * Displays the external registration content.

     *

     * @method showExternalRegistrationContent

     * @private

     */

    var showExternalRegistrationContent = function() {

        getExternalRegistrationContainer().removeClass('hidden');

    };

    /**

     * Save the given tool proxy id on the DOM.

     *

     * @method setToolProxyId

     * @private

     * @param {Integer} id Tool proxy ID

     */

    var setToolProxyId = function(id) {

        var button = getExternalRegistrationCancelButton();

        button.attr('data-tool-proxy-id', id);

    };

    /**

     * Return the saved tool proxy id.

     *

     * @method getToolProxyId

     * @private

     * @return {String} Tool proxy ID

     */

    var getToolProxyId = function() {

        var button = getExternalRegistrationCancelButton();

        return button.attr('data-tool-proxy-id');

    };

    /**

     * Remove the saved tool proxy id.

     *

     * @method clearToolProxyId

     * @private

     */

    var clearToolProxyId = function() {

        var button = getExternalRegistrationCancelButton();

        button.removeAttr('data-tool-proxy-id');

    };

    /**

     * Returns true if a tool proxy id has been recorded.

     *

     * @method hasToolProxyId

     * @private

     * @return {Boolean}

     */

    var hasToolProxyId = function() {

        return getToolProxyId() ? true : false;

    };

    /**

     * Checks if this process has created a tool proxy within

     * Moodle yet.

     *

     * @method hasCreatedToolProxy

     * @private

     * @return {Boolean}

     */

    var hasCreatedToolProxy = function() {

        var button = getExternalRegistrationCancelButton();

        return button.attr('data-tool-proxy-new') && hasToolProxyId();

    };

    /**

     * Records that this process has created a tool proxy.

     *

     * @method setProxyAsNew

     * @private

     * @return {Boolean}

     */

    var setProxyAsNew = function() {

        var button = getExternalRegistrationCancelButton();

        return button.attr('data-tool-proxy-new', "new");

    };

    /**

     * Records that this process has not created a tool proxy.

     *

     * @method setProxyAsOld

     * @private

     * @return {Boolean}

     */

    var setProxyAsOld = function() {

        var button = getExternalRegistrationCancelButton();

        return button.removeAttr('data-tool-proxy-new');

    };

    /**

     * Gets the external registration request required to be sent to the external

     * registration page using a form.

     *

     * See mod_lti/tool_proxy_registration_form template.

     *

     * @method getRegistrationRequest

     * @private

     * @param {Integer} id Tool Proxy ID

     * @return {Promise} jQuery Deferred object

     */

    var getRegistrationRequest = function(id) {

        var request = {

            methodname: 'mod_lti_get_tool_proxy_registration_request',

            args: {

                id: id

            }

        };

        return ajax.call([request])[0];

    };

    /**

     * Cancel an in progress external registration. This will perform any necessary

     * clean up of tool proxies and return the page section back to the home section.

     *

     * @method cancelRegistration

     * @private

     * @return {Promise} jQuery Deferred object

     */

    var cancelRegistration = function() {

        startLoadingCancel();

        var promise = $.Deferred();

        // If we've created a proxy as part of this process then

        // we need to delete it to clean up the data in the back end.

        if (hasCreatedToolProxy()) {

            var id = getToolProxyId();

            toolProxy.delete(id).done(function() {

                promise.resolve();

            }).fail(function(failure) {

                promise.reject(failure);

            });

        } else {

            promise.resolve();

        }

        promise.done(function() {

            // Return to the original page.

            finishExternalRegistration();

            stopLoadingCancel();

        }).fail(function(failure) {

            notification.exception(failure);

            finishExternalRegistration();

            stopLoadingCancel();

            str.get_string('failedtodeletetoolproxy', 'mod_lti').done(function(s) {

                var feedback = {

                    message: s,

                    error: true

                };

                $(document).trigger(ltiEvents.REGISTRATION_FEEDBACK, feedback);

            }).fail(notification.exception);

        });

        return promise;

    };

    /**

     * Load the external registration template and render it in the DOM and display it.

     *

     * @method renderExternalRegistrationWindow

     * @private

     * @param {Object} registrationRequest

     * @return {Promise} jQuery Deferred object

     */

    var renderExternalRegistrationWindow = function(registrationRequest) {

        var promise = templates.render('mod_lti/tool_proxy_registration_form', registrationRequest);

        promise.done(function(html, js) {

            // Show the external registration page in an iframe.

            var container = getExternalRegistrationTemplateContainer();

            container.append(html);

            templates.runTemplateJS(js);

            container.find('form').submit();

            showExternalRegistrationContent();

        }).fail(notification.exception);

        return promise;

    };

    /**

     * Send a request to Moodle server to set the state of the tool type to configured (active).

     *

     * @method setTypeStatusActive

     * @private

     * @param {Object} typeData A set of data representing a type, as returned by a request to get a type

     *               from the Moodle server.

     * @return {Promise} jQuery Deferred object

     */

    var setTypeStatusActive = function(typeData) {

        return toolType.update({

            id: typeData.id,

            state: toolType.constants.state.configured

        });

    };

    /**

     * Render and display an agreement page for the user to acknowledge the list of capabilities

     * (groups of data) that the external tool requires in order to work. If the user agrees then

     * we will activate the tool so that it is immediately available. If they don't agree then

     * the tool remains in a pending state within Moodle until agreement is given.

     *

     * @method promptForToolTypeCapabilitiesAgreement

     * @private

     * @param {Object} typeData A set of data representing a type, as returned by a request to get a type

     *               from the Moodle server.

     * @return {Promise} jQuery Deferred object

     */

    var promptForToolTypeCapabilitiesAgreement = function(typeData) {

        var promise = $.Deferred();

        templates.render('mod_lti/tool_type_capabilities_agree', typeData).done(function(html, js) {

            var container = getToolTypeCapabilitiesTemplateContainer();

            hideExternalRegistrationContent();

            showToolTypeCapabilitiesContainer();

            templates.replaceNodeContents(container, html, js);

            var choiceContainer = container.find(SELECTORS.CAPABILITIES_AGREE_CONTAINER);

            // The user agrees to allow the tool to use the groups of data so we can go

            // ahead and activate it for them so that it can be used straight away.

            choiceContainer.on(ltiEvents.CAPABILITIES_AGREE, function() {

                startLoadingCapabilitiesContainer();

                setTypeStatusActive(typeData).always(function() {

                    stopLoadingCapabilitiesContainer();

                    container.empty();

                    promise.resolve();

                });

            });

            // The user declines to let the tool use the data. In this case we leave

            // the tool as pending and they can delete it using the main screen if they

            // wish.

            choiceContainer.on(ltiEvents.CAPABILITIES_DECLINE, function() {

                container.empty();

                promise.resolve();

            });

        }).fail(promise.reject);

        promise.done(function() {

            hideToolTypeCapabilitiesContainer();

        }).fail(notification.exception);

        return promise;

    };

    /**

     * Send a request to the Moodle server to create a tool proxy using the registration URL the user

     * has provided. The proxy is required for the external registration page to work correctly.

     *

     * After the proxy is created the external registration page is rendered within an iframe for the user

     * to complete the registration in the external page.

     *

     * If the tool proxy creation fails then we redirect the page section back to the home section and

     * display the error, rather than rendering the external registration page.

     *

     * @method createAndRegisterToolProxy

     * @private

     * @param {String} url Tool registration URL to register

     * @return {Promise} jQuery Deferred object

     */

    var createAndRegisterToolProxy = function(url) {

        var promise = $.Deferred();

        if (!url || url === "") {

            // No URL has been input so do nothing.

            promise.resolve();

        } else {

            // A tool proxy needs to exist before the external page is rendered because

            // the external page sends requests back to Moodle for information that is stored

            // in the proxy.

            toolProxy.create({regurl: url})

                .done(function(result) {

                        // Note that it's a new proxy so we will always clean it up.

                        setProxyAsNew();

                        promise = registerProxy(result.id);

                    })

                .fail(function(exception) {

                        // Clean up.

                        cancelRegistration();

                        // Let the user know what the error is.

                        var feedback = {

                            message: exception.message,

                            error: true

                        };

                        $(document).trigger(ltiEvents.REGISTRATION_FEEDBACK, feedback);

                        promise.reject(exception);

                    });

        }

        return promise;

    };

    /**

     * Loads the window to register a proxy, given an ID.

     *

     * @method registerProxy

     * @private

     * @param {Integer} id Proxy id to register

     * @return {Promise} jQuery Deferred object to fail or resolve

     */

    var registerProxy = function(id) {

        var promise = $.Deferred();

        // Save the id on the DOM to cleanup later.

        setToolProxyId(id);

        // There is a specific set of data needed to send to the external registration page

        // in a form, so let's get it from our server.

        getRegistrationRequest(id)

            .done(function(registrationRequest) {

                    renderExternalRegistrationWindow(registrationRequest)

                        .done(function() {

                                promise.resolve();

                            })

                        .fail(promise.fail);

                })

            .fail(promise.fail);

        return promise;

    };

    /**

     * Complete the registration process, clean up any left over data and

     * trigger the appropriate events.

     *

     * @method finishExternalRegistration

     * @private

     */

    var finishExternalRegistration = function() {

        if (hasToolProxyId()) {

            clearToolProxyId();

        }

        setProxyAsOld(false);

        hideExternalRegistrationContent();

        var container = getExternalRegistrationTemplateContainer();

        container.empty();

        $(document).trigger(ltiEvents.STOP_EXTERNAL_REGISTRATION);

    };

    /**

     * Sets up the listeners for user interaction on the page.

     *

     * @method registerEventListeners

     * @private

     */

    var registerEventListeners = function() {

        $(document).on(ltiEvents.START_EXTERNAL_REGISTRATION, function(event, data) {

                if (!data) {

                    return;

                }

                if (data.url) {

                    createAndRegisterToolProxy(data.url);

                }

                if (data.proxyid) {

                    registerProxy(data.proxyid);

                }

            });

        var cancelExternalRegistrationButton = getExternalRegistrationCancelButton();

        cancelExternalRegistrationButton.click(function(e) {

            e.preventDefault();

            cancelRegistration();

        });

        cancelExternalRegistrationButton.keypress(function(e) {

            if (!e.metaKey && !e.shiftKey && !e.altKey && !e.ctrlKey) {

                if (e.keyCode == KEYS.ENTER || e.keyCode == KEYS.SPACE) {

                    e.preventDefault();

                    cancelRegistration();

                }

            }

        });

        // This is gross but necessary due to isolated jQuery scopes between

        // child iframe and parent windows. There is no other way to communicate.

        //

        // This function gets called by the moodle page that received the redirect

        // from the external registration page and handles the external page's returned

        // parameters.

        //

        // See AMD module mod_lti/external_registration_return.

        window.triggerExternalRegistrationComplete = function(data) {

            var promise = $.Deferred();

            var feedback = {

                message: "",

                error: false

            };

            if (data.status == "success") {

                str.get_string('successfullycreatedtooltype', 'mod_lti').done(function(s) {

                    feedback.message = s;

                }).fail(notification.exception);

                // Trigger appropriate events when we've completed the necessary requests.

                promise.done(function() {

                    finishExternalRegistration();

                    $(document).trigger(ltiEvents.REGISTRATION_FEEDBACK, feedback);

                    $(document).trigger(ltiEvents.NEW_TOOL_TYPE);

                }).fail(notification.exception);

                // We should have created a tool proxy by this point.

                if (hasCreatedToolProxy()) {

                    var proxyId = getToolProxyId();

                    // We need the list of types that are linked to this proxy. We're assuming it'll

                    // only be one because this process creates a one-to-one type->proxy.

                    toolType.getFromToolProxyId(proxyId).done(function(types) {

                        if (types && types.length) {

                            // There should only be one result.

                            var typeData = types[0];

                            // Check if the external tool required access to any Moodle data (users, courses etc).

                            if (typeData.hascapabilitygroups) {

                                // If it did then we ask the user to agree to those groups before the type is

                                // activated (i.e. can be used in Moodle).

                                promptForToolTypeCapabilitiesAgreement(typeData).always(function() {

                                    promise.resolve();

                                });

                            } else {

                                promise.resolve();

                            }

                        } else {

                            promise.resolve();

                        }

                    }).fail(function() {

                        promise.resolve();

                    });

                }

            } else {

                // Anything other than success is failure.

                feedback.message = data.error;

                feedback.error = true;

                // Cancel registration to clean up any proxies and tools that were

                // created.

                promise.done(function() {

                    cancelRegistration().always(function() {

                        $(document).trigger(ltiEvents.REGISTRATION_FEEDBACK, feedback);

                    });

                }).fail(notification.exception);

                promise.resolve();

            }

            return promise;

        };

    };

    return {

        /**

         * Initialise this module.

         */

        init: function() {

            registerEventListeners();

        }

    };

});