lib/amd/src/paged_content_factory.js

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