Wait! Hold on… Using a preloader in XPages to warn the user stuff is happening and (s)he should have some patience

preloadI have an XPages application that is querying a DB2 table via JDBC, and it takes a couple of seconds before it returns some data I display in a nice grid after a partial update.

The thing is: if the user should wait a couple of seconds, he should be warned, so that he knows something is going on.  First of all, it’s nice, user friendly and polite.  Secondly, you don’t want your user to get all experimental and starting to click all over the place in order to get some feedback.  Because he will, eventually  ;-).

But how?

  1.  You need a preloader image first.  Try to match the image of your choice with your theme or layout.  A good starting point to create a preloader is http://ajaxload.info/ but there are probably tons of other sites with such preloader generators.  I created this tiny “waiter”.
  2. Add the image as an image control to your XPage where you want it to appear.
  3. Of course, you don’t want to show it all the time (or your user might get hypnotized by it); you want to hide it to start.  You do this by adding a div with visibility hidden.  OR you can call the clientside id of the image and hide it directly. The source code may look like this:
    <div id="wait" style="visibility:hidden;margin:0;padding:0;height:0">
    <xp:image url="/ajax-loader.gif" id="image3"></xp:image>
  4. You want to show the image when your SSJS is called and hide it once your SSJS is finished.  A good thing we have the onStart and onComplete events in the Event handler of a control.  You can access these by opening the outline tree for the control where your SSJS is executed (in my example a radio button) and open the Event handler below it.  It’s a bit hidden.event handler

    If you then open the Properties for this, onStart and onComplete are listed there.

  5. onStart you enter the (client) JS:
    dojo.byId("wait").style.visibility = "visible";
  6. onComplete you enter the (client) JS:
    dojo.byId("wait").style.visibility = "hidden";



  1. If you have even longer running processes and you want to provide the user with more information (in the form of a progress bar or progress message), then you might consider this demo I created some time ago: http://linqed.eu/?p=174

  2. In most cases there is no need to hide the gif. Just make sure the gif is hidden by default and have it inside the object you refresh will hide it automatically after refresh

    • Thomas, you’re absolutely right, thanks for the remark!


Submit a Comment

Your email address will not be published. Required fields are marked *

+ 13 = 14

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>