Documentation‎ > ‎WebSphere Portal‎ > ‎

Client side Programming model

Client side Model Sample Portlet

This article demonstrates how simple it is to build a portlet using new client side programming model introduced in WebSphere Portal 6.1. This article has attachment of sample war file that uses the client side programming model. The JavaScript Client Side API is a new convenience API introduced in WebSphere Portal 6.1. You don't really need a lot of Java/J2EE to build portlets using this API. The sample shows how you can access the portlet preferences using these APIs.

The first and most important thing to understand is that the client side model is IBM specific API provided as a way to simplify programming portlets. If you go through the JSR 286 portlet spec, you probably won't notice any such client side API. The API is meant to provide a simple way to create portlets without the need of a deep Java expertise. Because all the processing happens on the client, you can see a significant improvement in the overall performance and user experience for your portlets.

The sample discussed here is a bare bones example that simply introduces this new programming model. It has only one text input item and one button. When the button is activated (clicked), the value in the text input is added to the portlet preferences with the name "Custom1". If you click the button again, the "Custom1" preference value is replaced with whatever the value is in the text input. Even though portlet preferences (persistant data) are stored on the server, there is no server side call; only client side JS calls. The server side updates happen under the covers in a transparent way. You will also notice that the API objects are package in *.ibm.* packages. The following are the five simple steps to complete this sample:

  1. Reference the tag library to be used


  2. Initialize the client side programming model

    <portlet-client-model:require module="ibm.portal.xml.*" />
    <portlet-client-model:require module="ibm.portal.portlet.*" />

    The most important thing the above code does is create a variable portletWindowID that can be used in the JSP.
  3. Create a JavaScript Object/code specific to your portlets. Typically this is coded in a separate JavaScript file (promotes encapsulation, reuse, etc) instead of coding it in the JSP file. In this step, a callback method needs to be implemented as specified by the client side programming model. In this sample, one callback method handleLoadPortletPreferences and one business logic method addPrefItem are implemented.

    function SimpleJSPortlet(id, window) { = id;
    this.window = window;
    SimpleJSPortlet.prototype.handleLoadPortletPreferences =
    function (portletWindow, status, portletPrefs) {
    if (status==ibm.portal.portlet.PortletWindow.STATUS_OK) {
    portletWindow.setAttribute("preferences", portletPrefs);
    var prefs = portletPrefs.getMap();
    var htmlStr = "Number of preferences: "+prefs.length + "<br/>";
    for (var i=0; i<prefs.length; i++) {
    temp = i + 1;
    htmlStr += temp+" - "+prefs[i].name+" - "
    +prefs[i].values+" - "+prefs[i].readonly + "<br/>";
    var temp = document.getElementById("show<%=portletWindowID%>");
    temp.innerHTML = htmlStr;
    else { alert("error loading feed"); }

    SimpleJSPortlet.prototype.addPrefItem = function (value) {
    // retrieve the preferences object; it was stored earlier
    // in the callback method
    var prefs = this.window.getAttribute("preferences");
    //set a custom preference called Custom1 to the value supplied
    prefs.setValue("Custom1", value);
    //write to the window object
    this.window.setPortletPreferences(prefs, this.handleLoadPortletPreferences);


    Note: You should scope your variables because you can have other portlets in the same page that may contain JavaScript code as well as JavaScript Variables. You can also have two instances of the same portlet in the same page (Therefore, it is very important to create namespace’d objects and functions where applicable). Notice that namespace classes are not created as it is not necessary for this application (variables are scoped/namespace’d as shown in next step)
  4. Create JavaScript variables and invoke the right APIs based on the logic needed

    var portletWindow<%=portletWindowID%>
    = new ibm.portal.portlet.PortletWindow("<%=portletWindowID%>");
    var simpleJSPortlet<%=portletWindowID%>
    = new SimpleJSPortlet("<%=portletWindowID%>", portletWindow<%=portletWindowID%>);
    // add portlet object to window (needed for callback functions!)
    portletWindow<%=portletWindowID%>.setAttribute("portlet", simpleJSPortlet<%=portletWindowID%>);
    // load preferences to display initial list

    Notice how the JS instances are all scoped with the portletWindowID identifier (remember the portlet-client-model:init tag that gave us the server-side variable portletWindowID) which will be specific to a particular portlet window
  5. Generate the HTML code for the JSP page

    <form onsubmit="simpleJSPortlet<%=portletWindowID%>
    .addPrefItem(this.newPref.value);return false;">
    <input name="newPref" type="text"></input>
    <input type="Submit" value="Add Pref"></input>

Hopefully this gave enough information on how to create a client side portlet in WebSphere Portal 6.1.

Sukumar Konduru,
Apr 1, 2009, 3:33 PM