A Flexible View Control for XPages Part 6 – Sorting

When I started building the Flexible View Control, one of the driving forces was to significantly reduce the amount of back-end Domino views that would collect in my applications. I was just as guilty as anyone of creating a new view with the same selection formula and columns as an existing view with the only difference being the column arrangement or how the new view was sorted/categorized.

Build a Client-Side Sorting Demo

If you’ve used DataTables then you know that by default DataTables makes sorting your data by any column very easy. As a result, The Flexible View Control, being a mashup of Domino XPages and DataTables, has advanced sorting capabilities baked in.

Create a new XPage

To demonstrate this, I start by making a copy of my viewBasic XPage and call it viewBasicSorting.

Since I want to re-use this new XPage for multiple demos, I’m making my viewKey dynamic by having it look for a querystring parameter to get its value:

Using a url parameter to populate the viewKey

This means anytime I load this XPage I need to supply the name of the desired View Definition in the url:

viewBasicSorting.xsp?viewdef=used-cars-sorting-default

Create the View Definition

Now I create my new View Definition. Note that we are using an existing view and existing rest service to fetch the data.

View Definition with default sorting

In the screenshot above, there is no value in the Client Sort (1) field, meaning when the DataTable is built client-side it will display in the order the data was loaded from the rest service. If your back-end data is sorted by the 1st column, then that is how the data will display in the constructed DataTable.

viewBasicSorting.xsp?viewdef=used-cars-sorting-default

By default the id column is sorted

Adding a client-side sort

But what if your users insist on another view that sorts by Price with the Price column being first? In Notes/Domino, you begrudgingly copy your view, move the Price column to the front and make sure it’s sorted. UGH!

This is where the “Flexible” part of the Flexible View Control comes in. All I have to do is create a new View Definition, point it to the same data, and simply drag the Price column to the top and designate that as the sort column in the Client Sort (1) field. In my case I want to sort it descending.

View Definition sorted by price
Important: The value entered in the Client Sort must match the itemName of the column you want to sort.

The results

Now, I can load my view viewBasicSorting XPage and simply change the viewdef url parameter to show a different “virtual view”, in this case By Price:

viewBasicSorting.xsp?viewdef=used-cars-sorting-byprice

Same data from same view now sorted by price

Recap

Using one back-end view, and one XPage equipped with the Flexible View Control, we can display countless views to the front-end user by simply making a View Definition for each front-end view we need to display. Cool!

Advanced Sorting

When specifying the column to sort in a View Definition we use the Client Sort (1) field. But you may have noticed a field below that named Client Sort (2) and perhaps you wondered what purpose this serves.

DataTables has incredible advanced sorting capabilities, as the gif below illustrates.

Advanced DataTables sort capabilities

To get the multiple column sorting capability in the Flexible View Control, we use the Client Sort (2) field. To demonstrate I created a new View Definition that points to the same Domino view we’ve been using. This time, I make the Client Sort (1) by Year (descending) and add Price as a secondary sort, also descending.

When I look at the By Year view I can see that it has a primary sort (by year) and secondary sort (by price).

Sorting Server-side

My preference is to do all sorting client-side and have my back-end views act as fairly static tables of data that are indexed well and can respond quickly to requests. The View Definition does have a “Server Sort” field but it currently is not operable.

However, if you do need to sort server side before returning data view a rest service or xAgent you can certainly do so.

Important: to resort a back-end view server-side you must set the column sort setting to “both” for any column you want to be able to resort by.

To demonstrate sorting the price column I start by creating a new View Definition with pretty much all the defaults except I move the Price column to the first position (Note: the column you want to be the first sort does NOT have to be in the first position).

Next, I update the rest service that has been used repeatedly to look for the sortColumn and sortOrder query string parameters:

<xe:restService id="restService1" pathInfo="used-cars-phil-chevy-tahoe-basic"
		state="false">
		<xe:this.service>
			<xe:viewJsonService systemColumns="2"
				viewName="xspPhilPaChevTahoe" defaultColumns="true" count="1000">
				<xe:this.databaseName><![CDATA[#{javascript:@DbName()[0]+"!!demos\\used_cars.nsf"}]]></xe:this.databaseName>
				<xe:this.sortColumn><![CDATA[#{javascript:context.getUrlParameter("sortColumn")!="" ? context.getUrlParameter("sortColumn") : ""}]]></xe:this.sortColumn>
				<xe:this.sortOrder><![CDATA[#{javascript:context.getUrlParameter("sortOrder")!="" ? context.getUrlParameter("sortOrder") : ""}]]></xe:this.sortOrder>
			</xe:viewJsonService>
		</xe:this.service>
	</xe:restService>

Finally, the Flexible View Control has a queryString parameter that can be utilized to pass url parameters to the rest service being called to retrieve data.

context.getUrlParameter("viewdef") == "used-cars-sorting-server-byprice" ? "&sortColumn=PRICE&sortOrder=descending" : ""

The Results

viewBasicSorting.xsp?viewdef=used-cars-sorting-server-byprice

Price column sorted server-side

While we get the desired result, notice that there is no indication in the column header that Price is the sorted column. Only by examining the data can you determine that.


A Flexible View Control for XPages Part 5 – Processing Selected Rows

The previous post in this series demonstrated how to add click events to a view created with the Flexible View Control utilizing the callbacks that are built into DataTables. But once a row (or rows) is selected, how do you actually DO something with the selection?

Getting a Handle On Selected Rows

There is a hidden field on the control that stores the @unid of the selected rows along with any other data the View Definition configured to return when selected (in JSON format). When the control is rendered, a class is applied to the field based on the “thisView” parameter given to the control.

Client-Side Data

In the demo we built in Part 4, we gave our thisView parameter the value “viewBasic”. This allows us to reference the selected row(s) client-side in jQuery with the syntax:

$('.fldviewBasic').val();

Using the demo from http://demos.xpage.me/demos/datatables-xpages-bootstrap.nsf/viewBasicCallbacks.xsp, when I select a row and examine the hidden field in dev tools I see:

Hidden field with selected row data stored as JSON

What if I select multiple rows?

What if I want to return data besides just the row’s document id? To do so, I update the View Definition to tell it to return the columns I want when I click a row:

In this example, I want to return the ID and VIN columns in addition to @unid.

Important Note: By default, the @unid value is returned when a row is clicked. The Return Value of the View Definition overrides this value. Therefore, if values are entered in this field on the View Definition, @unid needs to be included if that value needs to be accessed.

Server-Side Data

The Flexible View Control also makes it easy to pass the selected rows server-side. The aforementioned hidden field is bound to a viewScope mapped to the thisView value.

thisView composite data bound to a viewScope

To demonstrate, I’m adding a button to my example above that does a partial refresh on a panel and executes some server-side code to examine the selected rows:

Server-side action with no document selected
Server-side action with a document selected

Recap

The Flexible View Control for XPages makes it very easy to get a handle on the rows selected in a view and process that data both client-side and server-side

In the next post …

I’ll start to demonstrate the “flexible” part of the Flexible View Control by showing how a Domino view with over 2 million records can be mined to create different representations of data with the control through the power of the View Definitions.


A Flexible View Control for XPages Part 4 – Callbacks & Click Events

Regardless of the type of application you’re working with, when interacting with view data you typically want to be able to take some type of action on that data, such as open a document or manipulate the data in some way.

Callbacks

DataTables, being very callback “heavy”, has two callbacks that can be utilized to add row-level functionality to take action on a clicked/double-clicked row and its data:

CallbackFrom the DataTables documentation
rowCallbackThis callback allows you to ‘post process’ each row after it have been generated for each table draw, but before it is rendered into the document.
createdRowThis callback is executed when a TR element is created (and all TD child elements have been inserted), or registered if using a DOM source, allowing manipulation of the TR element.

The Flexible View Control has properties that make incorporating these callbacks into your table build quite easy.

Flexible View Control createdRow and rowCallback

The View Control has a scriptBlock that builds a JavaScript object at runtime which contains the DataTable initialization code. This initialization code contains placeholders for rowCallback and createdRow (as well as other callbacks) that are evaluated by Expression Language to create function calls at runtime. The necessary function parameters are passed in automatically.

Callbacks created with Expression Language

You’ll notice in the createdRow callback above that by default the documentId of each row is added as a class parameter. As you will see, this makes it easy to identify rows that have been clicked/double-clicked when needing to take action.

The Flexible View Control source code has a default rowCallback function that can be utilized to add some basic click/double-click actions. Building on the demo created in the previous post, I’m going to add this rowCallback to that control.

Adding the rowCallback function to the control

Note: It’s important to use the correct syntax when supplying a function to a callback property in the view control. Since Expression Language is being used to dynamically create the function call, the “()” are not needed.

CorrectccRestView.defaultRowCallback
IncorrectccRestView.defaultRowCallback()

The defaultRowCallback code is below:

defaultRowCallback : function(row,data,index,params,o) {
		var attr = $(row).attr("data-docid");
		
		// For some browsers, `attr` is undefined; for others, `attr` is false. Check for both.
		if (typeof attr !== typeof undefined && attr !== false) {
		  // Element has this attribute
			return;
		}
		
		// add some row attr
		$(row).attr("data-docid",data['@unid']);
		$(row).attr("data-xpage",data[o.xpage]);

                // These are defined by the return values field on the view definition
		for (var x=0;x<params.length;x++) {		
			params[x] != "@unid" ? $(row).attr("data-value-"+params[x],data[params[x]]) : "";
		}
		
		var retData = ccRestView.getReturnData(o,data);
	
		$(row).attr("data-return",JSON.stringify(retData));
		$(row).click(function(ev) {
		
			// 	Get the row data 
			var retData = $(row).attr("data-return");

			if ($("td",$(this)).hasClass("rowSelectOn")) {
							
				if (o.multiValue=="true") {
					
					if (ev.ctrlKey && ev.shiftKey) {
						// do nothing
						
					} else if (ev.ctrlKey) {
						// Remove the selected class from the selected row
						ccRestView.removeSelectedRow(o,retData,this);
						
					} else if (ev.shiftKey) {
						
						if (index > window[o.thisView].config.firstIndex) {
							
							$("."+o.dataTableClass + " tbody tr").each(function(rowIndex) {
								
								if (rowIndex >= window[o.thisView].config.firstIndex && rowIndex <= index) {
									retData = $(this).attr("data-return");
									ccRestView.insertSelectedRow(o,retData,this)
								}
							})
						} else {
							console.log("select rows " + index + " to " + window[o.thisView].config.firstIndex);
						}
					} else {
						// no keys pressed.  select this row only
						
						ccRestView.clearSelectedRows(o,this);								
						ccRestView.insertSelectedRow(o,retData,this);
						window[o.thisView].config.firstIndex = index;
					}
				} else {
					// Remove the selected class from the selected row
					ccRestView.removeSelectedRow(o,retData,this);
				}
							
			} else {
				
				if (o.multiValue!="true") {
					// Remove the selected class from all rows first
					ccRestView.clearSelectedRows(o,this);
					ccRestView.insertSelectedRow(o,retData,this);
				} else {
					// multi
					if (ev.shifKey && ev.ctrlKey) {
						
					} else if (ev.ctrlKey) {
						ccRestView.insertSelectedRow(o,retData,this);
						window[o.thisView].config.firstIndex = index;
					} else if (ev.shiftKey) {
						ccRestView.clearSelectedRows(o, this);
						
						if (index > window[o.thisView].config.firstIndex) {
							
							$(o.dataTableClass + " tbody tr").each(function(rowIndex) {
								
								if ($(this).attr("data-index") >= window[o.thisView].config.firstIndex && $(this).attr("data-index") <= index) {
									retData = $(this).attr("data-return");
									ccRestView.insertSelectedRow(o,retData,this)
								}
							})
						} else {
							console.log("select rows " + index + " to " + window[o.thisView].config.firstIndex);
						}
					} else {
						ccRestView.clearSelectedRows(o,this);
						ccRestView.insertSelectedRow(o,retData,this, function() {
							
						});
						window[o.thisView].config.firstIndex = index;
					}
					
				}
						
			}
			
		}); // end click
		
		$(row).dblclick(function() {
			
			// get the unid of the double clicked row
			var docid = $(this).attr("data-docid");
			href = location.href.split(".nsf");
			location.href=href[0]+".nsf/"+o.xpage+".xsp?documentId="+docid+"&action=editDocument";
		});

Click Events

So what exactly is the rowCallback doing?

First, some attributes are added to the row dom to make it easier to reference this row by the @unid when it’s clicked or double-clicked:

var attr = $(row).attr("data-docid");
		
		// For some browsers, `attr` is undefined; for others, `attr` is false. Check for both.
		if (typeof attr !== typeof undefined && attr !== false) {
		  // Element has this attribute
			return;
		}
		
		// add some row attr
		$(row).attr("data-docid",data['@unid']);

The data-xpage attribute is added to store the XPage that should be opened when this row is double-clicked. This value typically comes from the View Definition:

$(row).attr("data-xpage",data[o.xpage]);

Next, more parameters are added. This portion of the code is useful when data besides @unid needs to be extracted from a row and passed on to another process.

// These are defined by the return values field on the view definition
		for (var x=0;x<params.length;x++) {		
			params[x] != "@unid" ? $(row).attr("data-value-"+params[x],data[params[x]]) : "";
		}
		
		var retData = ccRestView.getReturnData(o,data);
	
		$(row).attr("data-return",JSON.stringify(retData));

Now, we add the click event to every row. When a row is clicked the following evaluations are made:

  • Does this view allow multiple selections?
    • If so, check for other key presses (ctrl, shift). The control handles multiple selections like windows explorer.
  • Is this row already selected?
    • If not, add a class that changes the row color and add the row @unid to a hidden field (more on this in the next post).
    • If so, remove the class that changes the row color and remove the @unid from the hidden field.
        $(row).click(function(ev) {
         
            //  Get the row data 
            var retData = $(row).attr("data-return");
 
            if ($("td",$(this)).hasClass("rowSelectOn")) {
                             
                if (o.multiValue=="true") {
                     
                    if (ev.ctrlKey && ev.shiftKey) {
                        // do nothing
                         
                    } else if (ev.ctrlKey) {
                        // Remove the selected class from the selected row
                        ccRestView.removeSelectedRow(o,retData,this);
                         
                    } else if (ev.shiftKey) {
                         
                        if (index > window[o.thisView].config.firstIndex) {
                             
                            $("."+o.dataTableClass + " tbody tr").each(function(rowIndex) {
                                 
                                if (rowIndex >= window[o.thisView].config.firstIndex && rowIndex <= index) {
                                    retData = $(this).attr("data-return");
                                    ccRestView.insertSelectedRow(o,retData,this)
                                }
                            })
                        } else {
                            console.log("select rows " + index + " to " + window[o.thisView].config.firstIndex);
                        }
                    } else {
                        // no keys pressed.  select this row only
                         
                        ccRestView.clearSelectedRows(o,this);                               
                        ccRestView.insertSelectedRow(o,retData,this);
                        window[o.thisView].config.firstIndex = index;
                    }
                } else {
                    // Remove the selected class from the selected row
                    ccRestView.removeSelectedRow(o,retData,this);
                }
                             
            } else {
                 
                if (o.multiValue!="true") {
                    // Remove the selected class from all rows first
                    ccRestView.clearSelectedRows(o,this);
                    ccRestView.insertSelectedRow(o,retData,this);
                } else {
                    // multi
                    if (ev.shifKey && ev.ctrlKey) {
                         
                    } else if (ev.ctrlKey) {
                        ccRestView.insertSelectedRow(o,retData,this);
                        window[o.thisView].config.firstIndex = index;
                    } else if (ev.shiftKey) {
                        ccRestView.clearSelectedRows(o, this);
                         
                        if (index > window[o.thisView].config.firstIndex) {
                             
                            $(o.dataTableClass + " tbody tr").each(function(rowIndex) {
                                 
                                if ($(this).attr("data-index") >= window[o.thisView].config.firstIndex && $(this).attr("data-index") <= index) {
                                    retData = $(this).attr("data-return");
                                    ccRestView.insertSelectedRow(o,retData,this)
                                }
                            })
                        } else {
                            console.log("select rows " + index + " to " + window[o.thisView].config.firstIndex);
                        }
                    } else {
                        ccRestView.clearSelectedRows(o,this);
                        ccRestView.insertSelectedRow(o,retData,this, function() {
                             
                        });
                        window[o.thisView].config.firstIndex = index;
                    }
                     
                }
                         
            }
             
        }); // end click

The double-click event is much simpler. It simply opens the selected document using the XPage defined on the View Definition:

$(row).dblclick(function() {
			
			// get the unid of the double clicked row
			var docid = $(this).attr("data-docid");
			href = location.href.split(".nsf");
			location.href=href[0]+".nsf/"+o.xpage+".xsp?documentId="+docid+"&action=editDocument";
		});

Selecting Multiple Rows

Set the multiValue property of the view control to true:

Now, I can select multiple documents by holding <ctrl> or <shift> when clicking:

Building a Demo

In order to demonstrate everything described above, I’m going to make a copy of my viewBasic XPage that was created in Part 3, call it viewBasicCallbacks and add the rowCallback:

I’m leaving everything else intact – using the same settings and the same View Definition.

To demo the double-click, I create a basic XPage to display a used car record and I need to update my View Definition so that when I double click a row in the view it opens this carDocument XPage:

carDocument XPage
Adding carDocument to the View Definition
Double-clicking a row opens the selected document with the carDocument XPage

Here’s the link: http://demos.xpage.me/demos/datatables-xpages-bootstrap.nsf/viewBasicCallbacks.xsp

In the next post …

We will see how the selected rows can be accessed both client and server side.


A Flexible View Control for XPages Part 2 – Starting An Application

Get the code

To get started using the Flexible View Control, get your hands on the code.  You can do this via two methods:

  • By pulling down a fresh database from the github repo.
  • By downloading the nsf from here.  Make sure you sign the database.

Once you have the database open in Domino Designer either locally, or on your server,  build your project.

In Part 1 of the Flexible View Control or XPages series, I gave an overview of the control and architecture of how it works.  Now we get to see it in action.

Starting with this blog post, I’m going to demonstrate many features of the FVCX by creating an application starting with the FVCX source database.  As the series moves on, I’ll be using a separate database to provide the data – a Used Car database with over 2 million records and only a couple of Notes views.  Part of demonstrating the FVCX will be sharing Notes view strategies that simplify surfacing of data not just for views, but for other components like typeaheads.

Out-of-the-box the Flexible View Control has very basic styling to make it easier to integrate with whatever UI design you want to use.  For my demos, I’m going to utilize Bootstrap.

The included theme has links to a Bootstrap CDN that are commented out.  To add Bootstrap I just unhide the css and js links.

 

Configuring the Database

Now we are ready to get started!  Keep reading below or take a look at the video to the right to see the steps below in action.

Configuration involves two steps:

  • Creating the config doc used by View Definitions (adminConfig.xsp)
  • Creating the first View Definition which is used to display all View Definitions (adminViewDefinitionDoc.xsp)

The first element we are going to work with is the adminConfig XPage.  Open this page in your browser.

The purpose of this XPage is to store some basic configuration information that is used when creating View Definitions.

  • Rest Service Path – this is the path (<dir>/<database.nsf>) where you will create rest services to retrieve data.  If you leave it blank then the control will look in the current database to find rest services.
  • Servers – The list of servers that contain databases with views you need to create View Definitions for.  This list populates a dropdown on the adminViewDefinitionDoc XPage.  Leave blank if you only need to use the current server.
  • Databases – The list of databases with views you need to create View Definitions for.  This list populates a dropdown on the adminViewDefinitionDoc XPage.  This becomes important if you are separating your data from your design.

Click the Save button.  A Notes document is created.  Verify it is there by looking in the vwConfig view.  Now, any time the adminConfig XPage is opened the created doc will be automatically loaded.

 

Creating the first View Definition

The first View Definition we’re going to create will be to display …. the list of View Definitions.  Is your head spinning yet?  From the adminConfig XPage click the Create View Definition button.

The adminViewDefinitionDoc XPage opens:

There’s quite a bit to unpack here so let’s start with the basics so we can see what the results look like.

View Definition This is the “key” for this view def and should be a unique value. It’s also a good idea to make it url friendly as we will see in future posts. I am calling this view-definitions.
Use Rest Service This value should match the “path-info” of a Domino REST Service control. This is only needed if the value above is different than the path-info of your REST service. I’m leaving this blank.
Use Rest XPage This is the XPage where the REST service for this View Defintion is located. The database comes with a restServices XPage so I enter that value here.
Load On Init When checked, this tells the control to load the view as soon as the control is loaded. Since I want my view to load right away, I select it.
Server This is the list of servers we defined on the adminConfig XPage. I select *current server*
Database This is the list of datbases we defined on the adminConfig XPage. I select *current database*.
View Since I’m creating the “View Definitions” View Definition, I choose that view. (I really didn’t want to write View Definition for a 3rd time. Crap, I did it anyway)

After selecting the View in the dropdown, all of the columns show up below. Now I can start to configure how the view will look.  For my example, I’m select all of the columns except the last one.

The FVCX database comes with an XPage adminViewDefinitions that is used to show all View Definitions in the application.  This page has the custom control already dragged onto it and configured to point to our view-definitions view def we just created:

 

When creating the View Definition above, we told it that our REST service was located on the restServices XPage:

Back to the View Definition… When I click the Save button , I’m automatically redirected to this XPage.  Here is what it looks like:

We are off and running with the Flexible View Control.  In the next post we will start working with some “real” data.


A Flexible View Control for XPages Part 1 – Introduction

In my last post, I stated I would be expanding on the topics from my session “Real World XPages” at Collabsphere 2019.

The first topic is A Flexible View Control for XPages, a custom control integrated with jQuery and DataTables that once added to your design (along with it’s companion elements) can easily be added to any XPage  and connected to back-end Domino data in minutes through a Domino REST Service or an XAgent.

 

Why was this created?

  • Frustration with the available tools in XPages for displaying view data.  Anyone that has tangled with a View Panel knows exactly what I’m talking about.
  • Efficiency in development by avoiding recreating the same code over and over again.  When I make a change to the design of this control all of the views created with it get the update immediately.
  • To minimize view overhead.  One view can be reused over and over which minimizes the number of view indexes that need to be built and maintained.  Say goodbye to creating a view just because you need to show your data sorted by a different column!

This tool has been battle-tested in production for 4-5 years with every view and embedded view in our huge XPage application utilizing this control to surface data.  Over those 4-5 years it has grown and evolved to be extremely flexible and capable of handling many different use cases.  It has been, without a doubt, the single most important piece of functionality in our application as it has been leveraged over and over again to surface data.

At CollabSphere Andrew Davis of HCL stated that “XPages is still the recommended technology in the Domino stack to modernize applications” (paraphrasing).  Obviously, this could change with Domino V11 and beyond.  But wIth the recent chatter about XPages and the desire many still have to continue creating and enhancing applications, my hope is others will find the value in this tool that I have.

How it works

  • View Definitions are the ‘wiring’ for the Flexible View Control.
  • They are stored as Lotus Notes Documents and act as the View design for the Flexible View Control.  This moves much of the management of views out of the actual design element.
  • One View can be represented many different ways with different sorting, column orders and even categorization.
  • The Lotus Notes View simply acts as a table of data served via REST services.
  • View rendering is done client side with DataTables.


 

How to get the code

The Flexible View Control for XPages is available on github:

https://github.com/michaelgsmith/datatables-xpages

Here you will find detailed descriptions of the project assets and custom control properties.  Before diving in, I highly recommend absorbing the next few blog posts which will detail and explain how to get everything set up and demonstrate how to make effective use of the control.

Note:

  • The included theme loads jQuery and DataTables from a public CDN
  • The out-of-box UI is very plain to make it easier to integrate with existing projects
  • While Bootstrap is not required, the control is already equipped to integrate with Bootstrap

 

Demos

Stay tuned for Part 2 (and beyond) where I will demo how easy it is to get the database/control setup and connected to data!