1. Open the XPage that you wish to add the Dojo Progress Bar  to in the XSP editor.
2. Select the XPage and on the All Properties tab, expand the basics category.
3. Select resources and click on the Add icon. Select xp:dojoModule from the list and enter dijit.ProgressBar as the value for the name field of this resource. These steps are outlined in Figure 1.



Figure 1: Adding a Dojo module to an XPage



4. Remain in the All Properties tab, within the basics category. Set both the dojoParseOnload and the dojoTheme property values to true.
5. Change to the source tab on the XSP editor and copy in the following code wherever you want the progress bar to be placed:

6. Save the XPage and view the outcome in a web browser. A Dojo Progress Bar, as shown in Figure 2, now appears on the XPage.

           
                   Figure 2: A Dojo progress bar widget

1. Open the XPage that allows users to enter information into a new Domino Document. Make sure that one of the available fields is setup to accept a numeric value. In this example, the XPage uses an Edit Box control to accept a value for the number of sales for a business in one day.
2. As in the previous example, set the dojoTheme property value to true and add a Dojo module resource to the XPage with dijit.form.NumberSpinner as the name value.
3. Use an Output Script control to attach the Dojo Number Spinner widget to the Edit Box. (To add an Output Script control, select Other.... on the controls palette, expand the Other Controls category and select Output Script.  Click OK.).
4. Select the control in the XSP editor and on the properties tab, expand data and compute the value field. As shown in Figure 3, select Custom in the language drop down menu and enter the following in the script editor:

 new dijit.form.NumberSpinner({name:"#{id:numSales}",
value:50, smallDelta:1, constraints:{min:0,places:0}}, 

XSP.getElementById("#{id:numSales}")); 

This code invokes the constructor of the Dojo Number Spinner widget. The first parameter is an object, the properties of which map to the properties of the Dojo widget. The second parameter is the HTML DOM object node associated with the Edit Box control used to enter the number of sales.  “numSales” is the name of this Edit Box  and #{id:numSales} is used to get its client ID value. Saving the XPage and viewing it in a web browser, the Dojo Number Spinner widget should now appear instead of the Edit Box (see Figure 4). The value selected on this Dojo widget will be the number saved into the Domino Document when the data is submitted.

Figure 4: A Dojo Number Spinner widget on an XPage

In this example, a default value of 50 is specified for the Number Spinner widget. Therefore if a user uses the same XPage to open the Domino Document just created, the value displayed for the number of sales field will be 50. The example can be further enhanced so that if a user views a stored Domino Document, the value displayed in this field is the previously stored value. To achieve this, the value for the Number Spinner needs to be dynamically calculated. Replacing the value of the Output Script control above with the following code accomplishes this:

 var myvalue
= "#{javascript: 

var value; 

if(getComponent("numSales").getValue() != null){ 

    value = getComponent("numSales").getValue().intValue();


}else{ 

    value = 50; 

}                    
            

return value.toFixed(0);}"; 
new dijit.form.NumberSpinner({name:"#{id:numSales}",
value:myvalue,
smallDelta:1, constraints:{min:0,places:0}}, 
XSP.getElementById("#{id:numSales}"));

Figure 5: Creating and editing a document that uses a Number Spinner widget.

XSPClientDojo

 XSP.getElementById("#{id:numSales}")

 

  var name =
 XSP.getElementById("#{id:name}"); 

    var nameValue = name.value; 

    var nameType = name.type; 

    var nameDisabled = name.disabled; 

XSP.attachValidator("#{id:age}",null,new
XSP.IntConverter("Incorrect age value entered. Please enter
an integer")); 

XSP.addOnLoad( 

function addAgeValidator() { 

XSP.attachValidator("#{id:age}",null,new XSP.IntConverter("Incorrect
age value entered. Please enter an integer")); 

} 

); 

When the XPage is displayed through a web browser, only integer values will be accepted for the age field as shown in Figure 6.

This example can be further expanded to make age a required field on the XPage and to limit the age value entered to a specified range (see Figure 7). The attachValidator function call in this case would be:

XSP.attachValidator("#{id:age}",
new XSP.RequiredValidator("You must enter an age"), 

 new XSP.IntConverter("Incorrect value entered, please enter
an integer"), 

 new XSP.NumberRangeValidator(18, 65, "Incorrect age value
entered. Age must be between 18 and 65")); 

It is also possible to contribute custom convertors and validators and apply them using the XSP object. The following example shows how to define a new validator and apply it to an XPage control. In this example, the user is asked to enter and submit their employee number through an XPage. A new validator is defined to verify that the employee number entered is valid.

Firstly, define the employeeIDValidator function as outlined in the following steps and shown in Figure 8.

• In the Application Navigator, expand the Code resources.
• Double Click on Script Libraries and select New JavaScript Library. Type a name for the new JavaScript library e.g. myValidators.
• Copy the following function into the script editor and save the file.

var
EmployeeIDValidator = function EmployeeIDValidator(message){ 

this.validate = function xeidv_v(clientId,value){ 

    if(typeof value =="string"){ 

            var len = value.length; 

             if(len != 8 || !XSP.startsWith(value,"P")){


                    XSP.validationError(clientId,message);


                    return
false; 

            } 

    } 

    return true; 

} 

} 

This is a very basic validation rule which requires the employee ID entered to start with “P” and to be 8 characters long. To utilize this function, the new JavaScript library needs to be added as a resource to the XPage which contains the employee ID field and then attach the new validator to the employee ID field.

• Open the XPage which contains the employee ID field. Select the XPage and on the Resources tab, click Add Script Library.
• Select the Script library which contains the employeeIDValidator. Its functions can now be used in controls on the current XPage.
• Add an Output Script control to the XPage as before and enter the following code as its value

XSP.addOnLoad(


function addEmployeeIDValidator() { 

   XSP.attachValidator("#{id:employeeID}",new XSP.RequiredValidator("You
must enter an employee number"), null, 

                    
     new XSP.EmployeeIDValidator(“Error, incorrect employee
number entered")); 

   } 

); 

This specifies that the employee ID field is required and that it will not be submitted unless it passes the validation criteria specified in the EmployeeIDValidator function. Note a convertor is not applied in this case, since the employee ID is treated as a string. Figure 9 shows the outcome of this code sample.

Figure 9: The Employee Number field is required and it must satisfy the validation criteria from the EmployeeIDValidator function

The XSP object also provides a useful logging facility. Using this, messages can be output to a logging window as an XPage is navigated. This can be used to track user actions or to output status messages and is a valuable resource for testing and debugging. The following function call results in the logging window shown in Figure 10.

XSP.log("Submit button
clicked with values: Company Name: " 

  +XSP.getElementById("#{id:topic}").value+" and #Sales:
"+XSP.getElementById("#{id:numSales}").value); 

Summary

Sample Code

 "1.0"
encoding="UTF-8"?>


"http://www.ibm.com/xsp/core"
dojoTheme="true"


dojoParseOnLoad="true"
 







    "dijit.ProgressBar"
 










    

    
"dijit.ProgressBar"
style="width:300px"


            jsId="jsProgress"
id="downloadProgress"
 


    


    

    "Start"
id="button1"
 


            "onclick"
submit="false"
 


                    


                    
       "text/javascript"
 


                    
               


                    
               
                    
                Split up bar
into 7% segments 

                    
               numParts = Math.floor(100/7);


                    
               jsProgress.update({
maximum: numParts, progress:0 }); 

                    
               for (var i=0; i<=numParts;
i++){ 

                    
                     
     This plays update({progress:0}) at 1nn milliseconds, 

                    
                     
    update({progress:1}) at 2nn milliseconds, etc. 

                    
                     
     

                    
                     
    setTimeout("jsProgress.update({ progress: " + i
+ " })", 

                    
                     
                     
(i+1)*100 + Math.floor(Math.random()*100)); 

                    
               } 

                    
               ]]>