Finding your XPage generated elements byId client side

Ok so when you create your fields or divs in XPage and you give them a sane Id, when XPage then renders them you get ids like:


I do see why it is necessary, since you can have multiple forms in one XPage and it would be impossible to keep them apart if fields did not have unique names.

But what if you have your JavaScript libraries which uses functions like getElementById or if you are smarter than that and uses the dojo.byId which is browser independent.

There is no way using the client side syntax (#{id:comboBox}) you can use in the XPage and custom controls.

At the moment I see two approaches, the first is to create a global variable which is then used in the JavaScript library. This method is described here!

The second method is to use dojo.query().

dojo.query can be used to “query” the DOM tree, a really powerful function which is well worth digging into.

But in this case we will use it to find our html element by querying for the elements where id ends with the id we are looking for.

The syntax would be dojo.query(“[id$=’:CompanyName’]”).

Let’s take it apart. The brackets means we are searching for a tag with the name “id” ([id$=’…), which value ends with our search string, ‘$=’ stands for ends with.

The search string begins with a colon since we want to be sure we do not get fields with ids like ‘FirstCompanyName’, since they also ends with ‘CompanyName’.

The result will be an array of html elements, with multiple entries if more than one element id ends with ‘:CompanyName’, which very well may be the case, see when to use section below.

So when do we use which one:

The first method is preferred if you have multiple forms as data sources for your fields or when you cannot be absolutely sure that the ids are unique over all elements you need to use in your JavaScript library!

In all other cases the second method should work fine.

So now you have to rewrite all your JavaScript libraries! Yes you do and when you do that try to skip everything which takes an id string as a parameter, rewrite it to use elements or better to take both types as an argument.

Function doSomthingWithElement(elmnt){
 if(typeof(elmnt) === ‘string’){
   elmnt = dojo.byId(elmnt);
 // use the element

What you also can do is to replace the XSP objects method getElementById with your own implantation of it using the dojo.query().

Either put the code inside addOnLoad in the client side XPage event onClientLoad or better put the code below in to a JavaScript library which is added as a resource into the XPage. Be sure to put in the JavaScript library early in the code so that it is loaded before used.

The XSP object is created by Domino server and contains different convenient functions like a getElementsById which actually only is a wrapper around dojo.byId()!

 dojo.mixin(XSP, {
   getElementById: function(idName){
     var result = dojo.byId(idName);
     if (!result){
       result = dojo.query("[id$=':" + idName + "']");
       if (result){
         result = result[0];
     return result;

I’ll try to explain what happens: First the dojo.addOnLoad() will run the function given as a parameter when the page has loaded in the client. Then by using dojos mixin the script replaces the object literal entry for “getElementById” with the code given as a second parameter. The code itself doing the magic first tries to find the element the classic way by using dojo.byId(). In this way we do not break the previous functionality. If nothing is found it tries to find the element by using the dojo.query() method described above.

So now if you want to find an element where the id has been replaced by the Domino XPage rendering engine you can use XSP.getElementById(‘CompanyName’) as you hopefully are used to.

An alternativ can be to mixin xspById() into dojo.

If someone knows of a function which can be used instead in custom JavaScript libraries please tell me since I’ve been searching a lot for a solution to this problem.


@URLEncode and the JavaScript equivalent!

JavaScript has many different encoding function with different approaches. Some of them does not encode all special characters.
escape() – does not encode: *@-_+./
encodeURI() – Does not encode: ,/?:@&=+$#

But encodeURIComponent() encodes all special characters! Link to W3SChool

@URLEncode(“ISO-8859-1;”,/?:@&=+$#”) will encode to the following string: “%2C%2F%3F%3A%40%26%3D%2B%24%23%22”
Which means that @URLEncode is similar to encodeURIComponent()!

But be warned @URLEncode/@URLDecode in standard uses “Domino” as decode type. “Domino” uses UTF-8 char set which will not work together with standard encoding on a  web page togehter with the JavaScript encode and decode functions . To work well with international characters use “ISO-8859-1”.

When it comes to encoding keep in mind that the decodeURI() function will skip decoding escaped characters which encodeURI() will not encode (at least in Firefox). @URLDecode and the JavaScript functions unescape() and decodeURIComponent() will decode all % escaped characters.

So decoding the string above will give the following result:

unescape() => ,/?:@&=+$#”
decodeURI() => %2C%2F%3F%3A%40%26%3D%2B%24%23″
decodeURIComponent() => ,/?:@&=+$#”

@URLDecode will decode anything encoded with any of the JavaScript alternatives correctly.
@URLEncode will only be correctly encoded by the JavaScript functions unescape() and decodeURIComponent().

JavaScript in Domino – Unobtrusive JavaScript and mandatory fields

Finally I found a name for it. Chris Blatnick named it on his blog Interface Matters.

The technique was presented to me by Patrick Kwinten a while back. He as also blogged about it here.

Since then I find the technique really appealing since it in my opinion makes the coding in domino a lot cleaner. You can create a javascript library and put all the event management in there instead of having it in forms and subforms. Personally it goes along very well with my belief in separating style and content.

Here’s an example how to dynamically change the behavior on mandatory fields. In this case it uses css to show a red border around the field which is mandatory and is missing a value. I have not included the css here. But it is basic knowledge so it should not be hard to create one your self.

This example requires prototype.js

First a function is used to get a Hash of mandatory fields. In this case the mandatory fields are different depending of a previous selection in a field. The selections are “IBAN”, “US-ABA”, “SE-BG”…
There is a function for this so that the source of the information easily can be changed. Later its easy to implement a configuration document and fetch the information via ajax.

function getMandatoryFields(){

var mandatoryFields = {

"Tx_BankID", "Tx_AccountNumber"]},


"DE-BLZ":{"mandatory":["Tx_BankName", "Tx_BankID","Tx_AccountNumber"]},
"Tx_BankID", "Tx_AccountNumber"]}};

return mandatoryFields;


Here’s the code:
Function refreshMandatoryBankInfo(accountType, mandatoryFields){

//Get the list of fields to the specific account type
mandatoryList = mandatoryFields[accountType].mandatory;

//This is not very modular for now.
var allFields = ["Tx_Recipient","Tx_BankName","Tx_BankID","Tx_AccountNumber"];

//Now we reset all fields. Removing onFocus and onBlur events and styles for mandatory fields
for (var i = 0; i < allFields.length; i++){



//Go through all mandatory fields and assign an onFocus and onBlur event.
for (var i = 0; i < mandatoryList.length; i++){

Event.observe($(mandatoryList[i]), 'focus', mandatoryOnFocusEvent);
Event.observe($(mandatoryList[i]), 'blur', mandatoryOnBlurEvent);

//Set initial class for the field.
if (IsEmpty($(mandatoryList[i]))){







//Function to check if field is empty
function IsEmpty(aTextField) {

if ((aTextField.value.length==0) || (aTextField.value==null)){

return true;

}else {

return false;



//The onFocus function
function mandatoryOnFocusEvent(e){

//Find source element (field which event was triggered) read more about the technique here. The difference is due to different handling in ie and mozilla.
if (typeof e == undefined) {

var e = window.event;

var source;
if (typeof != undefined) {

source =;

} else if (typeof e.srcElement != undefined) {

source = e.srcElement;

} else {

//Since it is a target type we do not handle, exit function
return true;


//Set class for active field (You can define a special style to show in which field the cursor is placed).


function mandatoryOnBlurEvent(e){

if (typeof e == undefined) {

var e = window.event;

var source;
if (typeof != undefined) {

source =;

} else if (typeof e.srcElement != undefined) {

source = e.srcElement;

} else {

return true;


//Remove class for active field

//Different handle for text and textarea and a select object
if (source.type =="text" || source.type =="textarea"){

if (IsEmpty(source)){


} else{


source.value = Trim(source.value);

//Check if select statement is empty. Select-one is for on selection if you have a multiple selection object test for select-multiple. The test if it is empty may then have to be rewritten to work.
}else if (source.type =="select-one"){

if(source.options[source.selectedIndex].text == ""){







How the function is called:
refreshMandatoryBankInfo($F("Tx_AccountType"), getMandatoryFields());

Easy implementation of multiple configurable global stylesheets

The concept is to have a profile document with a multi value field containing the stylsheet path. First entry has the lowest priority the last the highest priority.

First create a profile document and a multi value field
In my example the profile form is named “(DbSetup)” and the field is named “globalCSS”.

In the Form you add the following code into to the “HTML Head Content” form object. Explanation follows.

startTagCSS := "<link rel=\"stylesheet\" type=\"text/css\" href=\"";
endTagCSS := "\">";
s := @Name([CN]; @ServerName);
@If( s= "" ; varGlobalCSS:="css/global.css";varGlobalCSS:=@GetProfileField("(DbSetup)"; "GlobalCSS") );
@Implode((startTagCSS) + varGlobalCSS + (endTagCSS);@NewLine) + @NewLine

First I define the start and end tags. I then try to find out if it runs local or on a server. If it is local it gets the css path from the local application it self, otherwise it gets it from the profile document. Needed that to be able to debug without network access.

Then, on each entry in the GlobalCSS field, the start and end tag is added in front and back of the path. By using @Implode and @NewLine each entry will be separated with a new line. Last but not least I add an extra new line after. To make it look more readable.

If the field GlobalCSS contains [”,, we would get the following in the “<head>” tag on the web page.

<link rel="stylesheet" type="text/css" href="">
<link rel="stylesheet" type="text/css" href="">
<link rel="stylesheet" type="text/css" href="">

This is only for absolute paths, since the relative path changes depending on if the document is new or already exists.
In this case each entry has to be tested for the existence of http or “//” in the beginning of the path and add “../” in the beginning if it is not a new document. Hint use @IsNewDoc in combination with @Transform.

Logout button

When using session based authentication on the web, it is possible to create a logout button in a simple way.

Just append ?logout to the URL path. By using redirectto it is possible to forward the user to a logout page. Only catch, since you then are logged-out, the page you want to show must be available for the user anonymous.

Just create a button with the the following syntax in the onClick event: + "?logout&redirectto=//" + logoutURI ,"_self")

“_self” opens the url in the current window.

If you want to redirect to the same application (logout and get the login dialog directly) don’t forget to end logoutURI with a slash “/”.

This would logout and direct you to the login page again:"//