Creating widgets using basic tools

You can use basic tools such as a text editor or other editors to create custom widgets.

1. Create a directory structure to contain the files for your custom widget.
   Tip: The common widgets are in the following structure: iWidget/widgets/widget_name. You can use this path to be consistent or you can use your own structure.
2. In the widget_name directory, create the widget definition file and define your widget in it. For more information on the widget definition and its elements and on the iContext, see the iWidget specification.
   Tip: The naming convention for the widget definition file is widgetName_iWidget.xml.

   In the widget definition and its elements, you define the following things:

   • The name of the widget and the schemas being used.
     For example:

     <?xml version="1.0" encoding="UTF-8" ?>
     <iw:iwidget 
     	id="HelloWorld" 
     	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     	xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" 
     	supportedModes="view edit" 
     	lang="en" 
     	iScope="HelloWorld" 
     	name="helloWorld">

     The id must be unique.
   • The scope, which is the Dojo wrapper class for the widget implementation.
     For example:

     <iw:iwidget 
     	id="HelloWorld" 
     	...
     	iScope="HelloWorld" 
     	name="helloWorld">

     The iScope should match the name of the JavaScript class that defines the behavior of the widget.
   • The modes that the widget supports and the definitions for each mode.
     For example, add the modes:

     <iw:iwidget 
     	id="HelloWorld" 
     	...
     	supportedModes="view edit" 
     	...
     	name="helloWorld">

     For example, define the modes that you added:

     <iw:content mode="view">
     			<![CDATA[
     			<div>Hello World</div>
     			]]>
     </iw:content>

     You must define the view mode so that there is 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. The edit mode changes widget attributes (settings) in the Instance attribute layer. If you want certain users (typically only 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 and how they work, see Widget attribute layers and Supporting widget customization and personalization.

   • The path and name of the JavaScript 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. For example: <iw:resource src="helloWorld.js" id="iScopeFile" />. In this case, the file is in the same directory as the widget definition so there is no need to include the path.
   • The attributes of the widget, which include the settings that users can modify. These attributes provide the default values for the widget. The values are stored as strings so your implementation might need to convert these values. For example:

     <iw:itemSet id="attributes" private="true">
     	<iw:item id="url" readOnly="false" value="http://www.ibm.com"/>
     </iw:itemSet>

   • The events that the widget publishes and handles by adding a definition and description for each event. For example:

     <iw:event eventDescName="displayHtml" handled="true" id="Receive URL" onEvent="displayMarkup"/>
     <iw:eventDescription 
     	description="Receives and displays a URL that is sent from another widget" 
     	id="displayHtml" 
     	lang="en" 
     	payloadType="url.html" 
     	title="Receive URL">
     </iw:eventDescription>

   • 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.
3. 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), there are 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 before 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.

4. Create image files to serve as the preview and icon images for your custom widget. The icon image should be 28 pixels by 28 pixels while the preview image should be 160 pixels wide by 128 pixels high.
5. 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 plug-in for information.
6. Package your widget definition file, widget implementation files, and image files into an EAR using an appropriate packaging tool. The tool must be able to package EARs and WARs according to J2EE specifications.
7. 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.
   Tip: The naming convention for the widget registration file is catalog_catalogName.xml.
8. Package and deploy your custom widget as described in Packaging and deploying custom widgets.
9. In a web browser, browse to the Process Portal URL. The URL will be something like http://localhost:9080/BusinessSpace.