page UI Component

Ben Tiedt — Fri, 08 Mar 2024 17:52:11 GMT

Current Revision posted to API Documentation by Ben Tiedt on 03/08/2024 17:52:11

jQuery.telligent.evolution.ui.components.page

[[ui JavaScript API Module|UI Component]] which handles automatic presentation of a paging control. Transforms the output from $core_v2_ui.Page(), which is a <span class="ui-page"></span> stub. The default implementation uses the [[evolutionPager jQuery Plugin|evolutionPager plugin]]. [[ui JavaScript API Module|Overrides can be provided]] at the theme level to present paging differently, either by different usage of [[evolutionPager jQuery Plugin|evolutionPager plugin]] or by an entirely different paging UI.

Options

Data made available to instances of the component:

currentpage: Current page index
pagesize: Items per page
totalitems: Total items
pagekey: Pager-specific query string key to use for page numbers
pagedcontenturl: Optional ajax endpoint for retrieving paged content (for ajax paging)
pagedcontentwrapperid: Optional DOM id of an element to update with paged content retrieved from the ajax paging endpoint
pagedcontentpagingevent: Optional name of a client message to raise when ajax paging is occurring
pagedcontentpagedevent: Optional name of a client message to raise when ajax paging has completed
loadingindicator: When true, shows a loading indicator mask on the pagedcontentpagingevent, hiding it on the pagedcontentpagedevent event.
loadonanyhashchange: When true, reloads the currently viewed page on any hashchange when using ajax paging
configuration: Object of all other keys and values passed via the options dictionary to $core_v2_ui.Page(), regardless of whether they have been pre-defined
- [[evolutionPager jQuery Plugin|jQuery.evolutionPager]] looks for the following optional configuration:
  - ShowPrevious: Whether 'previous' links should be shown (default: false)
  - ShowNext: Whether 'next' links should be shown (default: false)
  - ShowFirst: Whether 'first' links should be shown (default: true)
  - ShowLast: Whether 'last' links should be shown (default: true)
  - ShowIndividualPages: Whether individual pages should be shown (default: true)
  - NumberOfPagesToDisplay:: Number of individual pages to show (default: 5)

Example

A barebones UI component override which would result in rendering the current page number with back and next links, and not performing any paging via Ajax regardless of whether a pagedcontenturl was provided:

$.telligent.evolution.ui.components.page = {
    setup: function() {
    },
    add: function(elm, options) {
        var message = '',
            currentPage = parseInt(options.currentpage, 10)

        // show a previous link
        if(currentPage > 0) {

            // build a URL using the query string key
            var previousPageQuery = {}, previousPageHref;
            previousPageQuery[options.pagekey] = currentPage;
            previousPageHref = $.telligent.evolution.html.encode(
                $.telligent.evolution.url.modify({ query: previousPageQuery }));

            message = '<a href="' + previousPageHref + '">Previous</a>';
        }

        // show current page
        message = message + 'Page: ' + (currentPage + 1);

        // show a next link
        if((currentPage + 1) < options.totalitems / options.pagesize) {

            // build a URL using the query string key
            var nextPageQuery = {}, nextPageHref;
            nextPageQuery[options.pagekey] = currentPage + 2;
            nextPageHref = $.telligent.evolution.html.encode(
                $.telligent.evolution.url.modify({ query: nextPageQuery }));

            message = message + '<a href="' + nextPageHref + '">Next</a>';
        }

        $(elm).html(message);
    }
};

Default Implementation

For reference purposes or as the basis for an override:

(function($){

function showLoadingIndicator(container, mask) {
    var containerOffset = container.offset();
    mask.hide().appendTo('body').css({
        width: container.width(),
        height: container.height(),
        top: containerOffset.top,
        left: containerOffset.left
    }).show();
}

function hideLoadingIndicator(container, mask) {
    mask.hide();
}

function buildMask() {
    return $('<div></div>').css({
        backgroundColor: '#fff',
        position: 'absolute',
        opacity: .75,
        zIndex: 1
    });
}

var ajaxPagerContexts = {};
$.telligent.evolution.ui.components.page = {
    setup: function() {

    },
    add: function(elm, options) {
        // general settings
        var settings = {
            currentPage: parseInt(options.currentpage, 10),
            pageSize: parseInt(options.pagesize, 10),
            totalItems: parseInt(options.totalitems, 10),
            showPrevious: typeof options.configuration.ShowPrevious === 'undefined' ? false : options.configuration.ShowPrevious === 'true',
            showNext: typeof options.configuration.ShowNext === 'undefined' ? false : options.configuration.ShowNext === 'true',
            showFirst: typeof options.configuration.ShowFirst === 'undefined' ? true : options.configuration.ShowFirst === 'true',
            showLast: typeof options.configuration.ShowLast === 'undefined' ? true : options.configuration.ShowLast === 'true',
            showIndividualPages: typeof options.configuration.ShowIndividualPages === 'undefined' ? true : options.configuration.ShowIndividualPages === 'true',
            numberOfPagesToDisplay: typeof options.configuration.NumberOfPagesToDisplay === 'undefined' ? 5 : parseInt(options.configuration.NumberOfPagesToDisplay, 10),
            pageKey: options.pagekey,
            hash: options.configuration.Target,
            baseUrl: options.configuration.BaseUrl || window.location.href,
            template: typeof options.configuration.Template !== 'undefined' ? options.configuration.Template : '' +
                ' <% foreach(links, function(link, i) { %> ' +
                '     <% if(link.type === "first") { %> ' +
                '         <a href="<%: link.url %>" class="first" data-type="first" data-page="<%= link.page %>" data-selected="false"><span>&#171;</span></a> ' +
                '     <% } else if(link.type === "previous") { %> ' +
                '         <a href="<%: link.url %>" class="previous" data-type="previous" data-page="<%= link.page %>" data-selected="false"><span>&#60;</span></a> ' +
                '     <% } else if(link.type === "page") { %> ' +
                '         <a href="<%: link.url %>" class="page<%= link.selected ? " selected" : "" %>" data-type="page" data-page="<%= link.page %>" data-selected="<%= link.selected ? "true" : "false" %>"><span><%= link.page %></span></a> ' +
                '     <% } else if(link.type === "next") { %> ' +
                '         <a href="<%: link.url %>" class="next" data-type="next" data-page="<%= link.page %>" data-selected="false"><span>&#62;</span></a> ' +
                '     <% } else if(link.type === "last") { %> ' +
                '         <a href="<%: link.url %>" class="last" data-type="last" data-page="<%= link.page %>" data-selected="false"><span>&#187;</span></a> ' +
                '     <% } %> ' +
                '     <% if(i < (links.length - 1)) { %> ' +
                '         <span class="separator"></span> ' +
                '     <% } %> ' +
                ' <% }); %> '
        };
        // ajax-specific options
        if(options.pagedcontenturl) {
            ajaxPagerContexts[options.pagedcontentpagingevent] = {
                onPage: function(pageIndex, complete, hash) {
                    var data = hash || {};
                    data[options.pagekey] = pageIndex;
                    // modify the url instead of passing as data, as the url might have this in the querystring already
                    var url = $.telligent.evolution.url.modify({ url: options.pagedcontenturl, query: data });
                    $.telligent.evolution.get({
                        url: url,
                        cache: false,
                        success: function(response) {
                            complete(response);
                        }
                    });
                }
            };
            $.extend(settings, {
                onPage: function(pageIndex, complete, hash) {
                    ajaxPagerContexts[options.pagedcontentpagingevent].onPage(pageIndex, complete, hash);
                },
                refreshOnAnyHashChange: (options.loadonanyhashchange === 'true'),
                pagedContentContainer: '#' + options.pagedcontentwrapperid,
                pagedContentPagingEvent: options.pagedcontentpagingevent,
                pagedContentPagedEvent: options.pagedcontentpagedevent,
                transition: options.configuration.Transition,
                transitionDuration: typeof options.configuration.TransitionDuration === 'undefined' ? 200 : parseInt(options.configuration.TransitionDuration, 10)
            });
        }
        $(elm).evolutionPager(settings);

        if(options.loadingindicator === 'true') {
            var container = $('#' + options.pagedcontentwrapperid), mask = buildMask();
            $.telligent.evolution.messaging.subscribe(options.pagedcontentpagingevent, function(){
                showLoadingIndicator(container, mask);
            });
            $.telligent.evolution.messaging.subscribe(options.pagedcontentpagedevent, function(){
                hideLoadingIndicator(container, mask);
            });
        }
    }
};

}(jQuery));