Migrating a Business Space custom widget to run in the Dashboard

If you developed custom widgets for use in Business Space V7.5, V7.5.1, or V8.0, you can migrate these widgets to work with the dashboard.

1. Fully extract your Business Space custom widget archive. The archive contains an ear directory that contains one or more EAR files. These EAR files in turn contain one or more WAR files that contain your widget definition and implementation files. It is these WAR files that you must migrate in subsequent steps.
2. Your widget implementation files must now form one or more Asynchronous Module Definition (AMD) modules that are supported by Dojo 1.7 or later. Upgrade your widgets to use AMD and Dojo 1.9. See http://dojotoolkit.org/ for information about upgrading to Dojo 1.9.
   Note: In the WSRR V8.5.5 dashboard, the instance of the IBM Dojo Toolkit is based on version 1.9 of the Dojo toolkit. However, this bundled version might be updated as needed over time. This might include entire new Dojo versions and specific defect fixes. Compatibility of future Dojo versions is defined by the Dojo project.
3. If your widget implementation uses Business Space events or Business Space utility classes to access endpoint information, you must use the new CustomWidgetHelper.js helper provided by the dashboard instead. See CustomWidgetHelper.js helper for custom widgets for information about the helper and how it is accessed.
4. If your widget implementation uses the Business Space proxy, you must use the dashboard proxy instead. You can access the dashboard proxy by using the iContext.io.rewriteURI method. The method returns a URL that is rewritten so that it uses the dashboard proxy server. For example:

   <ENDPOINT BY PROXY> = this.iContext.io.rewriteURI(<ABSOLUTE URI TO ORIGINAL ENDPOINT>)

5. If your widget implementation uses Business Space wrappers for form controls such as check boxes and buttons, you must use the standard Dojo dijit/form controls instead.
6. Remove any Business Space or other CSS that is likely to interfere with the dashboard CSS.
7. If your widget implementation depends upon image files or other resources, you must use the getResourceUrl method provided by the CustomWidgetHelper to obtain an absolute URL that the browser can resolve. For example, you must set the src attribute of an img tag programatically using the value returned by the getResourceUrl method after supplying a relative URI for the image file as an argument. The URI you supply to the method must be relative to the location of your iWidget XML file. See CustomWidgetHelper.js helper for custom widgets for information about the helper and how it is accessed.
8. The dashboard supports version 2.1 of the iWidget specification, but some changes must be made to your iWidget XML descriptor files:
   1. Add the following attributes to your root iWidget element:

      xmlns:cre="http://www.ibm.com/xmlns/prod/CRE"
      cre:iScopeType="dojoAMD"

   2. Update the id attribute of your event elements so that they begin com.ibm.sr.ui.iwidgets instead of com.ibm.sr.bspace.widgets.
   3. Optional: Add an iDescriptor to specify a name, description, default height, and thumbnail image for your custom widget. These are used by the dashboard if they are available.
   The following is an example iWidget XML descriptor file:

   <?xml version="1.0" encoding="UTF-8" ?>
   <iw:iwidget id="YourCustomIWidget" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" xmlns:cre="http://www.ibm.com/xmlns/prod/CRE" supportedModes="view edit" cre:iScopeType="dojoAMD" supportedWindowStates="normal minimize maximize" iScope="sample.custom.widget.CustomIWidget"> 
         <iw:resource globalid="CustomIWidgetJS" src="CustomIWidget.js"/>
         <iw:itemSet id="idescriptor">  
       	  <iw:item id="title" lang="en" value="Your Custom iWidget"></iw:item>              
             <iw:item id="description" lang="en" value="Your Custom iWidget"></iw:item>  
             <iw:item id="defaultHeight" lang="en" value="250"></iw:item> 
         </iw:itemSet> 
         <iw:event id="com.ibm.sr.ui.iwidgets.events.itemSelected" handled="true" published="false" onEvent="loadData" eventDescName="desc_itemSelected" /> 
         <iw:eventDescription id="desc_itemSelected" lang="en" payloadType="json" title="Item selected" description="Edit the selected data"> 
         </iw:eventDescription> 
         <iw:content mode="view">  
             <![CDATA[  
                <div>Hello World</div>  
             ]]> 
         </iw:content> 
         <iw:content mode="edit">  
            <![CDATA[   
                <div>Hello World</div>  
             ]]> 
         </iw:content> 
   </iw:iwidget>

9. Package your .xml and .js files along with any supporting files that they require (such as image files) within a .zip file. You can then load your new custom widget archive .zip file in to the Dashboard. See Managing custom widgets. The file path to your main widget implementation file within your zip archive must match the package name of the iScope declared in your iWidget XML file. For example, if your iScope is sample.custom.widget.iscope.MyCustomWidget then MyCustomWidget.js must exist in the following directory path inside the .zip file: /sample/custom/widget/iscope.