IBM Connections iWidget Development - Communities

Social Business Application Development Workshop

Author: Paul GodbyIBM Ecosystem DevelopmentLast Updated: February 21, 2014


Lab Manual

IBM Connections iWidget Development

Communities

NOTE: In this lab you will be writing code. If you are not a developer (or if you don't feel like typing everything)you can choose to copy/paste the code from the lab solutions files located at:

/labs/solutions/ecod.iwidgets.communities

COPYRIGHT IBM CORPORATION 2014. ALL RIGHTS RESERVED.IBM Ecosystem Development

1


Introduction:IBM Connections provides the ability for third-party developers to integrate iWidgets into the IBM Connections user interface for use in the Communities, Home page, and Profiles features.

An iWidget is a Web application that allows you to add content to the IBM Connections user interface. In IBM Connections, many areas of the user interface are constructed using iWidgets. Developers and administrators can extend the user interface with new capabilities and also replace existing capabilities that are shipped with the product by developing their own iWidgets using the iWidget specification.

All widgets must conform to the iWidget specification, which uses technology based on JavaScript, XML, HTML, and CSS. The widget files are stored on any HTTP server. The widgets can also be bundled as EAR applications and deployed on IBM WebSphere Application Server.

Description:An iWidget is composed of the following components:

• XML iWidget descriptor: The core component that identifies the widget. This XML fragment defines the functionality supported by the widget. It's also used to pull in additional resources, such as external JavaScript or CSS files.

• Resource bundles: A resource bundle can be defined and will contain custom strings for use by the widget. This is a server-side resource and must be configured by an administrator.

• widgets-config.xml: Used to declare the widget for a specific IBM Connections application and to place the widget in specific locations on the page. This is a server-side configuration and must be performed by an administrator.

To proceed with this lab, it is important to have a good understanding of the various technologies used (for example, JavaScript, XML, HTML, and CSS) and preferably some experiences with Dojo. These technologies are essential to understanding the development of widgets for IBM Connections.

Objective:This lab will explain the following tasks:

Server configuration

Developing and deploying iWidgets in Communities


2


Procedure:

SERVER SETUP

IBM Connections, IBM HTTP Server, DB2, and LDAP will need to be running in order to complete this lab.

Step 1 If you haven't done so already, review the VMware setup document to configure networking for the current image.

Step 2 If you haven't done so already, start the LDAP services by double-clicking the “Lotus Domino Server” icon on the desktop.

Step 3 If you haven't done so already, start IBM Connections and IBM HTTP Server by double-clickingthe “Start IBM Connections” icon on the desktop. Verify that all servers have started by waiting for “open for e-business” messages before continuing. This may take a few minutes.

CONFIGURE COMMUNITIES WIDGETS

To make custom widgets available for use in Communities, you need to configure the widgets in the widgetdefinition file, widgets-config.xml.

The widgets-config.xml file contains information about widget definitions, widget attributes, widget location, defaultwidget templates, and page definitions. Custom widget attributes are defined by the widget developer but, asadministrator, you need to configure the widgets by adding a <widgetDef> element containing the appropriateattributes for each widget in the widget configuration file.

Step 4 In a terminal window, enter the following commands to check out the configuration file:

Note: By default, the wsadmin utility in Linux does not give you the ability to leverage the terminal window historyfeature (recycle commands using UP and DOWN arrows). This can make working with this utility in Linux afrustrating experience... The rlwrap readline utility is a free utility for Linux that will enable this functionality for you! Touse it, you simply precede your wsadmin tool invocation with the word “rlwrap” (as seen on line 2 below).

cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin

rlwrap ./wsadmin.sh -lang jython -user wasadmin -password passw0rd

execfile(“communitiesAdmin.py”)

CommunitiesConfigService.checkOutWidgetsConfig(“/config”,”connectionsCell01”)

Step 5 Leave the terminal window with your existing wsadmin session open. Open another terminal window and enter the following commands to edit the checked out configuration file.

gedit /config/widgets-config.xml


3


Step 6 You will need to add entries describing your widgets. Click Search → Find... In the Search for: field, type: resource type=”community” and click Find. After you find the community resources section, you can hit Close in the Find dialog window.

Step 7 Scroll to the bottom of the definitions section (Alternatively, search for: </definitions>). Add a new definition for your custom iWidget. This iWidget will be made available in the widget palette for all Community owners.

<widgetDef defId=”EcoD Community Palette" description="This widget does stuff" url="http://connections.demos.ibm.com/widgets/ecodCommPal.xml">

<itemSet><item name="communitiesBaseUrl" value="{communitiesSvcRef}" /><item name="attr1" value="value 1" />

</itemSet></widgetDef>

Field Value

defId Unique ID; matches the key in the properties file for the title

description Matches the key in the properties file for the widget palette description

bundleRefId The name of the resource bundle from Lotus-Connections-config.xml

url The location of the XML descriptor file for the iWidget

itemSet Custom configuration attributes that can be consumed by the widget

Step 8 Add the following widget definition. This iWidget will appear in column 1 of each Community.

<widgetDef defId="EcoD Col 1" showInPalette=”false” url="http://connections.demos.ibm.com/widgets/ecodCommCol1.xml"></widgetDef>




4




Step 11 At this point in the configuration, the iWidget that will appear in the widget palette is ready to go. However, in order to display widgets by default in columns 1, 2, and/or 3, there is an additional configuration step. You will need to define some mandated widget instances.

Step 12 Right below the definitions section in the XML file is the layout section. You will be placing widgets inside each Community that is created. So, you will add the following widget instancesto the page with a pageId of “communityOverview”:

<widgetInstance uiLocation=”col1” defIdRef=”EcoD Col 1”/>



Step 13 When finished, the section should look like the following image:

Note: The order the widgets are listed in here will be the order that they appear inside IBM Connections.

Step 14 Click Save. Close the text editor.

Step 15 Return to the terminal window with your existing wsadmin session. Check in your changes withthe wsadmin tool using the following command:

Note: Since you invoked wsadmin using the rlwrap utility, you can press UP to retrieve the previous command andmodify accordingly. You're welcome :)

CommunitiesConfigService.checkInWidgetsConfig(“/config”,”connectionsCell01”)

Step 16 Leave your wsadmin session running and continue to the next section.


5


CONFIGURE THE AJAX PROXY FOR COMMUNITIES

The AJAX proxy configuration for all of the IBM Connections applications is defined in the proxy-config.tpl file. Ifyou want to specify different AJAX proxy settings for a specific application only, you can do so by creating a new,application-specific version of the proxy-config.tpl template file.

This task is not required. Only perform it if you want to display information from an external service within IBMConnections. You can define a custom proxy configuration for the Activities, Communities, Home page, Profiles,and Search applications, but not the other IBM Connections applications.

By default, the IBM Connections AJAX proxy is configured to allow cookies, headers or mime types, and all HTTPactions to be exchanged among the IBM Connections applications. If you want to change the traffic that is allowedfrom non-IBM Connections services, you must explicitly configure it.

Step 17 In a new terminal session window (or reuse an existing one), type the following command and press Enter to open a text editor.

gedit

Step 18 Click Open and open the default proxy configuration file. The location is:

/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/config/cells/connectionsCell01/LotusConnections-config” and the file name is “proxy-config.tpl

Step 19 You will not edit this file directly. Instead, you will make a copy specific to the Communities application. Click File → Save As...

Step 20 Save a copy of the file and name it “proxy-communities-config.tpl”. Save it in the same directory as the original file.

Step 21 Close the new copy of the file. Close gedit.


6


Step 22 Return to your existing wsadmin session and enter the following commands to check out the Communities proxy configuration file.

CommunitiesConfigService.checkOutProxyConfig(“/config”,”connectionsCell01”)

Step 23 Leave the terminal window with your existing wsadmin session open. Open another terminal window and enter the following commands to edit the checked out configuration file.

gedit /config/proxy-communities-config.tpl

Step 24 You will need to add a new proxy rule for your widget so that it can communicate with other machines. Click Search → Find... In the Search for: field, type: wikisSvcRef and click Find. After you find the section, you can hit Close in the Find dialog window.

Step 25 Copy this entire XML fragment (containing your found “wikisSvcRef” string) beginning with <proxy:policy and ending with </proxy:policy>

Step 26 Scroll down to the section  and paste the copied text beneath it.

Step 27 Change the url attribute in the proxy:policy tag to point to the HTTP server that will host your iWidget. In this lab environment, it will be the IHS server configured for IBM Connections. In the iWidget programming exercises, you will create your iWidget and copy it to this HTTP server.

<proxy:policy url="http://connections.demos.ibm.com/*" acf="none" basic-auth-support=”true”>


7


Step 28 You can configure which cookies can (or can not) be passed to any back-end service that your widget will communicate with. In this example, you will add the LtpaTokens for SSO purposes. To do this, add a proxy:cookies tag and include the cookies you want to pass on from Connections to your iWidget.

<proxy:cookies><proxy:cookie>LtpaToken</proxy:cookie><proxy:cookie>LtpaToken2</proxy:cookie>

</proxy:cookies>

Step 29 When finished, the XML fragment should look like the following:

Step 30 In the text editor, click File → Save. Close gedit.

Step 31 Return to the terminal window with your existing wsadmin session. Check in your changes withthe wsadmin tool using the following command. You will also add the quit command since you are now finished with the server configuration!

CommunitiesConfigService.checkInProxyConfig(“/config”,”connectionsCell01”)


8


Step 32 All of the Communities iWidget configuration changes have been made! Now, it's time to resynchronize the nodes to ensure all of the changes propagate. In the existing wsadmin session, enter the following commands:

execfile(“connectionsConfig.py”)

LCConfigService.checkOutConfig(“/config”,”connectionsCell01”)

LCConfigService.updateConfig(“versionStamp”,””)

LCConfigService.checkInConfig(“/config”,”connectionsCell01”)

synchAllNodes()

Step 33 Leave the wsadmin session running and continue to the next section.

RESTART THE COMMUNITIES APPLICATION

The server configuration is complete! You created a properties file containing custom strings for your widget. Youthen configured the new resource bundle in IBM Connections. Afterwards, you configured the widget for theCommunities application. Finally, you learned how to configure the AJAX Proxy for a widget.

Now that you've made all of these changes, you must restart the application for them to take effect.

Step 34 Return to your wsadmin session. Restart the Communities application with the following commands:

appManager=AdminControl.queryNames(“cell=connectionsCell01,node=connectionsNode01,type=ApplicationManager,process=IC_server1,*”)

AdminControl.invoke(appManager, “stopApplication”, “Communities”)

AdminControl.invoke(appManager, “startApplication”, “Communities”)

exit

Step 35 Close all terminal windows (except for the Domino server window).

PREPARE A PROJECT USING THE ECLIPSE IDE

In the following steps, you will create a new project using the Eclipse IDE. You will learn how to create a basiciWidget. You will also learn how to display this iWidget in the IBM Connections Communities application.

Step 36 On the desktop, double-click the “Eclipse” icon to start the Eclipse IDE.


9


Step 37 In the Workspace Launcher window, you will select a location for your development workspace.Enter the following information and click OK.

Field Value

Workspace /labs/workspaces/connections_web

Step 38 If you see the Welcome page, click the “Go to the Workbench” button.

Step 39 From the Eclipse file menu, choose File → New → Project...

Step 40 In the New Project dialog window, choose Web → Static Web Project. Click Next.

Step 41 Enter the following information and click Finish.

Field Value

Project name ecod.iwidgets.communities

Step 42 If asked to open a Web perspective, click Yes.


10


Step 43 From the Eclipse top menu bar, click Window → Preferences

Step 44 Expand General → Editors → Text Editors

Step 45 On the right, place a check next to the option “Show line numbers” and click OK.

CREATE SOME IWIDGETS

In the following steps, you will create all of the necessary files for a fully functioning iWidget in the IBMConnections environment.

You will create the XML widget descriptor file that contains all of the important configuration information about thewidget. You will also create additional cascading style sheets (CSS) and JavaScript (js) files to support thewidget.

Step 46 Create the XML widget descriptor files. These files will correspond to the values you entered earlier in widgets-config.xml. In the Eclipse project, right-click the “WebContent” folder in the new project and select New → File

Step 47 In the New File window, enter the following information and click Finish.

Field Value

File name ecodCommPal.xml

Step 48 At the bottom of the XML text editor, make sure the “Source” tab is selected.

Step 49 Paste the following XML fragment at line 1.

<iw:iwidget id="com.ibm.ecod.comm.pal" iScope="com.ibm.ecod.comm.pal" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" supportedModes="view" mode="view" lang="en" allowInstanceContent="true">

<iw:resource uri="http://connections.demos.ibm.com/widgets/ecod.css" />

<iw:content mode="view"><![CDATA[

<span class=”color1”>Hello World!</span>]]>

</iw:content>

</iw:iwidget>


11


Step 50 Refer to the following table for a description of each XML tag and attribute

Tag Attribute Description

iw:iwidget id Unique ID

supportedModes Define the actions a user will be able to take on the widget

iScope The name of the JavaScript class containing widget logic

iw:resource uri URL for additional files required for the widget

iw:content mode The initial HTML to use when a user enters a view mode

Step 51 Click Save.

Step 52 In the Project Explorer, right-click the file “ecodCommPal.xml” and choose Copy.

Step 53 In the Project Explorer, right-click the WebContent folder and choose Paste.

Step 54 In the Name Conflict window change the name to “ecodCommCol1.xml” and click OK.

Step 55 Repeat the previous steps to create the following files:

ecodCommCol2.xml

ecodCommCol3.xml

Step 56 Double-click “ecodCommCol1.xml” to open it in the editor. In the “iw:iwidget” tag, update the following attributes as below:

id=”com.ibm.ecod.comm.col1”

iScope=”com.ibm.ecod.comm.col1”

Step 57 Click Save.




Step 59 Click Save.


12





Step 61 Click Save.

Step 62 Double-click “ecodCommPal.xml” to open it in the editor. On line 6, add one blank line so that lines 6.7 are blank. At line 6, add an additional iw:resource tag to pull in a custom JavaScript file.

<iw:resource uri=”http://connections.demos.ibm.com/widgets/ecodCommPal.js”/>

Step 63 When finished, the file should look as follows:

Step 64 Click Save.

Step 65 Create a CSS file that will be used by the widgets. In the Eclipse project, right-click the “WebContent” folder and select New → File


Field Value

File name ecod.css

Step 67 Paste the following style rule. It should match the CSS class you entered as part of the initial view mode in the XML descriptor file.

.color1 {color: red;

}

Step 68 Click Save.


13


Step 69 Create a JavaScript file to contain the widget logic. In the Eclipse project, right-click the “WebContent” folder and select New → File


Field Value

File name ecodCommPal.js

Step 71 In ecodCommPal.js, paste the following JavaScript code at line 1.

dojo.provide("com.ibm.ecod.comm.pal");dojo.declare("com.ibm.ecod.comm.pal", null, {

constructor: function() {

},onLoad: function() {

},onView: function() {

}});

Step 72 The code in the previous step is a declaration of a Dojo class. The “dojo.provide” and “dojo.declare” lines are defining a class with the iScope name from the XML widget descriptor. As you'll recall, the iScope class is the class that will contain the widget logic. “onLoad” and “onView” are two Dojo functions you can use to contain the logic for each supported view modein the widget.

Step 73 Click Save.

Step 74 You now have everything in place for a Hello World iWidget! The next step is to place the widget files on the HTTP server that was configured for in earlier steps. In this lab, you will place your exercises on the IBM HTTP server used by IBM Connections. In a terminal window,create a “widgets” directory with the following commands:

cd /opt/IBM/HTTPServer/htdocs

mkdir widgets

cd widgets

Step 75 Copy the entire contents of the “WebContent” folder in your Eclipse workspace to this new directory on the IBM HTTP Server with the following commands (Note: The line ends in a “space” followed by a “period”!):

'cp' -rf /labs/workspaces/connections_web/ecod.iwidgets.communities/WebContent/* .

Step 76 Leave this terminal window open. You can reuse it in future steps to recopy files and leverage the Linux history feature (press the UP/DOWN key(s) to cycle through the command history) and not have to retype the command each time.


14


Step 77 In a web browser, navigate to URL: http://connections.demos.ibm.com/communities/service/html/mycommunities

Step 78 Log in with the following credentials

Field Value

User name dmisawa

Password passw0rd

Step 79 Click the Start a Community button

Step 80 Create a new Community with the following information. When finished, click Save.

Field Value

Name IC Widget Development

Web Address icwidget

Access Public - anyone can join

Description Widget development demo

Step 81 The new community should automatically open once provisioned.

Step 82 On the left side of the page, you should see your mandated widget in column 1 below the Tags widget. You may need to scroll down to see it.

Step 83 In the middle of the page, you should see your mandated widget in column 2 below the Community Description widget.


15


Step 84 On the right side of the page, you should see your mandated widget in column 3 below the Members widget.

Step 85 In the upper right, click the Community Actions drop-down button and select Customize.

Step 86 In the widget palette, you should see your new iWidget!

Step 87 Mouse over the widget to view the description.

Step 88 Click the plus sign (+) to add the widget to the page.

Step 89 Close the widget palette. Leave the browser open to this page.


16


EXPLORE THE IWIDGET APIS

In this section, you will learn how to perform some common iWidget development tasks. For example, you willretrieve information about the currently logged in user, retrieve configuration data from widgets-config.xml, andload strings from your resource bundle. Finally, you'll also learn how to use Dojo to perform some simple AJAXrequests.

Step 90 Return to the Eclipse IDE and open ecodCommPal.xml. Remove the existing “Hello World!” code by deleting the content between the CDATA tags. When finished, your XML descriptor should look like the following image. Click Save.

Step 91 Open ecodCommPal.js. You can use the iContext to obtain information about available variables. Some variables are provided by the widget framework, while others were provided by you in widgets-config.xml. Add the following code to the onView function (between the {} brackets).

var elem = this.iContext.getRootElement();var list = dojo.create("ul", {}, elem);

var attrs = this.iContext.getiWidgetAttributes();var entries = attrs.getAllNames();

for (var x=0; x < entries.length; x++) {var val = entries[x] + " = " + attrs.getItemValue(entries[x]);dojo.create("li", {"innerHTML": val}, list);

});

Step 92 Click Save.

Step 93 Copy the entire contents of the “WebContent” folder in your Eclipse workspace to this new directory on the IBM HTTP Server with the following commands. If you use the same terminal window you used before, you can press the UP arrow to retrieve the command from the history.(Note: The line ends in a “space” followed by a “period”!):

'cp' -rf /labs/workspaces/connections_web/IDR-IWIDGETS/WebContent/* .


17


Step 94 In the web browser, refresh the page to view the new output of the iWidget. Notice that in contains information about the current Community as well as the ItemSet variables you added to widgets-config.xml.

Step 95 Return to the Eclipse IDE and ecodCommPal.js. In most circumstances, you won't want to loop through every available variable. Instead, you'll probably want to pull individual values as needed. Replace the existing onView function with the following code.

var elem = this.iContext.getRootElement();

var attr = this.iContext.getiWidgetAttributes().getItemValue("attr1");elem.innerHTML = attr;

Step 96 Click Save.

Step 97 Using the same steps as before, copy the entire contents of the “WebContent” folder in your Eclipse workspace to the IBM HTTP Server.

Step 98 In the web browser, refresh the page to view the new output of the iWidget.


18


Step 99 Return to the Eclipse IDE and ecodCommPal.js. In some scenarios, you will want to obtain information about the currently logged in user. For example, you might want to display a welcome message to the user. You may even want to obtain the user's e-mail address so that you can pull relevant information from another back-end system. Replace the existing onView function with the following code.

var elem = this.iContext.getRootElement();var list = dojo.create("ul", {}, elem);

var entries = new Array("displayName","email","userid");

for (var x=0; x < entries.length; x++) {var val = entries[x] + " = " + this.iContext.getUserProfile().getItemValue(entries[x]);dojo.create("li", {"innerHTML": val}, list);

}

Step 100 Click Save.


Step 102 In the web browser, refresh the page to view the new output of the iWidget.

Step 103 Return to the Eclipse IDE and ecodCommPal.js. In some scenarios, you will want to persist data across user sessions. For example, you may want to cache a username, password, token, etc. that gets passed back to a 3rd party system. Replace the existing onView function with the following code:

var elem = this.iContext.getRootElement();

var attrs = this.iContext.getiWidgetAttributes();

dojo.create("div", {"id": "givenname"}, elem);dojo.byId("givenname").innerHTML = attrs.getItemValue("givenname");

attrs.setItemValue("givenname","Dan");attrs.save();

Step 104 Click Save.



19


Step 106 In the web browser, refresh the page to view the new output of the iWidget. You should initially see nothing (since the “givenname” value has not yet been set and saved by the last 2 lines of code).

Step 107 Refresh the page again. Now that your last 2 lines of code has saved the “givenname” information to the iWidget persistent store, the first few lines of code should now be able to retrieve this information and display it to the user.

Step 108 This data will persist across browser sessions, the clearing of the browser cache, and even IBM Connections server restarts!

Summary:

In this lab, you learned how to configure an IBM Connection server for custom iWidgets. These tasks includecreation of a resource bundle, configuration of the widgets on the server, and configuration of the AJAX Proxy. Inaddition to the administrative tasks, you also tested some sample code to demonstrate some of the commonscenarios and information requested by an iWidget.

Now that you have this new knowledge, you can begin building custom iWidgets to integrate your application intoIBM Connections today!


20

Software

IBM Connections iWidget Development - Communities