// 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/>.
/**
* Javascript for showing/hiding pages of content.
*
* @module core/paged_content_pages
* @copyright 2018 Ryan Wyllie <ryan@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
define(
[
'jquery',
'core/templates',
'core/notification',
'core/pubsub',
'core/paged_content_events',
'core/pending',
],
function(
$,
Templates,
Notification,
PubSub,
PagedContentEvents,
Pending
) {
var SELECTORS = {
ROOT: '[data-region="page-container"]',
PAGE_REGION: '[data-region="paged-content-page"]',
ACTIVE_PAGE_REGION: '[data-region="paged-content-page"].active'
};
var TEMPLATES = {
PAGING_CONTENT_ITEM: 'core/paged_content_page',
LOADING: 'core/overlay_loading'
};
var PRELOADING_GRACE_PERIOD = 300;
/**
* Find a page by the number.
*
* @param {object} root The root element.
* @param {Number} pageNumber The number of the page to be found.
* @returns {jQuery} The page.
*/
var findPage = function(root, pageNumber) {
return root.find('[data-page="' + pageNumber + '"]');
};
/**
* Show the loading spinner until the returned deferred is resolved by the
* calling code.
*
* The loading spinner is only rendered after a short grace period to avoid
* having it flash up briefly in the interface.
*
* @param {object} root The root element.
* @returns {promise} The page.
*/
var startLoading = function(root) {
var deferred = $.Deferred();
root.attr('aria-busy', true);
var pendingPromise = new Pending('core/paged_content_pages:startLoading');
Templates.render(TEMPLATES.LOADING, {visible: true})
.then(function(html) {
var loadingSpinner = $(html);
// Put this in a timer to give the calling code 300 milliseconds
// to render the content before we show the loading spinner. This
// helps prevent a loading icon flicker on close to instant
// rendering.
var timerId = setTimeout(function() {
root.css('position', 'relative');
loadingSpinner.appendTo(root);
}, PRELOADING_GRACE_PERIOD);
deferred.always(function() {
clearTimeout(timerId);
// Remove the loading spinner when our deferred is resolved
// by the calling code.
loadingSpinner.remove();
root.css('position', '');
root.removeAttr('aria-busy');
pendingPromise.resolve();
return;
});
return;
})
.fail(Notification.exception);
return deferred;
};
/**
* Render the result of the page promise in a paged content page.
*
* This function returns a promise that is resolved with the new paged content
* page.
*
* @param {object} root The root element.
* @param {promise} pagePromise The promise resolved with HTML and JS to render in the page.
* @param {Number} pageNumber The page number.
* @returns {promise} The page.
*/
var renderPagePromise = function(root, pagePromise, pageNumber) {
var deferred = $.Deferred();
pagePromise.then(function(html, pageJS) {
pageJS = pageJS || '';
// When we get the contents to be rendered we can pass it in as the
// content for a new page.
Templates.render(TEMPLATES.PAGING_CONTENT_ITEM, {
page: pageNumber,
content: html
})
.then(function(html) {
// Make sure the JS we got from the page promise is being added
// to the page when we render the page.
Templates.appendNodeContents(root, html, pageJS);
var page = findPage(root, pageNumber);
deferred.resolve(page);
return;
})
.fail(function(exception) {
deferred.reject(exception);
})
.fail(Notification.exception);
return;
})
.fail(function(exception) {
deferred.reject(exception);
return;
})
.fail(Notification.exception);
return deferred.promise();
};
/**
* Make one or more pages visible based on the SHOW_PAGES event. The show
* pages event provides data containing which pages should be shown as well
* as the limit and offset values for loading the items for each of those pages.
*
* The renderPagesContentCallback is provided this list of data to know which
* pages to load. E.g. the data to load 2 pages might look like:
* [
* {
* pageNumber: 1,
* limit: 5,
* offset: 0
* },
* {
* pageNumber: 2,
* limit: 5,
* offset: 5
* }
* ]
*
* The renderPagesContentCallback should return an array of promises, one for
* each page in the pages data, that is resolved with the HTML and JS for that page.
*
* If the renderPagesContentCallback is not provided then it is assumed that
* all pages have been rendered prior to initialising this module.
*
* This function triggers the PAGES_SHOWN event after the pages have been rendered.
*
* @param {object} root The root element.
* @param {Number} pagesData The data for which pages need to be visible.
* @param {string} id A unique id for this instance.
* @param {function} renderPagesContentCallback Render pages content.
*/
var showPages = function(root, pagesData, id, renderPagesContentCallback) {
var pendingPromise = new Pending('core/paged_content_pages:showPages');
var existingPages = [];
var newPageData = [];
var newPagesPromise = $.Deferred();
var shownewpage = true;
// Check which of the pages being requests have previously been rendered
// so that we only ask for new pages to be rendered by the callback.
pagesData.forEach(function(pageData) {
var pageNumber = pageData.pageNumber;
var existingPage = findPage(root, pageNumber);
if (existingPage.length) {
existingPages.push(existingPage);
} else {
newPageData.push(pageData);
}
});
if (newPageData.length && typeof renderPagesContentCallback === 'function') {
// If we have pages we haven't previously seen then ask the client code
// to render them for us by calling the callback.
var promises = renderPagesContentCallback(newPageData, {
allItemsLoaded: function(lastPageNumber) {
PubSub.publish(id + PagedContentEvents.ALL_ITEMS_LOADED, lastPageNumber);
}
});
// After the client has finished rendering each of the pages being asked
// for then begin our rendering process to put that content into paged
// content pages.
var renderPagePromises = promises.map(function(promise, index) {
// Create our promise for when our rendering will be completed.
return renderPagePromise(root, promise, newPageData[index].pageNumber);
});
// After each of our rendering promises have been completed then we can
// give all of the new pages to the next bit of code for handling.
$.when.apply($, renderPagePromises)
.then(function() {
var newPages = Array.prototype.slice.call(arguments);
// Resolve the promise with the list of newly rendered pages.
newPagesPromise.resolve(newPages);
return;
})
.fail(function(exception) {
newPagesPromise.reject(exception);
return;
})
.fail(Notification.exception);
} else {
// If there aren't any pages to load then immediately resolve the promise.
newPagesPromise.resolve([]);
}
var loadingPromise = startLoading(root);
newPagesPromise.then(function(newPages) {
// Once all of the new pages have been created then add them to any
// existing pages we have.
var pagesToShow = existingPages.concat(newPages);
// Hide all existing pages.
root.find(SELECTORS.PAGE_REGION).addClass('hidden');
// Show each of the pages that were requested.;
pagesToShow.forEach(function(page) {
if (shownewpage) {
page.removeClass('hidden');
}
});
return;
})
.then(function() {
// Let everything else know we've displayed the pages.
PubSub.publish(id + PagedContentEvents.PAGES_SHOWN, pagesData);
return;
})
.fail(Notification.exception)
.always(function() {
loadingPromise.resolve();
pendingPromise.resolve();
})
.catch();
};
/**
* Initialise the module to listen for SHOW_PAGES events and render the
* appropriate pages using the provided renderPagesContentCallback function.
*
* The renderPagesContentCallback is provided a list of data to know which
* pages to load.
* E.g. the data to load 2 pages might look like:
* [
* {
* pageNumber: 1,
* limit: 5,
* offset: 0
* },
* {
* pageNumber: 2,
* limit: 5,
* offset: 5
* }
* ]
*
* The renderPagesContentCallback should return an array of promises, one for
* each page in the pages data, that is resolved with the HTML and JS for that page.
*
* If the renderPagesContentCallback is not provided then it is assumed that
* all pages have been rendered prior to initialising this module.
*
* The event element is the element to listen for the paged content events on.
*
* @param {object} root The root element.
* @param {string} id A unique id for this instance.
* @param {function} renderPagesContentCallback Render pages content.
*/
var init = function(root, id, renderPagesContentCallback) {
root = $(root);
PubSub.subscribe(id + PagedContentEvents.SHOW_PAGES, function(pagesData) {
showPages(root, pagesData, id, renderPagesContentCallback);
});
PubSub.subscribe(id + PagedContentEvents.SET_ITEMS_PER_PAGE_LIMIT, function() {
// If the items per page limit was changed then we need to clear our content
// the load new values based on the new limit.
root.empty();
});
};
return {
init: init,
rootSelector: SELECTORS.ROOT,
};
});