Creating widgets using Rational Application Developer

You can use Rational® Application Developer or Integration Designer to help you create custom widgets.

1. Using the Web perspective, create a dynamic web project for your custom widget and assign the project to an EAR. The dynamic web project maps to a WAR when you export the EAR.
   Tip: If you plan on the widget using its context root to find its resources, note the context root for the web application. You can keep the default or change it. Use the next page of the wizard to change the context root.
2. In the WebContent directory of the project (created automatically as part of the web project), create a directory structure to contain the code for your widget. The WebContent directory structure is where you place the deployable resources for your widget such as HTML and JSP files. Any resources that you place outside of the WebContent directory structure are for resources that are not deployed such as Java and SQL files.
   Tip: The common widgets included with Business Space are in the following structure: iWidget/widgets/widget_name. You can use this path to be consistent or you can use your own structure.
3. In the widget directory, create the iWidget definition file for your custom widget. Ensure that the ID of your iWidget is unique and that the iScope matches the name of the JavaScript class that defines the behavior of the widget. For information, see Creating iWidgets in the Rational Application Developer help.
   Tip: In Business Space, the naming convention for the widget definition file is widgetName_iWidget.xml.
4. Using the iWidget editor, define your widget by providing the following information:
   • Add the modes that the widget supports and the data or code for each mode.

     You must define the view mode so that Business Space has something to display. If you want users to modify (using the Edit settings menu item) the contents of the widget in some way, add the edit mode. In Business Space, the edit mode changes widget attributes (settings) in the Instance attribute layer. If you want certain users (typically only Business Space administrators) to modify the default values of the widget, add the config mode. The config mode changes widget attributes in the Administration layer. If you want users to customize how the widget displays its data and have that change apply only to individual users, add the personalize mode. The personalize mode changes widget attributes in the User layer. For information on the attribute layers in Business Space and how they work, see "Widget attribute layers" and "Supporting widget customization and personalization."

   • Add the attributes of the widget by adding an item set and items within it. These attributes provide the default values for the widget. For example, if your widget displays a web site, add a url attribute to store the URL.

     The values are stored as strings so your implementation might need to convert these values.

     Ensure that you include an attribute for supporting each setting or personalization that users can make in the widget. For example, if your widget includes a table and you want to support personalizing which column the table uses to sort the information, you might have a sort_column attribute to store this information.

   • The events that the widget publishes and handles by adding a definition and description for each event.
   • Add, as a resource, the relative path and name of the file that declares the iScope. The iScope is a Dojo class that is an entry point to an iContext class at run time. This entry point is the part of the widget that interacts with the environment through the iContext class. The iContext class is central to the widget runtime environment and provides all the environmental services such as access to global variables, a shared state, local variable storage, widget communication using events, remote services, mode support and many other capabilities.

     In this case, the file is in the same directory as the widget definition so there is no need to include the path.

   • Add, as resources, the relative path and name of any other files that your widget needs. For example, if your widget uses a .css file for formatting, add the path and name of this file as a resource. However, when you are adding resources, consider that too many requests for resources impacts performance and the code should refer to as few Javascript, CSS and image files as possible. Consider using techniques such as image spriting, combining and minimizing Javascript and CSS files, and lazy loading of resources (such as waiting to load resources for edit mode until the onEdit event occurs) when designing your widget.
   You can also add your code or data directly to the XML file using the Source tab. For more information on the widget definition and its elements and on the iContext, see the iWidget 2.1 specification.
5. Create the JavaScript file that declares the iScope and then start defining the iScope by identifying its interface. Create the implementation for your widget using JavaScript or any other programming language or script. Continue to develop the iScope in parallel with developing the widget implementation.
   Tip: If your widget is simple and you are using JavaScript for its implementation, create the widget implementation in the iScope file itself.
   1. Create handlers for the modes that you added in the iWidget definition and the various events defined in the interface including the predefined events from the iWidget specification. For the following predefined iEvents (from the iWidget specification), Business Space provides default event handlers, which you can override if needed:
      • onLoad, which is called when the widget loads for the first time and when the browser refreshes. The widget can initialize the initial view in this handler. There is no event payload. You can retrieve the item values using code like this:

        var att = this.iContext.getiWidgetAttributes();
        this.name = att.getItemValue("name");

      • onReload, which is called when the widget is reloaded. This event handler is similar to onLoad, however, it is called in slightly different circumstances. When a user is in edit mode and selects one of the buttons at the bottom of the settings window, the onReload event handler is called when the view mode is refreshed. This is slightly different behavior than the iWidget specification calls for, since the specification asks that this event fire prior to the reload, rather than during an edit mode refresh of the iWidget content. There is no event payload.
      • onUnload, which is called when the widget is about to be unloaded. There is no event payload.
        Important: Ensure that all Dojo widgets that you create are cleaned up during this event handler. You need to call <widget>.destroyRecursive() to ensure that all child Dojo widgets are cleaned up in terms of memory usage.
      • onRefreshNeeded, which is called when the iContext determines that the widget's data is stale. This event should signal to the iWidget to refresh its data if applicable.
   2. For each mode specified in the supportedModes attribute in the widget definition, create a mode handler. For example, if your widget has a view mode and an edit mode, create onView and onEdit methods. The onView method could be coded as follows:

      onView: function(){
      ... 
      }

   3. Create a handler for the onSizeChanged event. The event has a payload that contains values for the newWidth and newHeight attributes. The handler uses this information to resize the widget to the specified width and height. If the user has minimized the widget, these attributes will have a value of 0.

      The following code shows how to use the onSizeChanged handler:

      onSizeChanged: function(iEvent) { 
            var data = iEvent.payload; 
            if (data) { 
               alert("new height: " + data.newHeight); 
               alert("new width: " + data.newWidth); 
            } 
         }

   4. Optional: If your widget is accessing data through REST APIs, use Uniform Resource Identifiers (URIs) in code like the following example:

      dojo.xhrGet({ 
        url: this.iContext.io.rewriteURI(uri), 
        load: handler 
      }); 

      You can use a similar approach for HTTP actions like PUT, POST, and DELETE.

6. Create image files to serve as the preview and icon images for your custom widget and put them somewhere in the WebContent directory. Make the icon image 28 pixels by 28 pixels and make the preview image 160 pixels wide by 128 pixels high.
7. Optional: If your custom widget will have online help, create one or more HTML files to provide the help text. You can package these files with your widget or you can create a documentation plugin and place your help files in the plugin. See "Creating a documentation plugin" for information.
8. To register your custom widget, create a definition for the widget in a catalog file. You can put the entry in an existing catalog file or you can create your own catalog file. See "Registering custom widgets using catalog files" for information about creating a catalog file and a widget registration definition. If you create a catalog file, put it in a catalog directory outside of the WebContent directory.
   Tip: In Business Space, the naming convention for the widget registration file is catalog_catalogName.xml.
9. Package and deploy your custom widget. If the profile containing Business Space is not local, use the wsadmin tool on the application server as described in as described in "Packaging and deploying custom widgets." If the Business Space profile is local, you can run the commands within your development environment using the following steps:
   1. Export the catalog directory into a JAR file and specify that the extension of the file is .zip. The ZIP file must have your catalog file within a catalog directory.
   2. Create a directory to contain the packaging and deployment script. Make sure that the script directory is not in the WebContent directory or any of its children.
   3. Create a Jython script file in your script directory and name it something like installBSpaceWidget.py.
   4. Edit the script file to add the following code:

      AdminTask.installBusinessSpaceWidgets('[-nodeName node_name -serverName server_name -widgets path/catalog_file.zip]')

   5. Save the file and close it.
   6. In the explorer view, right click the script and select Run as > Administrative script
   7. In the Edit Configuration window, add the following information:
      • For the scripting runtime environment, specify the application server type.
      • For the profile name, specify the profile that contains Business Space.
      • For the wsadmin arguments, type -conntype NONE.
      • If Business Space has security enabled, specify the administrator user ID and password.
      You can track the progress of the script in the Console view. Depending on your server, the script will take several minutes to complete.
10. Test your widget by doing the following steps:
    1. In the Server view, right click and select New.
    2. Using the New Server wizard, create a view that points to the WebSphere® Application Server profile that contains Business Space.
    3. Add the EAR project for your widget to the server that you created. Now that you have connected your development environment to the Business Space, you can test and develop the widget. You do not need to repackage and deploy the widget unless you need to make changes to its catalog file or to its documentation plugin.
    4. In a Web browser, browse to the Business Space URL. The URL will be something like http://localhost:9080/BusinessSpace.
    5. Log into Business Space and then test your widgets.