This guide provides a reference to the standard iWidget specification and shows you the additional features available for widgets in the Business Space environment.
As discussed in the Sample widgets overview, Business Space widgets conform to the iWidget specification. In this section a link is provided to that open-source specification followed by additional features for widget development that are found in Business Space.
The iWidget specification is an open-source specification upon which Business Space widgets are based. Before creating any widget, you should read this specification. Afterwards, it should be used as your guide for creating your own widget. You can find the iWidget specification at the following link:
The iWidget framework provides several predefined events that will be automatically fired without the need for a widget to declare them. For example, an iWidget may choose to override any of the default handlers. The behavior is as follows: if an iWidget defines any of the below event handlers as methods, then these methods will be called, otherwise the default framework event handlers will be invoked.
The iWidget framework provides some common dialogs that you should use when displaying information to the user. The following dialogs are provided by the framework in the following module: com.ibm.bspace.common.util.widget.BSpaceDialogs.
Dialog name | Description |
---|---|
com.ibm.bspace.common.util.widget.InfoPopup | Use this dialog to display informational messages to the user. |
com.ibm.bspace.common.util.widget.WarningPopup | Use this dialog to display warning messages to the user. |
com.ibm.bspace.common.util.widget.ErrorPopup | Use this dialog to display error messages to the user. |
com.ibm.bspace.common.util.widget.ConfirmDialog | Use this dialog to request a confirmation from the user. |
This code snippet for a confirm dialog shows how to use the common dialog:
1. //Show error dialog 2. dojo.require("com.ibm.bspace.common.util.widget.BSpaceDialogs"); 3. var errorDialogHolder = document.createElement("div"); 4. var errorDialogDiv = document.createElement('div'); 5. dojo.place(errorDialogHolder, errorDialogDiv, "last"); 6. this._errorDialogWidget = new com.ibm.bspace.common.util.widget.ErrorPopup({dojoAttachPoint: "errorDialogWidget"}, errorDialogDiv); 7. this._errorDialogWidget.setMessage( user friendly message, verbose details, possible actions ); 8. this._errorDialogWidget.show(); 9. var self = this; 10. dojo.connect(this._errorDialogWidget, "hide", function () {self._errorDialogWidget.destroyRecursive; });
Most widgets need to request data through a Uniform Resource Identifiers (URIs). To request a data through a URI, use the following code:
dojo.xhrGet({ url: this.iContext.io.rewriteURI(uri), load: handler });
You can use a similar approach for the other HTTP actions (PUT, POST, DELETE).
iWidget has specific mode handlers (eg. onview, onedit, and so on) for each possible mode that is specified in the supportedModes attribute of the iWidget's definition. For example, if an iWidget supports view mode and edit mode, you need to create onview and onedit methods in the widget's implementation. An onview method would be coded as follows:
onview: function(){ this.setGridDimention(); this.showFilterPattern(); this.findModels(this.listModels); }
The iWidget runtime guarantees that the proper mode event will be fired after an iWidget is loaded (eg. we can assume that onview() will be called after onLoad()). Therefore, your code for these mode events would be as follows:
onLoad: function(){ ... ... } onview: function(){ this.setGridDimention(); this.showFilterPattern(); this.findModels(this.listModels);
Your widget needs to add and manage the OK, Apply, Cancel, and Restore buttons that appear on the edit mode view. There is a helper class available in the common utility resource that all Business Space widgets will include. This helper class allows the creation of the edit mode buttons. To use this helper class follow these steps:
dojo.require("com.ibm.bspace.common.util.widget.BSpaceEditButtonPanel");
<div> <div class="editButtonPanelPlaceholder"></div> </div>
var temp = this.iContext.getElementByClass("editButtonPanelPlaceholder"); editButtonPanelPlaceholder = temp[0]; var editButtonPanel = new com.ibm.bspace.common.util.widget.BSpaceEditButtonPanel({parentWidget: this, iContext: this.iContext}, editButtonPanelPlaceholder);
Widgets must handle the onSizeChanged event by supplying an onSizeChanged(iEvent) method as defined by the iWidget specification. The payload of the iEvent will have properties for the newWidth and newHeight values. This method should resize the widget according to the new dimensions.
When the widget is minimized, the values for newWidth and newHeight will both become 0. In all other cases, the values for newWidth and newHeight will represent the actual dimensions that the widget should be, after the onSizedChanged event.
The following code shows how to use the onSizeChanged method:
onSizeChanged: function(iEvent) { var data = iEvent.payload; if (data) { alert("new height: " + data.newHeight); alert("new width: " + data.newWidth); } }
Widgets and framework classes should practice defensive programming and try to catch and handle exceptions in all top level methods. This means that widgets should encapsulate all of the following methods in try/catch block statements:
When you create a widget in Rational Application Developer or WebSphere Integration Developer, there will be many Dojo errors shown in the JavaScript editor. These errors do not prevent the widget from working. To remove the errors, edit the .project file in the workspace. Remove the jsNature line (<nature>org.eclipse.wst.jsdt.core.jsNature</nature>) and then refresh the project in the workspace.
When making a change to a widget, you should redeploy it. Then in the browser, logout of Business Space, clear the cache in the browser and then login to Business Space.
For the initial deployment in Rational Application Developer or WebSphere Integration Developer, you can use the add/remove projects dialog in the server view, rather than exporting an EAR and using the admin console to install it. Since the context root, defaults to the WAR project name, make sure you refer to the correct name for the 'url' tag in the widget endpoints XML file.
For subsequent deployments, you can select the option in the server view to republish the project to the server.
You have looked at the key iWidget specification that Business Space widgets are based upon and have learned some key areas that are unique to Business Space. In Representational State Transfer (REST) APIs you will find the REST APIs that are available to you for IBM business process management products. The REST APIs let you access functions at runtime in the IBM business process management products.