GI Contributor Blog Blog from Aug 31, 2009

GI Matrix scroll paging

In GI large data set can be displayed within the jsx3.gui.Matrix control which has build in paging mechanism (Paging Model property set to PAGED), which allows for large number of records to be displayed by showing only a subset of records on screen (the page). Other records that are not visible are  left un-rendered off the page. To see these off-page records you must scroll through the Matrix Table. This is where the magic of Matrix control happens, as you scroll, the on screen view is updated with new "pages" of records while the previous pages are moved off screen. This means that only the number view panel records (jsxrowsperpanel) * the number of paint queue size (jsxpaintqueuesize) are rendered at any one time. This allows a good performant Matrix table that can handle very large dataset of records.

Source for this sample here

Paging buttons/links or Scroll paging?

A very common Matrix list table question that comes up is how to create a forward and back button/links navigatable 'page' list table, a virtual scrolling mode that loads in data as needed. Why do users want button/links navigation over scrolling? Answers given range from 'Well, I like paging buttons better than scrolling', to 'It's a requirement of this app' ... or a few other reasons along those lines. However, it is most likely that the reason for  people to like 'link/button paging' over scrolling comes down to familiarity.

In a traditional JSP/ASP/PHP driven website, you couldn't display huge amounts of data without some sort of paging mechanism on server side that just showed a single page in the browser at a time. It iscommon to see a data view where a forward or next button would post some page position data to the server, and the server would send back a completely new HTML view of the data. So the reason I think user or developer would ask for a 'button paging' version of the jsx3.gui.Matrix comes down to what they know. People are used to clicking forward and back buttons to swap in new data, even through in a real desktop application the ability to scroll through a set of data is more natural, the web users (or at least the web developer believes that they) are conditioned to want clickable 'pages'.

In the following section, I will show how button navigation paging can be done with the jsx3.gui.Table control. While the same can be done for jsx3.gui.Matrix, there's a couple reasons I don't want to do that. First is the the advanced scroll paging mechanism feature build into Matrix makes such excercise a reivention of the wheel (probably less efficient also). Second is the fact that Matrix build in support for edit mask, multiple paging model, hiearchical display, etc. means that it is not suited for a simple usage such as list table view.

Implementing paging filter in jsx3.gui.Table XSL

In GI 3.8, couple paging filter parameters are added into the default jsx3.gui.Table XSL. They are jsxmaxinclusive and jsxmininclusive . By setting these XSL parameters on the Table, you can control the record rows to be displayed.

      table.setXSLParam("jsxmininclusive", start )
      table.setXSLParam("jsxmaxinclusive", end );
      table.repaint();

Following is an example implmentation of button+combo select controlled paging table

The "<" and ">" buttons use the page index from the combo select box to move to previous or next page

    samplePaging.gotoPane = function (index) {
      var table = samplePaging.APP.getJSXByName("table");
      var rowsPerPage = this.getRowsPerPage();
      var start = index*rowsPerPage;
      jsx3.log(start);
      var end = start+rowsPerPage;

      table.setXSLParam("jsxmininclusive", start )
      table.setXSLParam("jsxmaxinclusive", end );
      table.repaint();
    }

The combo select box is generated by calculating the number of pages needed to display all the rows by dividing the "rows per page" (the first textbox value) by the total number of records in the Table ( using table.getXML().selectNodes("//record").size() ).

     samplePaging.initMax = function() {
       var table = this.APP.getJSXByName("table");
       if (table) {
        samplePaging.max = table.getXML().selectNodes("//record").size();
        samplePaging.maxPage= samplePaging.max/this.getRowsPerPage();
       }
    }

    // called in onAfterDeserialize of Table
    samplePaging.init = function (indexBox) {
        this.initMax();
        var max = this.maxPage ? this.maxPage : 1;
        if (indexBox) this.indexBox = indexBox; else return;
        indexBox.clearXmlData();
        for (var i=0; i <= max; i++) {
          var rec = {};
          rec.jsxid = i;
          rec.jsxtext = i;
          indexBox.insertRecord(rec);
        }
    }

To handle user changes of "rows per page", the textbox Change event triggers a recalculation of the combo box index selector.

Download the sample project here