Moodle 3.6

What is this?

The paged content factory allows you to quickly and easily create a paged content region (see [1]). The factory will handle creating and configuring the region for you so that it confirms with the standard Bootstrap markup (on the Boost and Clean themes).

PHP

This can be used to render the paged content in PHP however it requires that all pages be preloaded and rendered in PHP and doesn't support AJAX loading of additional pages.

If you render the paged content in PHP it will initialise all of the JavaScript required to control the navigation between pages for the user.

To render it in PHP simply render the [2] template with the appropriate context.

JavaScript

This is the real strength of this module. Core comes shipped with a paged content factory module which will create and enhance the paged content region for you. It allows you to very quickly and easily create a paged content region that asynchronously loads the pages as the user requests them.

How do I use it?

The paged content factory has a few different ways to create the element depending on how you'd like it to behave. The creation methods can be split into two categories, either asynchronous (you don't have all of the data loaded) or static (you already have all of the data you want to paginate).

If you have all of the data up front then you can give it all to the createFromStaticList list function along with a few options and the factory will create the paged content element for you.

If you'd like to load the data asynchronously then you can use one of the other create functions, depending on whether you'd like to specify the limit of items per page and/or the total number of items. All of the async create functions require you to provide a callback function which will be called in order to load and render the requested pages.

Each create function also optionally takes a config object (more information below).

Load and render callback

As part of the create functions you will be required to provide a callback function that the paged content code will call when the user requests a page. The callback function will be provided a list of pages being requested (this is typically just one page but not guaranteed to be). Each page data contains the page number (indexed from 1), the limit, and offset to use to load the data.

The callback must return an array of promises (order matching the given array) that resolve with the rendered HTML for that page.

The second parameter to the callback will be an object containing actions which can be called to trigger behaviour in the paged content. At the moment the only action that can be called is allItemsLoaded which your callback function should call to tell the paged content code that there are no more items to load. This is only required if you created the paged content area without a total upfront.

Config

You can provide a configuration object to the paged content factory in order to control certain behaviours

The current options are:

dropdown - bool (default: false) - If the pagination controls should be a dropdown instead of a paging bar
maxPages - int - Maximum number of page options for the dropdown (only works if dropdown is set to true)
ignoreControlWhileLoading - boolean (default: true) - Disable the pagination controls while a page is being loaded
controlPlacementBottom - boolean (default: false) - Put the pagination controls under the paged content area (default is above)
eventNamespace - string (default: a generated unique id) - Provide a custom namespace to prefix the pagination events with. This can be used if you have code that wants to listen to events for a specific paged content region.
persistentLimitKey - string (default: null) - If provided the factory will automatically use this value as the key to save the selected limit option in user preferences so that they persist between page loads

Example: Async load with unknown total number of items

require( [

   'jquery',
   'core/paged_content_factory',
   'core/templates'

],
function(

   $,
   PagedContentFactory,
   Templates

) {

   // Some container for your paged content.
   var container = $('#container');
   
   PagedContentFactory.createWithLimit(
       // Show 10 items per page.
       10,
       // Callback to load and render the items as the user clicks on the pages.
       function(pagesData, actions) {
           return pagesData.map(function(pageData) {
               // Your function to load the data for the given limit and offset.
               return loadData(pageData.limit, pageData.offset)
                   .then(function(data) {
                       // You criteria for when all of the data has been loaded.
                       if (data.length > 100) {
                           // Tell the page content code everything has been loaded now.
                           actions.allItemsLoaded(pageData.pageNumber);
                       }

                       // Your function to render the data you've loaded.
                       return renderData(data);
                   });
           });
       },
       // Config to set up the paged content.
       {
           controlPlacementBottom: true,
           eventNamespace: 'example-paged-content',
           persistentLimitKey: 'example-paged-content-limit-key'
       }
   ).then(function(html, js) {
       // Add the paged content into the page.
       Templates.replaceNodeContents(container, html, js);
   });

});

Documentation

AMD paged content

Contents