My CollabSphere session | DEV115 | Using XPages and Bootstrap tabs to build a (Monolithic) Single-Page Application (of Micro Front-Ends)
Posted: November 2, 2021 Filed under: Bootstrap, Collabsphere, Domino, XPages | Tags: Bootstrap, Collabsphere, Domino, HCL, XPages 5 CommentsIt’s been two weeks since CollabSphere but better late than never in releasing my session, right?
Once again, Richard and his team have pulled off a phenomenal event. Whether joining as an attendee or a speaker, the mechanism by which one could participate in sessions really could not be any smoother. Having presented at Collabsphere previously in person, I was thrown off initially by not being able to feel the “energy” in the room so to speak, but I quickly settled in and felt quite comfortable.
flexTabs
The session starts out focusing on solutions I’ve built within my organization but ends with “flexTabs” demos – a soon-to-be-released project that can make creating dynamic XPage applications easier and faster. Enjoy!
Join me at CollabSphere 2021!
Posted: October 15, 2021 Filed under: Bootstrap, Domino, HCL, jQuery, XPages | Tags: Bootstrap, Collabsphere, Domino, HCL, jQuery, XPages Leave a commentCollabSphere, perennially a great conference, will be held virtually for the 2nd year in a row from Oct. 19th – Oct. 21st and I am fortunate to be presenting a session this year.
DEV115: Using XPages and Bootstrap tabs to build a (Monolithic) Single-Page Application (of Micro Front-ends)
Time: Tuesday 10/19 @ 2PM EST
While the title is a bit wordy, it is meant to be a little cheeky … This session will demonstrate how at Mutual Boiler Re we use Bootstrap tabs and jQuery to provide our XPages applications with a structure that allows multiple pages, views, and documents to be opened within one browser tab, essentially creating a Single Page Application that mimics the Notes Client in a browser.
Thank you to Richard and the Collabsphere team for this opportunity. I look forward to seeing you there!
A Flexible View Control for XPages Part 10 – Multiple Views Using Tabs
Posted: May 11, 2020 Filed under: Bootstrap, DataTables, Domino, Flexbox, JavaScript, XPages | Tags: Bootstrap, Domino, Flexbox, JavaScript, XPages Leave a commentIf you’ve been a Domino Developer long enough, then you remember when embedded views were added to Lotus Notes (version 5?) and how it turned your world upside down with the information you could easily make available to users on one form.
Combining The Flexible View Control with Bootstrap tabs makes adding this type of functionality to your XPages application incredibly easy. The demo below uses the used car database to display a few different types of large SUVs on one XPage in different tabs. Each tab is sourced from the same view that contains 2.2 million documents but is categorized creatively to easily drill down to the desired data.
Now, you don’t have to use Bootstrap tabs (or any tabs for that matter) – I do since I’m using Bootstrap as my layout framework and this page has the standard out-of-the-box tab setup with a tab strip navigator and tab. The entire page layout looks like this:
<div class="level0-flex-container">
<div class="level0-flex-item">
<xc:ccNav></xc:ccNav>
</div>
<div class="level0-flex-view">
<div class="level0-flex-item" style="padding-top:10px;background:#ddd">
<ul class="nav nav-tabs" role="tablist">
<li role="presentation" class="active" style="margin-left:25px;">
<a href="#tahoe" aria-controls="tahoe" role="tab" data-toggle="tab"
class="tahoe">
Chevrolet Tahoe
</a>
</li>
<li role="presentation">
<a href="#yukon" aria-controls="profile" role="tab" data-toggle="tab"
class="yukon">
GMC Yukon
</a>
</li>
<li role="presentation">
<a href="#escalade" aria-controls="messages" role="tab"
data-toggle="tab" class="escalade">Escalade</a>
</li>
<li role="presentation">
<a href="#expedition" aria-controls="settings" role="tab"
data-toggle="tab" class="expedition">Expedition</a>
</li>
</ul>
</div>
<div class="tab-content"
style="">
<div role="tabpanel" class="tab-pane active flex-tab" id="tahoe"
style="">
<Flexible View Control>
</div>
<div role="tabpanel" class="tab-pane flex-tab" id="yukon"
style="">
<Flexible View Control>
</div>
<div role="tabpanel" class="tab-pane flex-tab" id="escalade"
style="">
<Flexible View Control>
</div>
<div role="tabpanel" class="tab-pane flex-tab" id="expedition"
style="">
<Flexible View Control>
</div>
</div>
</div>
</div>
Flexbox, again
If you read Part 8 of this series, then you probably remember how important of a role Flexbox plays in the layout of the Flexible View Control. Getting the FVC to size properly in a Bootstrap tab panel is no different. We add a little extra CSS to make those tab panels flex so the view control fills up the available space in each tab:
.tab-content {
flex:1;
position:relative;
flex-basis:auto;
display:flex;
flex-direction:column;
}
.tab-pane.flex-tab {
display:flex;
flex:1;
position:relative;
flex-basis:auto;
flex-direction:column
}
.tab-pane.flex-tab {
display:none !important;
}
.tab-pane.flex-tab.active {
display:flex !important;
}
Now that the page is laid out we can add our view controls to each tab panel. The image below shows the FVC for the first tab, although the other three tabs are essentially configured the same.
Remember: thisView must be unique! This is what allows multiple views to be added to one XPage.
An important takeaway from the highlighted areas in the screenshot above: loadOnInit: false. Setting loadOnInit directly in the control will override the value defined in the View Definition. We set it to false here because we want to build the table manually, and even though the page has four views, we only want to fetch the data for the ‘active’ tab when the page loads:
$( document ).ready(function() {
TahoeView.build({
params: 'category=make:Chevrolet:model:Tahoe&view=xspAll'
});
}
- When loadOnInit: true the control will automatically execute the .build() function.
- When loadOnInit: false the DataTable can be built manually by calling [thisView].build().
- Refresh a view at anytime by calling [thisView].build()
So how do we load the data for the other tabs? In Part 7 – Modals & Picklists, we talked about needing to wait until a modal was ‘shown’ before building the view in a Picklist to make sure that the DataTable sized correctly. Similarly here, to load a view in a tab we need to wait until that tab is ‘shown’. To do that, again, we tap into a Bootstrap event:
$('.tahoe').on('shown.bs.tab', function (e) {
// Even though this view is built on page load
// the shown property can be set so the view refreshes
// when this tab is made active again
TahoeView.build();
});
$('.yukon').on('shown.bs.tab', function (e) {
YukonView.build({
category:'make:GMC:model:Yukon',
params:'view=xspAll'}
);
});
$('.escalade').on('shown.bs.tab', function (e) {
EscaladeView.build({
'category':'make:Cadillac:model:Escalade',
params:'view=xspAll'});
});
$('.expedition').on('shown.bs.tab', function (e) {
ExpeditionView.build({
category:'make:Ford:model:Expedition',
params:'view=xspAll'});
});
What about those .build() parameters?
As you probably noticed in the snippets above, we didn’t define the keys/category for the views within the control. We could have, but the FVC makes it possible to pass options to the .build() command. This is a huge part of what makes the Flexible View Control so ‘flexible’. More in this in the next blog post!
A Flexible View Control for XPages Part 9 – Using Scroller for Large Views
Posted: May 4, 2020 Filed under: Bootstrap, DataTables, Domino, JavaScript, XPages | Tags: Bootstrap, CSS, DataTables, Domino, JavaScript, XPages 2 CommentsUp to this point, the examples I’ve created to demonstrate the capabilities of the FVC have used fairly small sets of data. In a real-world production scenario there is going to be a need to display datasets of various sizes, including thousands of records. So how does the FVC scale for larger sets of data?
Understanding DataTables
Comprehending what is going on behind the scenes of DataTables is vital to developing a strategy to handle large sets of data efficiently. Similar to XPages, DataTables has a “lifecycle” where a series of events occur in the initialization of the table. Previously, I created a bunch of “pure” DataTables demos, one of which highlights the various phases (callbacks) of the lifecycle (turn on your developer console):
http://demos.xpage.me/xpages/mwlug/datatables.nsf/demoRestLifecycle.xsp
The image above shows browser consoles statements to demonstrate what the lifecycle looks like for a DataTable with 25 records. Take a close look and you’ll see that drawCallback executes multiple times. This means DataTables has drawn the table twice as part of the initialization. A good comparison to this in the XPages lifecycle is the renderResponse phase.
Now, let’s focus on the rowCallback and createdRow callbacks. In this table with 25 rows each of these is called every time DataTables processes a row of data. Normally, you are likely to only use one or the other – both are included here for demonstration purposes. Regardless of which callback you use, the code that resides there will be executed for each row. If your DataTable is replicating the functionality of a Notes View, then you’re likely to have click and double-click events at a minimum.
Now imagine you have a view with a large amount of data – thousands of records, for example. Your rowCallback is now executing THOUSANDS of times, resulting in slower rendering of your DataTable and negatively impacting the user experience. YIKES!
Large Datasets – Notes Views vs. Web Views
Anyone that has used Lotus Notes and Domino for years has been spoiled by having views with thousands (or millions) of records, nicely indexed, and extremely performant as you click on columns to re-sort or search the view based on a key. This is one thing that Notes does really, really well, but sending thousands to millions of rows to a view in a web application can seem like a fool’s errand.
While I certainly continue maintaining large Notes views on the back-end, I use categories, keys, and server-side searching to make it easy for users to target the information they need so only a small subset of information is sent to the client-side web view.
I feel like my magic number is about 5000 records or less. Any more than that and users are waiting too long. Obviously, there are going to be use cases where that is not possible and there are other factors to consider, such as server processing power and bandwidth between the client and server.
Pagers
Paging is one way to deal with large amounts of data and can be turned on with a simple paging: true as part of the initialization options within DataTables. But let’s say you have 4000 records and 50 records show up on each page. This results in 80 pages. Do you want to page through 80 pages of data? Do you want your users to page through 80 pages of data? NO!
Enter Scroller
I’ve said this before in previous posts and presentations but it bears repeating again – the more I use DataTables and the more I have challenging business requirements that at first glance seems like I might have to hack a solution together, ultimately DataTables has a fairly simple way to achieve the desired result. Displaying large amounts of data in a performant way is no different.
DataTables has a plugin called Scroller that does a great job of managing large amounts of data. It does so by only “drawing” the rows that are visible within the scroll body of the table plus extra rows so when the user starts scrolling the table is able to respond quickly. As the user scrolls, the scroller plugin draws more rows. All of the features of DataTables still work as you expect them to – filtering, sorting, etc. Technically, DataTables is using paging functionality behind the scenes to manage the data,
Enabling Scroller in the FVC
The Flexible View Control has the ability to utilize Scroller. Do the following to turn it on:
- Make sure you are loading the Scroller plugin resources. I’m loading the plugin via a CDN in my theme:
<resources>
<styleSheet
href="https://cdn.datatables.net/scroller/2.0.0/css/scroller.dataTables.min.css">
</styleSheet>
</resources>
<resource>
<content-type>application/x-javascript</content-type>
<href>https://cdn.datatables.net/scroller/2.0.0/js/dataTables.scroller.min.js</href>
</resource>
2. You must have showFixedHeader: true on your FVC. Scroller will not work properly without fixed headers being turned on.
3. Set scroller: true in the FVC custom properties.
Demos
This page contains multiple demos that illustrate the dramatic effect scroller has on loading large amounts of data.
Focusing on the first line of the page above, these two sets of console statements highlight the significant difference in loading time between two tables that have the same ~5000 records, one without scroller, one with scroller.
- The first thing we notice is the data is retrieved from the server in the same amount of time in both scenarios.
- In the first console image where scroller is not enabled, every row is being processed by DataTables at initialization, which drastically slows down the table build vs. the second console image, where scroller is enabled.
- Finally, we see a dramatic difference in the build times between the two tables. 11 seconds is a lifetime compared to 1 second and as tables get bigger the 10-second difference will grow in magnitude.
Some Minor Side-Effects
Using scroller does come with a couple of side-effects, but they are fairly minor and shouldn’t have much of an impact.
Since the scroller plugin relies on precise calculations to build the table rows, it forces each row to be the same height. This is really only a problem if you have one column that has one or more records that have extraordinarily long data. Scroller will stretch that column out so all of the data can fit within that row height.
Luckily, the FVC View Definition makes it easy to overcome this. All you need to do is explicitly define a max width for your column and check the “Hide Overflow” box:
The result is your column tries to honor the width you’ve assigned and any text that exceeds that width is truncated with an ellipsis:
The other noticeable side-effect is simply cosmetic and can easily be overridden with CSS. When a table does not have enough data to fill the table body, scroller fills the white space with a background image:
If your users don’t like it, you can use the following CSS to override the background to be whatever you want:
div.dts div.dataTables_scrollBody {
background:#fff;
}
Conclusion
The numbers above are pretty clear – using scroller will greatly improve the performance of the Flexible View Control when your table has a large amount of data and a difference can be seen with as few as 2-300 records. Every view in my application now has scroller enabled.
A Flexible View Control for XPages Part 8 – Putting the 'Flex' in Flexible
Posted: April 15, 2020 Filed under: Bootstrap, DataTables, Domino, Flexbox, JavaScript, jQuery, XPages | Tags: Bootstrap, DataTables, Domino, Flexbox, JavaScript, jQuery, XPages 1 CommentThus far, all of my demonstrations of the Flexible View Control have been centered around starting from scratch and integrating the view control into a mostly blank page, aside from a basic Bootstrap layout. Even the basic Bootstrap layout I’ve been using contains some very important elements that are integral to the control sizing properly, whether you are starting with a blank page or trying to integrate into an existing application.
Enter Flexbox
For years I read about Flexbox and how it can simplify the layout of pages and I always managed to push learning it to the back burner. Once I did all I could think is WHY DIDN’T I LEARN THIS SOONER?!?!? Prior to that, I probably did an embarrassing amount of dynamic element sizing with JavaScript. I can’t stress this enough … Flexbox has fundamentally changed how I approach application layout.
So what exactly is Flexbox?
The
from css-tricks.comFlexbox Layout(Flexible Box) module (a W3C Candidate Recommendation as of October 2017) aims at providing a more efficient way to lay out, align and distribute space among items in a container, even when their size is unknown and/or dynamic (thus the word “flex”).
An important concept to understand is flexible containers are not an “all-in” or “all-out” proposition. You can mix flexed elements with non-flexed elements on the same page, depending on what you’re trying to accomplish.
DataTables and Fixed Headers
Before showing how the FVC integrates Flexbox, a little background. When displaying view data in an application, if the amount of data in the view requires the user to scroll, having fixed headers naturally creates a better user experience. This can be achieved in out-of-the-box DataTables in two ways:
- By adding the parameter ‘scrollY’ to the configuration options with a px value > 0. For example, “scrollY”: “200px”
- By utilizing the DataTables Fixed Header plugin
The pros and cons of each based on my experience are below.
| Method | Pros | Cons |
| scrollY | Built into DT | Requires a hard-coded height value. |
| Fixed Header plugin | Also can create a fixed footer | Requires loading an additional 30k js file, does not handle responsiveness well |
Before using Flexbox for dynamic sizing, the Flexible View Control used the scrollY method to define an initial height and then after the table was rendered, the height of the scroll body would be recomputed so that the table would fit into the parent container. This involved a lot of taking measurements of various elements such as the table offset, header height, filter height, info height, etc. and creating a formula to calculate the correct height needed for the scroll body. It worked great but I really wanted a “cleaner” way to layout the table elements… and I found that with Flexbox.
The Flexible View Control and Fixed Header/Footer
The FVC has a parameter showFixedHeader which is set to true by default. When fixed headers are enabled, the control creates the scrollY option parameter for DataTables at runtime. The value is irrelevant .. the purpose is for DataTables to trigger the dom changes needed to make the table body scrollable:
The key elements here are dataTables_scrollHead, dataTables_scrollBody, and ffDefault. The first two are created by DataTables at initialization. The third, ffDefault is created by the FVC.
Now that we know what the elements are, we need to get them to “flex” by overriding their default styling. The snippet below displays the CSS from the FVC that allows us to accomplish that.
/********************************
DataTables overrides
*********************************/
.dataTables_wrapper {
flex:1;
display:flex;
flex-direction:column;
}
.dataTables_scroll {
flex:1;
display:flex;
flex-direction:column;
}
.dataTables_scrollBody {
flex:1;
flex-basis:auto;
flex-basis:0;
}
.dataTables_scrollHead {
flex:1;
flex-basis: auto;
flex-grow: 0;
position:relative;
}
.dataTables_filter input {
display: inline;
width: 250px;
margin-left: 5px;
}
div.dts {
display: flex !important;
}
/************************/
FIXED FOOTER
/************************/
.ffDefault {
flex:1;
flex-grow:0;
flex-basis:auto;
height:35px; /* Not required */
position:relative;
}
With the CSS above we have the DataTables dom elements configured to flex. But we need to do some more flexin’ to get the layout to flow the way we want. Continuing to work our way up the dom hierarchy, we flex the wrapper that the FVC places around the DataTables dom:
.panelRestViewContainer {
display:flex;
flex-direction:column;
height:auto;
position:relative;
flex:1;
}
Remember the ultimate goal
We want our view to fit in the space being provided by the flexed layout without having to hardcode dimensions or compute dimensions dynamically. This requires the top-most flexed container defining its height either through pixels or through the viewport height (vh). The demos being used throughout this series (such as this) use the following dom hierarchy (simplified for illustration):
<body>
<div class="level0-flex-container">
<div class="level0-flex-item">
Navbar
</div>
<!-- Flexible View Control -->
<div class="panelRestViewContainer">
</div>
</div>
</body>
body, form {
/* very important! */
overflow:hidden;
}
.level0-flex-container {
display:flex;
flex-direction:column;
height:100vh; /* will fill the window viewport */
}
.level0-flex-item {
flex:1;
flex-basis: auto;
flex-grow: 0; /* this element will size to its content */
position:relative;
}
What this all means:
- Body and form elements will not scroll
- Which allows for the flex container to fill the viewport
- The navbar, with flex-grow: 0, will only get as tall as its content
- The Flexible View Control, with flex-grow: 1 (through the shorthand flex:1 property) will expand to fill the remaining empty space in the container.
The end result is our view filling the screen with scrollable content, just as we wanted.
More Layout Demos
The demos below illustrate how easy it is to create several different flexible layouts and to add the FVC to XPage layout controls:
- Starting with a flexible container
- Adding a header
- Adding the Flexible View Control
- Add an action bar
- Add a footer
- Add a left-side navigator
- Add a footer
- Add a right sidebar
- FVC with NO fixed header in a flexible layout
- Adding the Flexible View Control to an Editable Area
- Adding the Flexible View Control to an Application Layout control
A Flexible View Control for XPages Part 7 – Modals & Picklists
Posted: April 6, 2020 Filed under: Bootstrap, DataTables, Domino, JavaScript, jQuery, XPages | Tags: Bootstrap, DataTables, Domino, jQuery, Lotus Notes, Modals, XPages 3 CommentsWhile I intended to get to this blog post eventually, the urgency of doing so was increased due to the following post on StackOverflow:
https://stackoverflow.com/questions/61061571/xpages-flexible-view-control
The OP also reached out to me directly looking for an answer so why not crank out a blog post with the answer?
By combining the Flexible View Control with a Bootstrap modal, you can easily mimic the Lotus Notes Picklist functionality. Getting the control working in a Bootstrap modal requires only a few simple steps, illustrated in this working demo.
Step 1 – Add the modal source to your page
I start with something like this:
<!-- Modal -->
<div class="modal fade picklist" id="myModal" tabindex="-1" role="dialog"
aria-labelledby="myModalLabel">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal"
aria-label="Close">
<span aria-hidden="true">x</span>
</button>
<h4 class="modal-title" id="myModalLabel">Choose a record</h4>
</div>
<div class="modal-body" style="display:flex;">
<!-- place the Flexible View Control here -->
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">
Cancel</button>
<button type="button" class="btn btn-primary">OK</button>
</div>
</div>
</div>
</div>
For the most part, the code above is straight off the Bootstrap site with a few important additions:
- I added the class ‘picklist’ to the ‘modal’ div.
- I add an inline style to ‘modal-body’ of ‘display:flex;’. This is very important since the control uses Flexbox (more on that in a future post).
Step 2 – Add the control to your page
Drop the control in the space bookmarked in the source above and configure the control as you do for a normal view page. Make sure you keep the modal-body intact!
Step 3 – Check your View Definition
It is highly recommended to have the Load on Init property unchecked. You will see why in a moment.
Step 4 – Resize the modal
By default, the Bootstrap modal is pretty small. Of course, the dimensions can be changed with css, but how do you deal with different screen sizes? By adding an event handler to the ‘show’ event of the Bootstrap modal, you can resize the modal to a percentage of available screen space:
<xp:scriptBlock>
<xp:this.value><
In this example above, the view is built during the ‘show’ event, resulting in the table header dimensions not matching up to the actual data rows.
Lucky for us, Bootstrap has another event that we can tap into. You may have noticed it in the screenshot above. The ‘shown’ event fires AFTER the modal has been rendered to the user:
By adding 3 lines of code to the scriptBlock above and tapping into the ‘shown’ event, our table will be built with the proper layout dimensions.
$(".picklist").on('shown.bs.modal', function () {
viewBasic.build();
});
In the snippet above, viewBasic refers to the ‘thisView’ property of the control. Since the ‘Load on Init’ property is unchecked on the View Definition, the view needs to be triggered by its ‘build’ function.
Step 6 – Patch the csjsCCRestView.js file
After completing the steps above, the modal will work fine and the table will load and be fully functional. However, in creating this demo I realized there is an adjustment that needs to be made to the source code. This is due to legacy code that was used when many aspects of the control were being sized dynamically with javascript prior to implementing Flexbox.
The issue is the footer is being calculated based on the window’s dimensions and not the modal’s, resulting in the width of the interior of the modal being wider than the modal container. This will be updated on the github repo, but in the short term you can fix it in your database by updating the buildFooter function in the ccRestView.js file with the code below. The fixes are labeled ‘//MODAL FIX’. A few lines are commented out and a few are altered.
buildFooter : function(o) {
if (o==null) { return; }
if (o==undefined) { return; }
console.log("=== start build footer for " + o.thisView + " ===")
if ($(".ffDefault",$(".panel"+o.thisView)).length > 0) {
// check to see if the info is in the footer.
// if so, set it aside and pick it up later
//$(".ffDefault",$(".panel"+o.thisView)).remove();
// MODAL FIX $(".ffDefault",$(".panel"+o.thisView)).css("max-width",$(".dataTables_scrollBody table",$(".panel"+o.thisView)).outerWidth()+"px")
// MODAL FIX $(".ffDefault",$(".panel"+o.thisView)).css("min-width",$(".dataTables_scrollBody table",$(".panel"+o.thisView)).outerWidth()+"px")
return;
}
var cellCount = $("th",$(".panel"+o.thisView + " " + o.dataTableClass + " thead")[0]);
footerAttachTo = o.viewport == "" ? "body" : o.viewport;
var tableWidth = "100%"; //$(".panel"+o.thisView + " tbody").outerWidth();
var tdCells = [];
var rowOne = $(".panel"+o.thisView + " tbody tr");
//console.log("rowOne length=" + $(rowOne).html())
// create footer cells to match header
for (x=0;x<cellCount.length;x++) {
cell = $("td",rowOne).length == 1 ? $("td",rowOne) : $("td",rowOne)[x]
var paddingLR = ($(cell).outerWidth() - $(cell).width())/2 + "px"; // css("width") //$("td",rowOne).css("padding"); // ($(o.cellCount[x]).outerWidth() - $(o.cellCount[x]).width())/2 + "px";
var border = ($(cell).outerWidth())
tdCells.push("<td data-column='" + o.itemIndexes[x] + "' class='" + o.itemNames[x] + "Foot' style='width:" + $(cell).width() + "px;padding:" + paddingLR + "'> </td>"); //padding-left:" + paddingLR + ";padding-right:" + paddingLR + "
}
var pos = $(footerAttachTo).position();
// get the width of the fixed header so we can apply it to
// the footer
width = $(footerAttachTo).css("width");
footerAtachTo = footerAttachTo != "" ? footerAttachTo : "body";
//console.log("attaching footer to " + footerAttachTo);
var footerHtml = "<div class='ffDefault " + o.ffClass + "' style='width:" + width + "'><table style='width:" + tableWidth + "px' class='fixedFooterTable cell-border'><tfoot><tr>" + tdCells.join("") + "</tr></tfoot></table></div>";
if (o.showFixedHeader) {
width="auto"; // MODAL FIX
var newFooter = $(".dataTables_scroll",$(".panel"+o.thisView)).after("<div class='ffDefault " + o.ffClass + "' style='width:" + width + "'><table style='width:" + tableWidth + "' class='fixedFooterTable cell-border'><tfoot><tr>" + tdCells.join("") + "</tr></tfoot></table></div>");
$(".ffDefault",$(".panel"+o.thisView)).prepend($(".dataTables_info",$(".panel"+o.thisView)))
$(".dataTables_info",$(".panel"+o.thisView)).css({"position":"absolute","padding":"5px","float":"none"})
} else {
width="auto"; // MODAL FIX
var newFooter = $(".panelRestView",$(".panel"+o.thisView)).append("<div class='ffDefault " + o.ffClass + "' style='width:" + width + "'><table style='width:" + tableWidth + "px' class='fixedFooterTable cell-border'><tfoot><tr>" + tdCells.join("") + "</tr></tfoot></table></div>");
}
if (footerAttachTo != "body") {
if (pos) {
left = $(footerAttachTo).css("position") == "relative" ? 0 : pos.left;
}
}
// MODAL FIX $(".ffDefault",$(".panel"+o.thisView)).css("max-width",$(".dataTables_scrollBody table",$(".panel"+o.thisView)).outerWidth()+"px");
// MODAL FIX $(".ffDefault",$(".panel"+o.thisView)).css("min-width",$(".dataTables_scrollBody table",$(".panel"+o.thisView)).outerWidth()+"px");
console.log("=== end build footer for " + o.thisView + " ===")
},
In conclusion
Integrating the Flexible View Control with a Bootstrap modal is easy and provides all of the functionality of DataTables you’d expect – filtering, sorting, etc.
Postscript
For applications where multiple Picklists are needed with different data, you can create a modal custom control with custom properties that can be fed into the view control dynamically. I have one application that has at least 20-25 different Picklists and this method works great.
A Flexible View Control for XPages Part 5 – Processing Selected Rows
Posted: January 13, 2020 Filed under: Bootstrap, Custom Control, DataTables, Domino, JavaScript, jQuery, XPages | Tags: Bootstrap, DataTables, Domino View, jQuery, XPages Leave a commentThe 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:
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.
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:
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
Posted: January 6, 2020 Filed under: Bootstrap, Custom Control, DataTables, Domino, JavaScript, jQuery, XPages | Tags: Bootstrap, Domino, jQuery, XPages 1 CommentRegardless 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:
| Callback | From the DataTables documentation |
|---|---|
| rowCallback | This 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. |
| createdRow | This 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.
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.
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.
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.
| Correct | ccRestView.defaultRowCallback |
| Incorrect | ccRestView.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:
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 3 – Create a Basic View
Posted: December 19, 2019 Filed under: Bootstrap, Custom Control, DataTables, Domino, XPages | Tags: Bootstrap, DataTables, Domino, XPages 2 CommentsSee the demo live
You can see the demo created in this post here. As more demos are added to demonstrate the many features of the Flexible View Control, they too will be available online.
In Parts 1 & 2 we learned about the Fexible View Control and created the configuration we needed to get started with our application.
The Data
Now, we are going to create a view from scratch utilizing a database of 2 million records comprised of used car data.
To get started I need to add the used car database to my configuration document so the View Definition XPage can read the views in this database.
As mentioned in a previous post, and as you can see above, I’m using Bootstrap (3.4) in my application for my UI framework. I’ve already created a navigator custom control:
and an XPage template I’m going to use to create all of my demo pages:
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"
xmlns:xc="http://www.ibm.com/xsp/custom" styleClass=""
style="overflow:hidden">
<xp:this.resources>
<xp:script src="/ssjsCCRestView.jss" clientSide="false"></xp:script>
</xp:this.resources>
<div class="level0-flex-container">
<div class="level0-flex-item">
<xc:ccNav></xc:ccNav>
</div>
<xp:panel styleClass="actionBar" id="panelActionBar" style="">
</xp:panel>
<!-- Drag ccRestView here
-->
</div>
</xp:view>
We’re going to get started with the most basic implementation of the Flexible View Control. In my used car database, I have a view xspPhilPaChevTahoe which shows all of the Chevy Tahoes in Philadelphia, PA. Normally I wouldn’t create a single purpose view like this – it’s being done for demonstration purposes only. In a database of 2M records, this view contains 70 and I’m going to display it with the Flexible View Control.
The View Definition
First, I create a View Definition and point it to the xspPhilPaChevTahoe view in the used car database and select all of the columns.
The REST Service
Next, I create the Rest Service that will be used to fetch the data. We told the View Definition to find the REST service on the restServices XPage. This is where I add mine and give it a path-info that matches the key I used in my View Definition above.
After building the application I do a quick test to make sure I’m getting data from the Rest Service:
The XPage
To create my page where I want to put my view, I create a copy of the XPage template and call it viewBasic. I also add a link to the Open button in my navigator custom control that will open this new XPage.
The Flexible View Control
Now, I’m ready to add the control to my new XPage by dragging it from the custom control palette:
After adding the custom control, take a look at the custom properties by clicking on the control and then clicking the Custom Properties on the Properties tab. There are a lot of properties (some of which have default values) which are integral to making this the “Flexible” View Control for XPages. Some of these properties get passed on to DataTables as the view is constructed.
Most importantly, there are three properties that must be set in order for the control to work properly.
| Property | Description |
| thisView | Unique identifier for this view. This value is used in the internals of the custom control to get a handle on this instance of the view control. |
| viewKey | This value refers to the View Definition that the control will use to get its configuration and location of rest data. |
| dataTableClass | A CSS class name that gets applied to the DataTable and is used to refer to the table programmatically. This value should be unique. |
On my viewBasic XPage I use the following values:
The Results
After saving and building I load my viewBasic XPage in the browser and verify I am getting the results I expect:
What we have now in our browser is a DataTable (v. 1.10.19) and all of the standard front end tools that come baked into that framework, such as filtering, sorting, etc.
Recap
The purpose of this post was to demonstrate how easy it is to quickly add a view to your application using the Flexible View Control for XPages:
- Create a View Definition.
- Create a REST Service (or reuse an existing service) that points to your Domino view.
- Add the custom control to your XPage and point it to your View Definition
Next
In the next post, I’m going to take this simple example and start adding advanced functionality to create more functional views.
Boot your alerts in the … with bootAlert
Posted: February 10, 2015 Filed under: Bootstrap, XPages | Tags: Bootstrap, Custom Controls, jQuery, XPages 7 CommentsUnfortunately, due to the sudden illness and ultimate passing of a family member in the fall, it has been quite a while since I last blogged. Hopefully, this post finds me getting back on the blogging horse to contribute some content to the Xpages/Domino community and bring some ideas I had been kicking around to fruition.
Today I am releasing bootAlert, a simple XPages custom control that allows developers to add configurable, reusable Bootstrap alerts to their apps without having to add any additional plugins. You should already be using Bootstrap/jQuery in your application in order to use this custom control.
For the past few months, in working on our application migration project, I built a configurable Bootstrap alert custom control. I found myself continuing to add features as different needs arose. So, I thought I would release it to the community.
Why bootAlert?
- bootAlert can be triggered from both server and client-side Javascript
- bootAlert can use Font Awesome icons
- bootAlert can be turned into a Growl-like message on-the-fly
- bootAlert is dynamically configurable – one action may require the
'success'class and another may require a'warning'or'danger'notification. One control can be used to display all three. - bootAlert can be customized with css
- Add as many bootAlert controls to your page as you want
bootAlert can be triggered from server-side js with view.postScript()
bootAlert let’s you add Bootstrap Growl messages to your application
Demo
I plan on submitting this as an OpenNtf project, but for now you can find a demo, as well as download bootAlert here
A github repo can be found here.
Getting Started
Getting started with bootAlert is easy. Simply:
- Download the demo database
- Copy the custom control and script library into your application (or copy the contents of the script library into your existsing client-side script library)
- Drag the custom control onto your xpage and populate the
alertNameproperty
<xc:ccBootAlert alertName="alertDemo2" id="ccBootAlertDemo2"></xc:ccBootAlert>
- Call bootAlert from client-side js …
// Client side js
var o = {}
o.title = "Client Side";
o.body = "This alert is being generated by client side javascript";
o.alertType = "danger";
o.alertIcon = "fa-calendar fa-lg"
bootAlert.show('alertDemo2',JSON.stringify(o))
- or call bootAlert from server-side js by putting a value into a requestScope variable and making sure the bootAlert control is part of the partial refresh target:
// Server side js
// This method assumes the alert is part of a partial refresh target
var o = {};
o.title = "Server Side";
o.body = "This alert is being generated from ssjs";
o.alertType = "info";
// The requestScope var name should match the alertName given to the bootAlert control
requestScope.put("alertDemo2",o);
- Finally, you can use view.postScript() to trigger a bootAlert:
// Server side js
// The alert custom control does NOT need to be part of a partial refresh target
// The parameters being passed to bootAlert need to be serialized
var o = {}
o.title = "Server Side > Client Side";
o.body = "This alert is being triggered by client side js called from server side js";
o.alertType = "warning";
o.autoClose = false;
view.postScript("bootAlert.show('alertDemo2'," + toJson(o) + ")");
I hope others find this control as useful as I have in my projects!
XPage.me 