Meet the XSP object

Look at the source code of any XPage in your browser (you are are using Firebug, are you? *) and you will find numerous invocations to the XSP object. This object sits on top of Dojo (at least for now) and is one of the reasons why type-ahead and partial refresh work so easily in XPages. Having a closer look at the object reveals a wealth of possibilities. A good starting point is an article by Teresa Monahan (one of our code goddesses in the IBM Dublin Software lab) on the Domino Designer WIKI. To get a deeper look simply examine the source. You can find the file in [Your Notes/Domino data directory]/domino/js/[DojoVersion]/ibm/xsp/widget/layout/XSPClientDojo.js.uncompressed.js. Let us have a look at some of the interesting functions and possibilities. XSP has a strong heritage in Dojo, but IBM might provide alternate implementations for specific needs in future. To get a head start in Dojo check out Mastering Dojo , Dojo: The Definitive Guide , Practical Dojo Projects or the other Dojo books . But back to XSP:

• XSP.addOnLoad( listener )
  Adds a function "listener" to the code that is executed when loading a page.
• XSP.attachClientScript(targetClientId, _event, clientScript), xsp.attachClientFunction(targetClientId, _event, clientSideScriptName)
  Attaches a function to a client element for a specific event. If the function exists use attachClientFunction. If the code is inside the variable "clientScript" use attachClientScript
• XSP.setSubmitValue(value)
  Overwrites what a submission is sending back to the server. Use with caution!
• XSP.canSubmit()
  Returns true/false. If a page has been recently submitted it returns false. Good way to prevent submit button double click hazards. To manually set it to true call XSP.allowSubmit()
• XSP.addPreSubmitListener(formid, listener, clientId, scriptid)
  Adds a function (the listener) that runs before the form (formid) is submitted. Great way to run cleanup code in custom controls to make them self contained. Also a good way to have code run only for a specific button (clientid) rather than onsubmit in any case. The scriptid helps to check if the listener has been loaded already (e.g. on partial page refresh) to avoid duplicate loads. If listener returns false submission does not happen. Runs after the client side validators.
• XSP.addQuerySubmitListener(formId, listener, clientId, scriptId)
  Same as above but runs before the validators
• XSP.alert(message), XSP.error(message), XSP.confirm(question)
  Currently this are wrappers around alert() and dojo.confirm(). Using this functions has the advantage of instant beautifications once the XSP object gets upgraded
• XSP.attachValidator(clientId, validator, converter)
  Allows to attach a validator to a client object. The better way to validate than writing code in the onSubmit event. Admittingly a little more complex. The function warrants its own blog entry (stay tuned)
• XSP.validateAllFields(true|false)
  Default for this is false. When set to true all client side validation is executed not only all until the first error. You will get a number of prompts. Makes sense with an overwritten validation function, but that's a story for another time.
• XSP.attachEvent(clientId, targetClientId, _event, clientSideScriptName, submit, valmode, execId)
  Attaches events to client side elements. The clientId is the element, the targetClientId the target for a partial refresh, _event the event to attach. More in a future blog entry.
• XSP.fireEvent(evt, clientId, targetId, clientSideScriptName, submit, valmode, execId)
  Allows to trigger an event script.
• XSP.attachPartial(clientId, targetId, execId, eventName, scriptName, valmode, refreshId, onStart, onComplete, onError)
  Attaches events to client side elements. The clientId is the element, the targetId the target for a partial refresh, eventName the event to attach. on(Start|Complete|Error) the functions to run locally around the ajax event. More in a future blog entry.
• XSP.partialRefreshGet(refreshId, options), XSP.partialRefreshPost(refreshId, options)
  Triggers a partial refresh manually. For POST the refreshId must point to a form, for get it can be any element with a partial refresh defines. The options object is quite interesting to examine. Includes parameters and functions to execute in the life cycle.
• XSP.attachDirtyListener(clientId)
  Listen to a specific field. If it changes consider the form "dirty". (Persil to the rescue). Use XSP.attachDirtyUnloadListener(message) to set a message. Typically you use that for "Your form has changed, do you really want to navigate away" type of messages.
• XSP.trim(string), XSP.startsWith(string, seachString), XSP.endsWith(string, searchString)
  Convenience functions for string stuff.
• XSP.serialize(object)
  Takes an JavaScript object and returns a textual representation. Currently JSON, but might change.
• XSP.toJson(object), XSP.fromJson(string)
  Convert data from/to JSON format.
• XSP.log(message)
  Send a message to the local log. Used for debug (mostly)

This is just an extract. I probably will cover usage details in future posts. You will have fun exploring more of it. As usual: YMMV

*Remark: Regardless what target environment environment you develop for: IE6 , IE7, IE8, IE9, FF2 , FF3, FF4, Opera, WebKit (The core of the browsers in iPhone, iTouch, iPad, Android, Chrome and Safari) or others, you do want to develop your XPages application using Firefox. The simple reasons are Firebug and Medusa.