Overview

ECM Widgets 4.5.2 provides the following three out-of-the-box toolbar action widgets:

• Launch process widget
• Launch process (eForm) widget
• Open web page widget

These three widgets support action types such as launch process and open web page process. The widgets are available in a toolbar, as shown in Figure 1.

However, when a business analyst needs to support specific business-related actions that are beyond the capability of the out-of-box toolbar action widgets, the analyst will need to create customized action types and register them with the toolbar widget. When these newly created widgets become available from the toolbar widget, they can be selected to perform the functions to meet the business requirements for which they are created.

This article describes the following steps to create and use a custom toolbar action widget for the ECM toolbar widget:

1. Creating and customizing a toolbar action widget
2. Deploying the sample widget on the IBM WebSphere® Business Space 7
3. Editing the toolbar widget settings

Back to top

Creating and customizing a toolbar action widget

You need to implement a toolbar action widget to provide the customized action type of a toolbar widget. The action widget customization has some constraints. These constraints determine how the actions of this type can be defined and how this type will work as a menu option within the toolbar widget. The implementation of the action widget must include some specific events and functions for it to work with the container toolbar widget. The widget must meet the IBM iWidget specification requirements. Meeting these requirements enables the toolbar widget, upon loading, to obtain references to find your action widget and work with it. The specific requirements are:

• The definition file needs to specify the published and handled events required to register your custom widget with the toolbar widget. See Definition file requirements.
• The name of the definition file must include the suffix "_ToolbarAction.xml". For example, a definition file might be called My_ToolbarAction.xml.
• The JavaScript code must implement the published and handled events specified in the definition file. See Event handler requirements.

Begin by creating a toolbar action widget called MyToolbarAction (see Download if you want to work with a widget that is already created). Make MyToolbarAction a configurable widget. When it is launched from a toolbar, it displays a JavaScript alert that echoes back the text that the user entered while configuring the widget.

Definition file requirements

The definition file for the sample action widget is named My_ToolbarAction.xml. Complete the following steps to code the definition file.

1. Create the structure of the definition file, as shown in Listing 1.

<iw:iwidget name="My_ToolbarAction" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" 
    iScope="com.ibm.im.ecmwidgets.sample.My_ToolbarAction"
    allowInstanceContent="true" supportedModes="view edit" mode="view">
    <iw:resource uri="My_ToolbarAction.js"/>
    ...
</iw:iwidget>

2. Declare a send toolbar action published event under the <iw:resource> tag, as shown in Listing 2.

<iw:payloadDef name="ToolbarAction">
    <iw:payloadDef name="id" type="string" defaultValue="" description=""/>
    <iw:payloadDef name="callback" type="any" defaultValue="" description=""/>
</iw:payloadDef>   
    
<iw:event id="Send Toolbar Action" published="true"
    eventDescName="SendToolbarActionDescription"
    onNewWire="handleToolbarActionNewWire"
    onRemoveWire="handleToolbarActionRemoveWire"/>

<iw:eventDescription id="SendToolbarActionDescription" 
    payloadType="ToolbarAction" description="" lang="en"/>            

3. Declare a receive save request handled event, as shown in Listing 3.

<iw:event id="Receive Save Request" handled="true" 
    onEvent="handleReceiveSaveRequest" 
    eventDescName="ReceiveSaveRequestDescription" />

<iw:eventDescription id="ReceiveSaveRequestDescription" 
    payloadType="any" description="" lang="en"/>

4. If your custom action widget requires configuration, include configurable attributes and an edit mode. The toolbar widget displays the configuration parameters of your widget while it is in the edit mode in a separate configuration panel. Listing 4 shows attributes of the sample action widget.

<iw:itemSet id="attributes">
    <iw:item id="warningMessage" value="Hello"/>
    <iw:item id="label" value="My Toolbar Action"/>
    <iw:item id="actionType" value="My_ToolbarAction"/>
</iw:itemSet>

The value of the actionType attribute indicates the sample action widget in the toolbar's configuration wizard. The values of the myConfiguredValue and label attributes appear in the configuration panel of the sample action widget.

5. Specify the edit mode configuration data of the sample widget in a text area, which indicates a configuration option labeled as Warning Message Text, as shown in Listing 5.

<iw:content mode="edit">
    <![CDATA[
        <div id="_IWID_edit" class="ecmwdgt ecmwdgtEditModeContent">
            <div class="ecmwdgtFormField">
                <label>Warning Message Text</label>
                <input id="ecmwdgtSampleWarningMessage"
                    style="width: 99%"></input>
            </div>
        </div>
    ]]>
</iw:content>

Event handler requirements

In the JavaScript code, you must implement the handlers for the Send toolbar action published event and the receive save request handled event. The name of the event handler must match the name declared in the definition file in which the name is user definable during definition time.

Listing 6 shows the event handlers and the callback function of the sample widget.

dojo.provide("com.ibm.im.ecmwidgets.sample.My_ToolbarAction");

dojo.declare("com.ibm.im.ecmwidgets.sample.My_ToolbarAction", null, {

    onedit: function() {
        var input = dojo.byId("ecmwdgtSampleWarningMessage");
        var message = this.iContext.getiWidgetAttributes()
                                   .getItemValue("warningMessage");
        input.value = message;
        this.warningMessageControl = input;
    },

    handleToolbarActionNewWire: function(iEvent){
        this.sendToolbarAction();
    },

    sendToolbarAction: function() {
        var warningMessage = this.iContext.getiWidgetAttributes()
                             .getItemValue("warningMessage");
        var label = this.iContext.getiWidgetAttributes().getItemValue("label");
        var actionType = this.iContext.getiWidgetAttributes().getItemValue("actionType");
        var action = {};
        action.iWidgetInstanceId = this.iContext.widgetId;
        action.callback = dojo.hitch(this, "launchMyToolbarAction", this);
        action.attributes = {};
        action.attributes.actionType = actionType;
        action.attributes.label = label;
        action.attributes.warningMessage = warningMessage;
            
        this.iContext.iEvents.publishEvent("Send Toolbar Action", 
                                           action, "ToolbarAction");
    },   

    // callback function for sample action widget
    launchMyToolbarAction: function() {
        var message = this.iContext.getiWidgetAttributes()
                                   .getItemValue("warningMessage");
        alert("Warning Message: " + message);
    }, 

    handleReceiveSaveRequest: function(iEvent) {
        if (this.warningMessageControl) {
            this.iContext.getiWidgetAttributes()
                         .setItemValue("warningMessage", 
                                       this.warningMessageControl.value);
        }
        this.sendToolbarAction();
    }
});            

This JavaScript file is named My_ToolbarAction.js. When you select My_ToolbarAction item from the Action Type drop-down list, the toolbar widget instance creates an instance of My_ToolbarAction widget. The widget automatically wires its receive toolbar action event to My_ToolbarAction widget's send toolbar action event. The widget also wires its send save request event to My_ToolbarAction widget's receive save request event.

Once the send toolbar action event is wired, the handleToolbarActionNewWire function is kicked off. The function calls the sendToolbarAction function to send a send toolbar action event to the toolbar widget with its default value of the warning message (Hello) and the callback function definition (launch MyToolbarAction).

The toolbar widget then automatically switches the My_ToolbarAction widget's mode to edit mode and calls its onedit function. As Listing 6 shows, the onedit function retrieves the default or saves the value of the message from iContext and then drops it in the input box.

Once message editing is complete and you click OK, the Toolbar widget sends a send save request event to My_ToolbarAction. As configured in the definition file in Listing 6, the handleReceiveSaveRequest function is called to handle this event. The handleReceiveSaveRequest retrieves the updated message value from iContext, sends a send toolbar action to the toolbar widget, and saves the change.

Back to top

Deploying the sample widget on the IBM WebSphere Business Space 7

The IBM ECM Widgets 4.5.2 operate in an IBM WebSphere Business Space 7 container environment. To enable the sample widget to work with the IBM ECM Widgets 4.5.2, complete the following steps to deploy the sample widget on the IBM WebSphere Business Space 7.

1. Build the web application sources into an enterprise archive (EAR) file. The structure is shown in Figure 2.

2. Package the EAR file, a catalog file, and an endpoints file into a ZIP file, as shown in Figure 3.

3. Use two XML files, catalog_My_ToolbarAction.xml, and My_ToolbarActionEndpoints.xml to provide information to register the widget in the IBM WebSphere Business Space 7. Note that the name of the catalog file must start with a prefix catalog_ as shown in Listing 7.

<catalog id="SampleWidget1">
    <resource-type>Catalog</resource-type>
    <category name="My_ToolbarAction">
    ... ...

4. Deploy the widget with IBM WebSphere Business Space 7 commands in a Windows® command window, as shown in Listing 8. You might need to modify the path according to your system and where you deposit the zip file.

    C:\> cd <WAS_install_path>\profiles\<profile_name>\bin
    C:\> wsadmin -connType NONE
    C:\>$AdminTask installBusinessSpaceWidgets {-serverName server1 -nodeName 
    WMADBS7Node01 -widgets C:\ My_ToolbarAction.zip}
    C:\> $AdminConfig save

5. Restart the IBM WebSphere Application Server. The widget is now registered, as shown in Figure 4.

After you restart the server, the widget is available when you edit a page.

6. Configure the widget in IBM WebSphere Business Space 7.

Back to top

Editing the toolbar widget settings

Add a toolbar menu of the custom action by editing the toolbar widget settings. My_ToolbarAction is now a selectable item in the Action Type drop down list, as shown in Figure 5.

If it is selected, the Warning Message Text input box is shown with the default value of Hello. You can change the label or the value of the warning message text, and click OK to add it to the toolbar menu.

After saving the change, the action widget is already wired to the toolbar widget automatically in the Widget Wiring window of the toolbar widget, as shown in Figure 6.

If you go back to the View mode of Business Space 7, the action that was added becomes available in the toolbar, as shown in Figure 7.

Selecting the action item causes a warning message to pop up, as shown in Figure 8.

Back to top

Conclusion

This article described how to use a sample toolbar action widget, MyToolbarAction, to create a customized toolbar action widget of the toolbar widget.

Acknowledgments

Thanks to Simon Chu for reviewing this article. He is an IBM Master Inventor and is one of our great mentors.

Back to top

Download

Information about download methods

Resources

Learn

• Use an RSS feed to request notification for the upcoming articles in this series. (Find out more about RSS feeds of developerWorks content.)
  
  
• Go to Dojo toolkit to get more information about Dojo development.
  
  
• See the IBM ECM Widgets Information Center to get more information about IBM ECM Widgets
  
  
• Learn more about Information Management at the developerWorks Information Management zone. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Follow developerWorks on Twitter.
  
  

Get products and technologies

• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Visit the IBM ECM Widgets developerWorks forum to share your ideas and ask questions.
  
  
• Check out the developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

De Yu Wang is a Staff Software Engineer in IBM CDL. He has extensive development experience on IBM FileNet Business Process Management (BPM) products, which is part of IBM Information Management portfolio.

Gai Li is a Software Engineer in IBM China Development Lab. She has rich development experience in widget, Dojo, and Web 2.0 applications.

Wei Lei is a Software Engineer in IBM CDL. He has rich development experience in widget, Dojo, and Web 2.0 applications.

Rate this article

Comments

Back to top

Table of contents

• Overview
• Creating and customizing a toolbar action widget
• Deploying the sample widget on the IBM WebSphere Business Space 7
• Editing the toolbar widget settings
• Conclusion
• Download
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Information Management on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers