// 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();
}
};
});