Functions and properties of the XSP object

Stephan Wissel has blogged about some useful functions of XSP obeject. But the list is not complete. So I decided to put the XSP object through my helper JavaScript function listPropsAndFunctions. Below is the list of whatever I could find. I would be updating this list with explanation of whatever properties and functions I am able to find from time to time.

_allowDirtySubmit

_dirty

_dirtyFormId

_eventNameHtmlToWidget

_listeningForDojo

_listeningForDojoOnload

_onLoadListeners

_submitValue

_submitValueSet

Using indexOf method on array in server side JavaScript

Sometime back I was trying to use indexOf method on an Array object in server-side JavaScript (SSJS) code. But it was giving me error that indexOf method is not defined. I also couldn't find this method in help documentation. It was then it struck me that the implementation indexOf method in client side JavaScript itself is a bit fuzzy with Internet Explorer not supporting it. It can be defined using prototype property.

I found a simple solution here which implements the method. Just add the below code snippet to your SSJS code and then you would be able to use indexOf method.

if(!Array.indexOf) {
   Array.prototype.indexOf = function(obj) {
      for(var i=0; i<this.length; i++) {
         if(this[i]==obj) {
            return i;
         }
      }
      return -1;
   }
}

Remember that this would be required for SSJS. For client side JavaScript I would recommend using dojo.indexOf.

Drag out file links from download control to save just like in Gmail

Google adds a lot of interesting features in it products. One of them is dragging a file link in your Gmail on to your desktop (or a folder) to download it. This article on CSS Ninja explains exactly how it is done.

We can also put this feature in our download control so that each file link can be dragged on to your folder to start download without going through save dialog.

Step 1: Identifying the file links in a download control

This is actually pretty simple. XPages by default sets the class name of the file links in download control to xspLinkFileDownload. So all you need to do is to use a simple dojo.query to find all those link and loop through them.

Step 2: Adding attributes to anchor tag

Now you need to set two attributes in the anchor tags of file links - draggable and ondragstart. The draggable attribute needs to be set to true, that's all.

Setting ondragstart requires a bit more details. You need to call event.dataTransfer.setData("DownloadURL", "application/octet-stream:<FILE NAME>:<FILE DOWNLOAD URL>"). Note that while specifying <FILE DOWNLOAD URL> make sure its the complete path start from http://. These attributes can be set using dojo.attr.

So your final JavaScript code looks something like this:

dojo.query(".xspLinkFileDownload").forEach(
    function(node, index, arr) {
        dojo.attr(node, "draggable", "true");
        dojo.attr(node, "ondragstart", "event.dataTransfer.setData('DownloadURL', 'application/octet-stream:" + node.innerText + ":" + node.href + "')");
    }
);

One limitation here is that this only works for Google Chrome. I have put this script block on XSnippets here. Just copy it from there and put it into your XPage.

Getting resources in database as stream in XPages (SSJS / Java)

Some time back I was trying to get the resources in database (to be precise image resource) in my SSJS / Java code. I tried a lot of options like ClassLoader.getResourceAsStream, MyClass.class.getResourceAsStream but no success. Then today while going through the sample database of Extension Library I ran into a piece of code which got the image resource as stream using a single line of code.

var inStream:java.io.InputStream = facesContext.getExternalContext().getResourceAsStream("<RESOURCE NAME>");

As simple as that. In case of Java you would write like this:

InputStream inStream = FacesContext.getCurrentInstance().getExternalContext().getResourceAsStream("<RESOURCE NAME>");

In my tests this worked for getting image resources, file resource and style sheets as streams.

Using dijit.form.CheckBox in check box group in XPages

dijit.form.CheckBox adds a fancy styling to the plain check box, which I love. Adding it to a single check box is pretty straight forward. Just set the dojoType property of the check box to dijit.form.CheckBox. But in case of check box group its not that straight forward.

When a check box group is rendered in browser it is rendered inside <fieldset> tag. So setting the dojoType property doesn't give the desired result. You need to set the dojoType property individually on each of the check boxes in the group. Fortunately, all the check boxes share the same name so they can be targeted using simple dojo.query.

Let's say the name of your check box group is "checkBoxGroup", then just add this script block to your XPage:

<xp:scriptBlock>
<xp:this.value><![CDATA[dojo.query("input[name=\"#{id:checkBoxGroup2}\"]").forEach(
function(node) {
dojo.attr(node, {dojoType: "dijit.form.CheckBox"});
}
)]]></xp:this.value>
</xp:scriptBlock>

Make sure you place this script block after your check box group. Needless to say that you need to add dijit.form.CheckBox in your XPages resources as Dojo module.

You can also extend this technique to set dijit.form.RadioButton in radio button group.

Expand / Collapse particular category in a view in XPages

In XPages, you can expand all / collapse all categories in a view either using the expandLevel property of view control or using view control API. The API technique can further be extended to expand / collapse a particular category in a view. So to expand the code goes like this:

Using extension library component Remote Service

Recently I had some queries on using the extension library component of Remote Service a.k.a. <xe:jsonRpcService>. I posed this question on StackOverflow and Tim Tripcony gave a detailed answer along with some operations where this might be useful. I would strongly suggest going through Tim's answer.

Creating optgroup tag in combo boxes in XPage

Tommy Valand in his blog post pointed to a StackOverflow question to add <optgroup> in combo box in JSF. Using hints from there I was able to devise a way to get <optgroup> in combo box for XPages. Below is the code snippet for the combo box.

Displaying common names of user with Name Picker

I have been trying out Extension Library and I must say I am really impressed with it. One of my favorite control there is Name Picker. The only problem with that is the input control whose value is set by name picker needs to be in edit mode and it shows the selected names in abbreviated format. In one of our application we wanted to show common names and the input control to be non-editable so that user could not play around with values.

Pass server side javascript code to custom control

Some time back I was trying to pass server side javascript to a custom control and then get the code executed from click of a button inside the custom control. With help from Sven Hasselbach I was able to do it. But the problem in that approach was that your entire code has to written in a string literal which denies you the flexibility of the javascript editor. Experimenting a bit more I stumbled on another solution which I think is better.

For custom control property select Type as "Simple Actions > Execute Script".

Installing and running XPages Extension Library in your local machine

I had been hearing a lot about XPages Extension Library and finally got to try it out in XPages code-a-thon held at Mumbai. So I decided to try it on my local machine along with little help from experts on StackOverflow. Its a simple two-step procedure - install extension library and run extension library.

Install XPages Extension Library

First of all get the latest release of extension library from OpenNTF. Unzip the file and find "updateSiteOpenNTF-designer.zip". Unzip it and you will get two folders of "features" & "plugins" and a file "site.xml". In Lotus Notes sidebar, go to My Widgets and select "Options > Configure a Widget from... > Features and Plugin on an Update Site". If you are unable to see My Widgets in your sidebar then click here.

Image URL in XPages using Notes client and browser

In Java Charts, one of the users reported that charts were not visible in Notes client. The charts (images) are basically being generated using the XAgent technique, and you will face the same problem if your image is being generated using XPage.

To understand what exactly is happening lets take help of an example. Say you have XPage with following code snippet which displays an image using javascript formula. (actn005.gif is present in the current database as image resource.)

<xp:image id="image1"><xp:this.url><![CDATA[#{javascript:"actn005.gif"}]]></xp:this.url></xp:image>

New property in XPages - Show read only as disabled

Some time back I had blogged about creating a read only edit box in XPage. But with Lotus Notes 8.5.3 there is a new property which does this for you - Show read only as disabled.

View XPage source code in browser

Karthikeyan A had written in his blog about viewing your XPage source code in browser. You just needed to add a plus (+) sign in front of your XPage URL and it would show you the source in the browser. Tommy Valand confirmed that this bug was fixed in Domino 8.5.1 FP1.

But recently, while playing around with XPages I found out that there is yet another way where you can get the source code in browser. Open the XPages view in Domino Designer and go to "Properties > Document Ids". There you will find Note UNID. Copy it.

Now create URL as http://<SERVER NAME>/<DATABASE PATH>/<Note UNID>. For e.g. http://myserver/mydatabase.nsf/14C2FD8F53CD42204925791600131817 and run it. You will find your XPage source code in the browser if you are using IE else you will be prompted to download a file which would contain it. I tried it on Domino 8.5.1 FP2.

Of course you need to know the Note UNID of XPage for this, which might not be possible for an end user... PHEW!

Add custom icon to dojo button in XPages

Adding icon to a dojo button is pretty simple. Jut set the dojo type to dijit.form.Button and add a dojo attribute named iconClass with value dijitEditorIcon dijitEditorIconCut.

And you get something like this:

But what if you want your own custom icon to appear on the button? The Dojo Themes and Theming Documentation explains about using custom icons. First of all import the icon image in your database. Now create a style sheet with following CSS class.

Declaring global variable in XPage using dataContexts

While working on a XPages application I required a database object to be initialized and then used in various controls in XPage. I wanted to initialize the object only once then use it again and again. With some experimenting I found out that if I put the initialization code in beforePageLoad, afterPageLoad or beforeRenderResponse I was able to access the object from anywhere in XPage. But I wasn't sure that whether this was the correct way or the objects would get automatically garbage collected. So I posted this question on XPages forum.

Paul S. Withers suggested me to use dataContexts. You can find them in All Properties tab of XPages properties inside data section.

Getting methods, fields, constructors for XPage Java classes

In my previous blog I was able to find out which Java classes were represented by global objects & functions of SSJS. For e.g. facesContext.getExternalContext() returns object of com.ibm.xsp.domino.context.DominoExternalContext. But what methods, fields, etc. are available in that class? To get those you use the Reflection API (java.lang.reflect package) in Java via which we can find out the methods, fields, etc in a class. Using this I built a small XPage which can explore these classes. Here’s how it looks:

Double exclamation / bang (!!) in Lotus Notes

Double bang or double exclamation (!!) is an interesting thing in Lotus Notes. It basically is an internal network separator to Notes¹ used to separate the server name and database path. No wonder in older release of Lotus Notes, launching attachments which have double exclamation marks in file name would crash Notes client. Also if you try to attach a file (either from Notes client, web or XPages) with double exclamation marks in its name, then the part preceding the double exclamation marks is removed from the attached file name. So if your name of file is file!!name.txt then after attaching, your file name would be name.txt. Even using the EmbedObject method in NotesRichTextItem class attaches the file in same way.

I used it myself when I wanted to open a specific frameset in a different database. Basically where ever you find the @ button in properties, there you can specify the server & database concatenated with double exclamation marks.

Also you use it in Show Database command at the Domino server console to display database and view information on a different server. David Leedy found out that while binding XPages to external databases you need to use double exclamation. Even in the C API function of W32_NSFDbOpen(dbpath$, hdb&) you specify the dbpath$ as <Server>!!<Database path>.

Update 8 Jan 2012: Starting with Notes and Domino 8.5.3 you can set up Domino to preload XPage applications using the notes.ini entry of XPagesPreloadDB, where you specify the server and database name concatenated with double exclamation. And yes, it is present in the final release of the 8.5.3.

---

1. Lotus Notes and Domino 5.0.5 Release Notes (Pg 116)

"loaded" vs "rendered" in XPages

I couldn’t find many resources on the exact difference between loaded and rendered property available in XPage controls except for this blog by Thiyagarajan.

When you hover your mouse over loaded property it says – “Specifies whether or not the control should be created when the page is loaded.” while for rendered it says – “Indicates whether or not control should be displayed or processed on any subsequent form submission.”. Enabling the properties (exclusively) does not generate the control in the web page. But this is where the similarity ends. It was after a discussion with Sven Hasselbach on XPages forum, I understood the usage of these properties.

Create two computed fields cfLoaded and cfRendered with loaded & rendered property set to false in them respectively. Now add another computed field with following code:

Accessing XPages global objects in Java

Update 24-Dec-2011: Added method to access session and database.

Update 10-Mar-2012: Updated the view object as it was pointing to a super class. Thanks to Tom pointing that one out.

Update 22-May-2012: Rectified the code to get viewScope. Thanks to Jens Winkelmann for pointing it out.

Update 16-Mar-2013: Added link to get getComponent equivalent in Java.

Tim Tripcony in his reply to one of the questions in the Notes/Domino XPages development forum had suggested using Java over SSJS to improve XPages performance. He basically said – “...Minimize the use of SSJS (server-side JavaScript). Every time any SSJS expression is evaluated, Domino parses the expression in realtime into an abstract syntax tree, then runs Java code that is a rough approximation of how the JavaScript specification states that code matching the detected syntax should run. The more you move your logic directly into true Java classes, the less expensive it is to execute, so it runs faster...”

So I started thinking about how can we access various XPages Global Objects like – facesContext, sessionScope, context, etc. from Java classes.

Well... here's how we can access it: