// 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/>.
/**
* Factory to create a paged content widget.
*
* @module core/paged_content_factory
* @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/paged_content',
'core/paged_content_events',
'core/pubsub',
'core_user/repository'
],
function(
$,
Templates,
Notification,
PagedContent,
PagedContentEvents,
PubSub,
UserRepository
) {
var TEMPLATES = {
PAGED_CONTENT: 'core/paged_content'
};
var DEFAULT = {
ITEMS_PER_PAGE_SINGLE: 25,
ITEMS_PER_PAGE_ARRAY: [25, 50, 100, 0],
MAX_PAGES: 3
};
/**
* Get the default context to render the paged content mustache
* template.
*
* @return {object}
*/
var getDefaultTemplateContext = function() {
return {
pagingbar: false,
pagingdropdown: false,
skipjs: true,
ignorecontrolwhileloading: true,
controlplacementbottom: false
};
};
/**
* Get the default context to render the paging bar mustache template.
*
* @return {object}
*/
var getDefaultPagingBarTemplateContext = function() {
return {
showitemsperpageselector: false,
itemsperpage: [{value: 35, active: true}],
previous: true,
next: true,
activepagenumber: 1,
hidecontrolonsinglepage: true,
pages: []
};
};
/**
* Calculate the number of pages required for the given number of items and
* how many of each item should appear on a page.
*
* @param {Number} numberOfItems How many items in total.
* @param {Number} itemsPerPage How many items will be shown per page.
* @return {Number} The number of pages required.
*/
var calculateNumberOfPages = function(numberOfItems, itemsPerPage) {
var numberOfPages = 1;
if (numberOfItems > 0) {
var partial = numberOfItems % itemsPerPage;
if (partial) {
numberOfItems -= partial;
numberOfPages = (numberOfItems / itemsPerPage) + 1;
} else {
numberOfPages = numberOfItems / itemsPerPage;
}
}
return numberOfPages;
};
/**
* Build the context for the paging bar template when we have a known number
* of items.
*
* @param {Number} numberOfItems How many items in total.
* @param {Number} itemsPerPage How many items will be shown per page.
* @return {object} Mustache template
*/
var buildPagingBarTemplateContextKnownLength = function(numberOfItems, itemsPerPage) {
if (itemsPerPage === null) {
itemsPerPage = DEFAULT.ITEMS_PER_PAGE_SINGLE;
}
if ($.isArray(itemsPerPage)) {
// If we're given a total number of pages then we don't support a variable
// set of items per page so just use the first one.
itemsPerPage = itemsPerPage[0];
}
var context = getDefaultPagingBarTemplateContext();
context.itemsperpage = buildItemsPerPagePagingBarContext(itemsPerPage);
var numberOfPages = calculateNumberOfPages(numberOfItems, itemsPerPage);
for (var i = 1; i <= numberOfPages; i++) {
var page = {
number: i,
page: "" + i,
};
// Make the first page active by default.
if (i === 1) {
page.active = true;
}
context.pages.push(page);
}
context.barsize = 10;
return context;
};
/**
* Convert the itemsPerPage value into a format applicable for the mustache template.
* The given value can be either a single integer or an array of integers / objects.
*
* E.g.
* In: [5, 10]
* out: [{value: 5, active: true}, {value: 10, active: false}]
*
* In: [5, {value: 10, active: true}]
* Out: [{value: 5, active: false}, {value: 10, active: true}]
*
* In: [{value: 5, active: false}, {value: 10, active: true}]
* Out: [{value: 5, active: false}, {value: 10, active: true}]
*
* @param {int|int[]} itemsPerPage Options for number of items per page.
* @return {int|array}
*/
var buildItemsPerPagePagingBarContext = function(itemsPerPage) {
var context = [];
if ($.isArray(itemsPerPage)) {
// Convert the array into a format accepted by the template.
context = itemsPerPage.map(function(num) {
if (typeof num === 'number') {
// If the item is just a plain number then convert it into
// an object with value and active keys.
return {
value: num,
active: false
};
} else {
// Otherwise we assume the caller has specified things correctly.
return num;
}
});
var activeItems = context.filter(function(item) {
return item.active;
});
// Default the first item to active if one hasn't been specified.
if (!activeItems.length) {
context[0].active = true;
}
} else {
// Convert the integer into a format accepted by the template.
context = [{value: itemsPerPage, active: true}];
}
return context;
};
/**
* Build the context for the paging bar template when we have an unknown
* number of items.
*
* @param {Number} itemsPerPage How many items will be shown per page.
* @return {object} Mustache template
*/
var buildPagingBarTemplateContextUnknownLength = function(itemsPerPage) {
if (itemsPerPage === null) {
itemsPerPage = DEFAULT.ITEMS_PER_PAGE_ARRAY;
}
var context = getDefaultPagingBarTemplateContext();
context.itemsperpage = buildItemsPerPagePagingBarContext(itemsPerPage);
// Only display the items per page selector if there is more than one to choose from.
context.showitemsperpageselector = $.isArray(itemsPerPage) && itemsPerPage.length > 1;
return context;
};
/**
* Build the context to render the paging bar template with based on the number
* of pages to show.
*
* @param {int|null} numberOfItems How many items are there total.
* @param {int|null} itemsPerPage How many items will be shown per page.
* @return {object} The template context.
*/
var buildPagingBarTemplateContext = function(numberOfItems, itemsPerPage) {
if (numberOfItems) {
return buildPagingBarTemplateContextKnownLength(numberOfItems, itemsPerPage);
} else {
return buildPagingBarTemplateContextUnknownLength(itemsPerPage);
}
};
/**
* Build the context to render the paging dropdown template based on the number
* of pages to show and items per page.
*
* This control is rendered with a gradual increase of the items per page to
* limit the number of pages in the dropdown. Each page will show twice as much
* as the previous page (except for the first two pages).
*
* By default there will only be 4 pages shown (including the "All" option) unless
* a different number of pages is defined using the maxPages config value.
*
* For example:
* Items per page = 25
* Would render a dropdown will 4 options:
* 25
* 50
* 100
* All
*
* @param {Number} itemsPerPage How many items will be shown per page.
* @param {object} config Configuration options provided by the client.
* @return {object} The template context.
*/
var buildPagingDropdownTemplateContext = function(itemsPerPage, config) {
if (itemsPerPage === null) {
itemsPerPage = DEFAULT.ITEMS_PER_PAGE_SINGLE;
}
if ($.isArray(itemsPerPage)) {
// If we're given an array for the items per page, rather than a number,
// then just use that as the options for the dropdown.
return {
options: itemsPerPage
};
}
var context = {
options: []
};
var totalItems = 0;
var lastIncrease = 0;
var maxPages = DEFAULT.MAX_PAGES;
if (config.hasOwnProperty('maxPages')) {
maxPages = config.maxPages;
}
for (var i = 1; i <= maxPages; i++) {
var itemCount = 0;
if (i <= 2) {
itemCount = itemsPerPage;
lastIncrease = itemsPerPage;
} else {
lastIncrease = lastIncrease * 2;
itemCount = lastIncrease;
}
totalItems += itemCount;
var option = {
itemcount: itemCount,
content: totalItems
};
// Make the first option active by default.
if (i === 1) {
option.active = true;
}
context.options.push(option);
}
return context;
};
/**
* Build the context to render the paged content template with based on the number
* of pages to show, items per page, and configuration option.
*
* By default the code will render a paging bar for the paging controls unless
* otherwise specified in the provided config.
*
* @param {int|null} numberOfItems Total number of items.
* @param {int|null|array} itemsPerPage How many items will be shown per page.
* @param {object} config Configuration options provided by the client.
* @return {object} The template context.
*/
var buildTemplateContext = function(numberOfItems, itemsPerPage, config) {
var context = getDefaultTemplateContext();
if (config.hasOwnProperty('ignoreControlWhileLoading')) {
context.ignorecontrolwhileloading = config.ignoreControlWhileLoading;
}
if (config.hasOwnProperty('controlPlacementBottom')) {
context.controlplacementbottom = config.controlPlacementBottom;
}
if (config.hasOwnProperty('hideControlOnSinglePage')) {
context.hidecontrolonsinglepage = config.hideControlOnSinglePage;
}
if (config.hasOwnProperty('ariaLabels')) {
context.arialabels = config.ariaLabels;
}
if (config.hasOwnProperty('dropdown') && config.dropdown) {
context.pagingdropdown = buildPagingDropdownTemplateContext(itemsPerPage, config);
} else {
context.pagingbar = buildPagingBarTemplateContext(numberOfItems, itemsPerPage);
if (config.hasOwnProperty('showFirstLast') && config.showFirstLast) {
context.pagingbar.first = true;
context.pagingbar.last = true;
}
}
return context;
};
/**
* Create a paged content widget where the complete list of items is not loaded
* up front but will instead be loaded by an ajax request (or similar).
*
* The client code must provide a callback function which loads and renders the
* items for each page. See PagedContent.init for more details.
*
* The function will return a deferred that is resolved with a jQuery object
* for the HTML content and a string for the JavaScript.
*
* The current list of configuration options available are:
* dropdown {bool} True to render the page control as a dropdown (paging bar is default).
* maxPages {Number} The maximum number of pages to show in the dropdown (only works with dropdown option)
* ignoreControlWhileLoading {bool} Disable the pagination controls while loading a page (default to true)
* controlPlacementBottom {bool} Render controls under paged content (default to false)
*
* @param {function} renderPagesContentCallback Callback for loading and rendering the items.
* @param {object} config Configuration options provided by the client.
* @return {promise} Resolved with jQuery HTML and string JS.
*/
var create = function(renderPagesContentCallback, config) {
return createWithTotalAndLimit(null, null, renderPagesContentCallback, config);
};
/**
* Create a paged content widget where the complete list of items is not loaded
* up front but will instead be loaded by an ajax request (or similar).
*
* The client code must provide a callback function which loads and renders the
* items for each page. See PagedContent.init for more details.
*
* The function will return a deferred that is resolved with a jQuery object
* for the HTML content and a string for the JavaScript.
*
* The current list of configuration options available are:
* dropdown {bool} True to render the page control as a dropdown (paging bar is default).
* maxPages {Number} The maximum number of pages to show in the dropdown (only works with dropdown option)
* ignoreControlWhileLoading {bool} Disable the pagination controls while loading a page (default to true)
* controlPlacementBottom {bool} Render controls under paged content (default to false)
*
* @param {int|array|null} itemsPerPage How many items will be shown per page.
* @param {function} renderPagesContentCallback Callback for loading and rendering the items.
* @param {object} config Configuration options provided by the client.
* @return {promise} Resolved with jQuery HTML and string JS.
*/
var createWithLimit = function(itemsPerPage, renderPagesContentCallback, config) {
return createWithTotalAndLimit(null, itemsPerPage, renderPagesContentCallback, config);
};
/**
* Create a paged content widget where the complete list of items is not loaded
* up front but will instead be loaded by an ajax request (or similar).
*
* The client code must provide a callback function which loads and renders the
* items for each page. See PagedContent.init for more details.
*
* The function will return a deferred that is resolved with a jQuery object
* for the HTML content and a string for the JavaScript.
*
* The current list of configuration options available are:
* dropdown {bool} True to render the page control as a dropdown (paging bar is default).
* maxPages {Number} The maximum number of pages to show in the dropdown (only works with dropdown option)
* ignoreControlWhileLoading {bool} Disable the pagination controls while loading a page (default to true)
* controlPlacementBottom {bool} Render controls under paged content (default to false)
*
* @param {int|null} numberOfItems How many items are there in total.
* @param {int|array|null} itemsPerPage How many items will be shown per page.
* @param {function} renderPagesContentCallback Callback for loading and rendering the items.
* @param {object} config Configuration options provided by the client.
* @return {promise} Resolved with jQuery HTML and string JS.
*/
var createWithTotalAndLimit = function(numberOfItems, itemsPerPage, renderPagesContentCallback, config) {
config = config || {};
var deferred = $.Deferred();
var templateContext = buildTemplateContext(numberOfItems, itemsPerPage, config);
Templates.render(TEMPLATES.PAGED_CONTENT, templateContext)
.then(function(html, js) {
html = $(html);
var id = html.attr('id');
// Set the id to the custom namespace provided
if (config.hasOwnProperty('eventNamespace')) {
id = config.eventNamespace;
}
var container = html;
PagedContent.init(container, renderPagesContentCallback, id);
registerEvents(id, config);
deferred.resolve(html, js);
return;
})
.fail(function(exception) {
deferred.reject(exception);
})
.fail(Notification.exception);
return deferred.promise();
};
/**
* Create a paged content widget where the complete list of items is loaded
* up front.
*
* The client code must provide a callback function which renders the
* items for each page. The callback will be provided with an array where each
* value in the array is a the list of items to render for the page.
*
* The function will return a deferred that is resolved with a jQuery object
* for the HTML content and a string for the JavaScript.
*
* The current list of configuration options available are:
* dropdown {bool} True to render the page control as a dropdown (paging bar is default).
* maxPages {Number} The maximum number of pages to show in the dropdown (only works with dropdown option)
* ignoreControlWhileLoading {bool} Disable the pagination controls while loading a page (default to true)
* controlPlacementBottom {bool} Render controls under paged content (default to false)
*
* @param {array} contentItems The list of items to paginate.
* @param {Number} itemsPerPage How many items will be shown per page.
* @param {function} renderContentCallback Callback for rendering the items for the page.
* @param {object} config Configuration options provided by the client.
* @return {promise} Resolved with jQuery HTML and string JS.
*/
var createFromStaticList = function(contentItems, itemsPerPage, renderContentCallback, config) {
if (typeof config == 'undefined') {
config = {};
}
var numberOfItems = contentItems.length;
return createWithTotalAndLimit(numberOfItems, itemsPerPage, function(pagesData) {
var contentToRender = [];
pagesData.forEach(function(pageData) {
var begin = pageData.offset;
var end = pageData.limit ? begin + pageData.limit : numberOfItems;
var items = contentItems.slice(begin, end);
contentToRender.push(items);
});
return renderContentCallback(contentToRender);
}, config);
};
/**
* Reset the last page number for the generated paged-content
* This is used when we need a way to update the last page number outside of the getters callback
*
* @param {String} id ID of the paged content container
* @param {Int} lastPageNumber The last page number
*/
var resetLastPageNumber = function(id, lastPageNumber) {
PubSub.publish(id + PagedContentEvents.ALL_ITEMS_LOADED, lastPageNumber);
};
/**
* Generate the callback handler for the page limit persistence functionality
*
* @param {String} persistentLimitKey
* @return {callback}
*/
var generateLimitHandler = function(persistentLimitKey) {
return function(limit) {
UserRepository.setUserPreference(persistentLimitKey, limit);
};
};
/**
* Set up any events based on config key values
*
* @param {string} namespace The namespace for this component
* @param {object} config Config options passed to the factory
*/
var registerEvents = function(namespace, config) {
if (config.hasOwnProperty('persistentLimitKey')) {
PubSub.subscribe(namespace + PagedContentEvents.SET_ITEMS_PER_PAGE_LIMIT,
generateLimitHandler(config.persistentLimitKey));
}
};
return {
create: create,
createWithLimit: createWithLimit,
createWithTotalAndLimit: createWithTotalAndLimit,
createFromStaticList: createFromStaticList,
// Backwards compatibility just in case anyone was using this.
createFromAjax: createWithTotalAndLimit,
resetLastPageNumber: resetLastPageNumber
};
});