Client programming with Dojo

IBM® WebSphere® sMash includes the Dojo toolkit for developing AJAX-based clients. Although AJAX and Dojo are not required for WebSphere sMash applications, the combination can result in compelling Web applications.

Adding Dojo to your application

You can add Dojo to your WebSphere sMash application as a dependency. Start by adding the following line to the dependencies element in your config/ivy.xml file: 

      <dependency org="dojo" name="dojo" rev="1+"/>

For more information about Dojo specifically, see the Dojo references section for links to that information. The following sections describe using Dojo with WebSphere sMash.

Leveraging convention for custom Dojo widgets

Dojo widgets are comprised of standard file types for the Web browser, including HTML, JavaScript™, and CSS. As long as these files are accessible using HTTP, you can incorporate them into your application.

WebSphere sMash introduces an optional convention for organizing your custom Dojo widgets: widget source files are placed under the app/zwidgets/ folder to simplify tooling integration. For example, this convention can be used to add your widgets to the palette in the visual page editor.

This convention requires that your application include the Dojo module as a dependency. Included in that module is the support to serve files from the app/zwidgets/ directory using the /zwidgets URI.

For example, if you want to create a widget x.MyWidget for this convention, then you have the following files: 

app/zwidgets/x/MyWidget.js
app/zwidgets/x/templates/MyWidget.html

To use any custom widget, you must first register the module path. For this example, add the following line to the script tag of your HTML: 

  dojo.registerModulePath("x", "../zwidgets/x");

Using a relative path ensures that your application is not affected by changes in the context root.

Using Dojo data to integrate with resource handlers

Another common design pattern is an AJAX-based client as the user interface for RESTful services interacting with XHR. This pattern is indirectly demonstrated in the Employee Demo sample. The sample uses the Dojo DataGrid and the Dojo data store (zero.resource.RestStore) provided by WebSphere sMash to retrieve and access resources in the application. Highlights of the sample, showing snippets from public/index.gt are shown in the following example for including Dojo: 

<head>
<script type="text/javascript" 
  src="/dojo/dojo.js"
  djConfig="parseOnLoad: true, isDebug: false"></script>
<script type="text/javascript">
  dojo.require("dojox.grid.Grid");
  dojo.require("zero.resource.RestStore"); 
  dojo.require("dijit.form.Form");
  dojo.require("dijit.form.ComboBox");
  dojo.require("dijit.form.TextBox");
  dojo.require("dojo.data.ItemFileReadStore");
  dojo.require("dojo.parser");
</head>

To use the zero.resource.RestStore, the application must specify a dependency on the zero.dojo module. 

      <dependency org="zero" name="zero.dojo" rev="[1.0.0.0, 2.0.0.0["/>

To enable the Dojo debug console, set the isDebug attribute to true.

Render collection data

Click the List Employees button to populate the employeeDataGrid grid with the list of employees. 

<script type="text/javascript">
function listEmployees(){
  setError("");
  // Using the jsId of the model to call refresh, which will reload the grid.
  employeeDataModel.refresh({onError: onError});
}

function onError(response) {
  setError(response);
}

function setError(errorText) {
  if (errorText != null && errorText != "") {
    if (errorText.responseText != null && errorText.responseText.toString().indexOf("500") != -1) {
      var jsonRespText = dojo.fromJson(errorText.responseText);
      if (jsonRespText != null && jsonRespText.rootCause.indexOf("duplicate key") != -1) {
        errorText = "<font color=red> The username entered is already exists. Please enter a unique username. </font>";
      } else {
        errorText = "<font color=red> The database may not have been initialized.  Please refer to the documentation for setting up the database.</font>";	    
      }
	} else {
	  errorText = "<font color=red>"+errorText.message+"</font>";
    } 
  }
  var err = dojo.byId("error");
  err.innerHTML = errorText;
}

var view = {cells:
  [[
    {name: 'Username', field: 'username', width: 'auto'}, {name: 'First Name', field: 'firstname', width: 10}, {name: 'Last Name', field: 'lastname', width: 10}, {name: 'Location', field: 'location', width: 10}, {name: 'Phone Number', field: 'phonenumber', width: 10}
  ]]
};
// a grid layout is an array of views.
var layout = [ view ];
</script>

<script type="text/javascript">document.write('<div dojoType="zero.resource.RestStore" jsId="employeeStore" resourceUri="'+employeeURL+'" memberIdentifier="username" memberLabel="username"></div>');</script>
<div dojoType="dojox.grid.data.DojoData" jsId="employeeDataModel" store="employeeStore" rowsPerPage="10"></div>
<div style="width: 800px; margin: auto; border-width: 1px 1px 1px 1px; border-style: solid; border-color: lightgray;">
<div jsid="employeeDataGrid" id="grid" dojoType="dojox.grid.Grid" model="employeeDataModel" structure="layout" style="width: 100%; height: 250px;"></div>

<button onclick="listEmployees();" style="width: 100%">List Employees</button>
<!-- display error message -->
<div id="error"></div>

Create new employee entry

Click the Add New Employee button to display a form for creating a new employee record. 

<script type="text/javascript">
function addEmployee() {
  var empform = dijit.byId("empform");
  var values = empform.getValues();
  if (values.username == '') {
    setError("Username cannot be empty.");
	return;
  }

  var employeeItem = null;
  try {
    employeeItem = employeeStore.newItem(values);
    if (employeeItem) {
      onEmployeeAdded(employeeItem);
    }
  } catch (error) {
    setError(error);
  }
}

function showEmployeeForm() {
  hideEditForm(false);

  var empformholder = dojo.byId("empformholder");
  empformholder.style.display = "block";
}

function hideEmployeeForm(reset) {
  var empformholder = dojo.byId("empformholder");
  empformholder.style.display = "none";
  if (reset) {
    var empform = dijit.byId("empform");
    empform.containerNode.reset();
  }
  setError("");
}
</script>

<div dojoType="dojo.data.ItemFileReadStore" jsId="locationStore" url="/resources/locations"></div>

<!-- form for creating an employee -->
<div id="empformholder" style="display:none">
<form dojoType="dijit.form.Form" id="empform" name="empform" onSubmit="return false;">
  <br/><br/>
  <table border=2> 
    <tr><th align="left">Property</th><th align="left">Value</th></tr> 
	<tr><td>Username</td><td><input type="text" dojoType="dijit.form.TextBox" maxlength="32" name="username"  /></td></tr> 
	<tr><td>First Name</td><td><input type="text" dojoType="dijit.form.TextBox" maxlength="16" name="firstname"  /></td></tr> 
	<tr><td>Last Name</td><td><input type="text" dojoType="dijit.form.TextBox" maxlength="16" name="lastname" /></td></tr>
	<tr><td>Location</td><td><select dojoType="dijit.form.ComboBox" store="locationStore" maxlength="64" name="location" /></td></tr>
	<tr><td>Phone Number</td><td><input type="text" dojoType="dijit.form.TextBox" maxlength="16" name="phonenumber" /></td></tr>
  </table><br />
  <button onclick="addEmployee();">Add</button>    
  <button onclick="hideEmployeeForm(true);">Cancel</button>
</form>
</div>

<button onclick="showEmployeeForm();" style="width: 100%">Add New Employee</button>

Update employee

Click the Edit Selected Employee button to display an edit form with the selected employee record. 

<script type="text/javascript">
function updateEmployee() {
  var editform = dijit.byId("editform");
  var values = editform.getValues();
  var username = dijit.byId("editUsername").getDisplayedValue();

  var itemFound = function(item, request) {
    if (item) {
      var key;
      for (key in values) {
        employeeStore.setValue(item, key, values[key]);
      }
      employeeStore.save({onComplete: onEmployeeUpdated, onError: onError});
    }
  };

  employeeStore.fetchItemByIdentity({identity: username, onItem: itemFound, onError: onError});
}

function showEditForm() {
  hideEmployeeForm(false);

  var username = getSelectedUserName();
  if (username == null) {
    return;
  }
   
  var req = dojo.xhrGet({
    url: employeeURL + '/' + username,
    handleAs: 'json-comment-optional', 
    sync: false
  });
  req.addCallbacks(onShowEditForm, onError);
  var editformholder = dojo.byId("editformholder");
  editformholder.style.display = "block";
}

function onShowEditForm(data){
  var editform = dijit.byId("editform");
  editform.setValues(data);
}
</script>

<!-- form for editing employee details -->
<div id="editformholder" style="display:none">
<form dojoType="dijit.form.Form" id="editform" name="editform" onSubmit="return false;">
<br/><br/>
<table border=2>
  <tr><th align="left">Property</th><th align="left">Value</th></tr> 
  <tr><td>Username</td><td><input type="text" id="editUsername" dojoType="dijit.form.TextBox" maxlength="32" name="username"  disabled/></td></tr> 
  <tr><td>First Name</td><td><input type="text" dojoType="dijit.form.TextBox" maxlength="16" name="firstname"  /></td></tr> 
  <tr><td>Last Name</td><td><input type="text" dojoType="dijit.form.TextBox" maxlength="16" name="lastname" /></td></tr>
  <tr><td>Location</td><td><select dojoType="dijit.form.ComboBox" store="locationStore" maxlength="64" id="edit_location" name="location"/></td></tr>
  <tr><td>Phone Number</td><td><input type="text" dojoType="dijit.form.TextBox" maxlength="16" name="phonenumber" /></td></tr>
</table><br />
<button onclick="updateEmployee();">Update</button>    
<button onclick="hideEditForm(true);">Cancel</button>
</form>
</div>

<button onclick="showEditForm();" style="width: 100%">Edit Selected Employee</button>

Delete employee entry

Click the Delete Selected Employee button to remove the currently selected rows. 

<script type="text/javascript">
function deleteEmployee() {
  setError("");
  employeeDataGrid.removeSelectedRows();
}
</script>

<button onclick="deleteEmployee();" style="width: 100%">Delete Selected Employee</button>

Dojo references

The best sources of information for Dojo can be found at the following locations:

Version 1.1.28346