Passing Parameters to SSJS from a Client-side partialRefreshGet()

partialRefreshGet() is a handy method of the client-side XSP object that can be used to trigger a partial refresh from client-side JavaScript. In this post, I’ll show how you can pass parameters for SSJS to read during the refresh, which allows you to send information to the server-side code without submitting a less efficient POST request.

This is an interesting tip that I picked up from the Mastering XPages book. I’ve used partialRefreshGet() numerous times, but I wasn’t familiar with the params property previously.

Here’s an example of a normal partialRefreshGet() call:

XSP.partialRefreshGet("#{id:myComputedText}", {});

The first parameter is the target for the partial refresh. This is client-side JavaScript, so it needs to use the #{id: } syntax to compute the client-side ID of the refresh target.

The second parameter is an object that have up to 4 properties: onStart, onError, onComplete, and params. Here’s an example of the structure when using all of the options (although none are required):

XSP.partialRefreshGet("#{id:myComputedText}",
 {
    params: paramObject,
    onStart: startHandler,
    onError: errorHandler,
    onComplete: completeHandler

 });

The params Property and the param Object

The params property takes an object with parameters to send with the AJAX call. The Mastering XPages book says that the params property “gets expanded, encoded, and appended to the GET request URI that is invoked by the underlying AJAX handler.”

This gives you an easy way to pass information from client-side JS to SSJS and then access it via the param object in SSJS, which provides access to all URL parameters.

The SSJS that’s intended to read the parameters passed by a partialRefreshGet much be within the specified refresh target in order to read the parameters during the refresh.

Simple Example

If I have a computedText component with this value:

if (param.containsKey('parameter1')) {
  return param.parameter1 + ' ' + param.parameter2;
}

It will not return anything when the page first loads.

If I add a button with this client-side JavaScript…

XSP.partialRefreshGet("#{id:computedField2}", 
  {
    params:{"parameter1":"1", "parameter2":"2"}
  });

… it will display 1(space)2 after I click the button, because it is the refresh target and it can read URL parameters sent during the refresh.

This is a very efficient way to send data to a server-side script.

Note: If you pass a parameter that already exists in the URL, it does not overwrite the URL parameter value — it turns the value into a string separated by a comma and a space between the values.