IBM Connections 5 iWidget Development - Profiles

IBM Connections 5.0 Workshop

Author: Paul GodbyIBM Ecosystem DevelopmentLast Updated: July 3, 2014Duration: 60 minutes

IBM Connections Workshop

Lab Manual

IBM Connections iWidget Development

Profiles

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.profiles

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 Profiles


2


Procedure:

SETUP

Step 1 Review the workshop setup document for instructions on how to ensure all required servers have been started on your SoftLayer device.

Step 2 You may choose to complete this lab on your local machine. However, the instructions will assume you are working locally on the SoftLayer device using a VNC client.

Step 3 Important! Any time you open a new terminal window (Applications → System Tools → Terminal), you should first enter the following commands to switch to the root user. All of the steps documented in this lab will assume you are running with root privileges!

su – root

(Enter <<SSH Password>>)

CREATE A STRINGS RESOURCE BUNDLE

IBM Connections provides a external resource bundle loader for adding and updating strings to Profiles,Communities, and the Home page. This will allow you to add custom strings or modify existing strings whenperforming certain tasks in IBM Connections, without having to update product resource files.

You can create a properties file to contain custom user interface (UI) strings for your widgets. This will allow youto update your UI without modifying the underlying code. In addition, the use of a string bundle will allow you toprovide a custom title for your widget in the page.

Step 4 In a new terminal window, create a new strings properties file in the IBM Connections customization directory with the following commands:

cd /opt/IBM/Connections/data/shared/customization/strings

gedit ecod.iwidgets.properties

Step 5 When the new text file opens, enter the following lines. As you can see, you will be providing a key-value pair that will be used to provide user friendly display text for your widget titles.

ecodProfCol1=EcoD Col 1ecodProfCol3=EcoD Col 3ecodProfTab=EcoD Tab

Step 6 Save the file but do not close it (yet!). You just created the default properties file used by server processes. The browser will require a separate properties file for each language code supported in your environment. In this particular case, you will need to create a second properties file for the language used in your current browser. The example below will be for theEnglish language. From the file menu, choose File → Save As

Step 7 Save the file in the same directory, with the same filename, but append “_en” to the end of the file name (but before the extension).

ecod.iwidgets_en.properties


3


Step 8 Close the text editor. Proceed to the next section.

REGISTER A RESOURCE BUNDLE

You must make IBM Connections aware of your new strings by registering a resource bundle inLotusConnections-config.xml. This will force IBM Connections to load your string bundle and to make it availableto your widget.

Step 9 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 iBmC0nn3ti0ns

execfile(“connectionsConfig.py”)

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

Step 10 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/LotusConnections-config.xml

Step 11 You will need to add a new resource bundle. Click Search → Find... In the Search for: field, type: <resources> and click Find. After you find the section, you can hit Close in the Find dialog window.

Step 12 Between the resources tags, you will need to add your new bundle. Enter the following XML fragment. The “name” attribute will be the name of your strings properties file, minus the extension. The “prefix” is an internal ID you will use elsewhere in the configuration to referencethis bundle.

Note: If you see other resources already listed, leave them in place and just add your new resource!

<widgetBundle prefix="ecodWidgets" name="ecod.iwidgets" />

Step 13 Save and close the file. Close the text editor.


4


Step 14 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 :)

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

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

CONFIGURE PROFILES WIDGETS

To make custom widgets available for use in Profiles, you need to configure the widgets in the widget definitionfile, 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 16 Return to your existing wsadmin session and check out the Profiles configuration file with the following commands:

execfile(“profilesAdmin.py”)

ProfilesConfigService.checkOutWidgetConfig("/config","connectionsCell")


gedit /config/widgets-config.xml

Step 18 You will need to add entries describing your widgets. Click Search → Find... In the Search for: field, type: resource type=”profile” and click Find.

Step 19 After you find the section, you can hit Close in the Find dialog window.


5


Step 20 Scroll to the bottom of the definitions section (Alternatively, search for: </definitions>). Add a new definition for each of your planned custom widgets. (Note: Don't forget to update the hostname for your SoftLayer device!!!)

<widgetDef defId="ecodProfCol1" bundleRefId="ecodWidgets" url="http://<<Host Name>>/widgets/ecodProfCol1.xml"></widgetDef>

<widgetDef defId="ecodProfCol3" bundleRefId="ecodWidgets" url="http://<<Host Name>>/widgets/ecodProfCol3.xml"></widgetDef>

<widgetDef defId="ecodProfTab" bundleRefId="ecodWidgets" url="http://<<Host Name>>/widgets/ecodProfTab.xml"></widgetDef>

Field Value

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

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

url The location of the XML descriptor file for the iWidget

Step 21 When finished, you should see the following definitions:

Step 22 In order to display widgets in columns 1, 2, 3, or the tabbed interface, there is an additional configuration step. You will need to define some mandated widget instances.

Step 23 Right below the definitions section in the XML file is the layout section. You will be placing widgets inside each Profile. So, you will add the following widget instances to the page with a pageId of “profilesView”:

<widgetInstance uiLocation="col1" defIdRef="ecodProfCol1"/>

<widgetInstance uiLocation="col3" defIdRef="ecodProfCol3"/>

<widgetInstance uiLocation="tabsWidget1" defIdRef="ecodProfTab"/>


6


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

Note: The order the widgets are listed in will be the order that they appear in IBM Connections. Since your widgetsare listed last, they will appear at the bottom of column 1 and 3. The tabs widget will be the last tab on the right.

Step 25 Click Save. Close the file. Close the text editor.

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

ProfilesConfigService.checkInWidgetConfig(“/config”,”connectionsCell01”)

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


7


CONFIGURE THE AJAX PROXY FOR PROFILES

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 28 First, you will need to make a copy of the default configuration file specifically for use with the Profiles application. In a new terminal window, enter the following commands:

cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/config/cells/connectionsCell/LotusConnections-config

cp proxy-config.tpl proxy-profiles-config.tpl

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

ProfilesConfigService.checkOutProxyConfig("/config","connectionsCell")


gedit /config/proxy-profiles-config.tpl

Step 31 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.


8


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

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

Step 34 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://<<Host Name>>/*" acf="none" basic-auth-support=”true”>

Step 35 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 36 When finished, the XML fragment should look like the following:

Step 37 Save and close the file. Close the text editor.


9


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

ProfilesConfigService.checkInProxyConfig("/config","connectionsCell01")

Note: If you get a permissions error (or an error of another type) during this process, then you will need to deletethe existing proxy-profiles-config.tpl file in directory

/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/config/cells/connectionsCell/LotusConnections-config

and repeat the check in command.

Step 39 All of the Profiles iWidget configuration changes have been made! Now, it's time to resynchronize the nodes to ensure all of the changes propagate. In order to save you some typing, and to potentially eliminate errors due to typos, we've provided a workshop script to automate this process for you. Enter the following commands:

execfile("/scripts/synchNodes.py")

Note: You can view the script, and the wsadmin commands it invokes, by opening a terminal window and issuingthe folowing command(s): gedit /scripts/synchNodes.py

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

RESTART THE PROFILES AND COMMON APPLICATIONS

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 theProfiles 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 41 In order for the server to pickup your new Profiles iWidgets, you will need to restart the Profiles application. In order for the server to pickup your strings resource bundle, you will need to restart the Common application. In order to save you some typing, and to potentially eliminate errors due to typos, we've provided a workshop script to automate this process for you. Enter the following commands:

sys.argv = ["Profiles", "Common"]

execfile("/scripts/restartApp.py")

Note: You can view the script, and the wsadmin commands it invokes, by opening a terminal window and issuingthe folowing command(s): gedit /scripts/restartApp.py


10


Step 42 Terminate the wsadmin session with the folowing command(s):

AdminConfig.save()

quit

Step 43 Close all terminal windows.

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 Profiles application.

Step 44 In a terminal window, enter the following commands to start Eclipse:

/labs/eclipse/eclipse

Step 45 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 46 If you see the Welcome page, click the “Go to the Workbench” button.

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

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


11


Step 49 Enter the following information and click Finish.

Field Value

Project name ecod.iwidgets.profiles

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

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

Step 52 Expand General → Editors → Text Editors

Step 53 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 54 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 55 In the New File window, enter the following information and click Finish.

Field Value

File name ecodProfCol1.xml

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


12


Step 57 Paste the following XML fragment at line 1. (Note: Make sure to update your host name!!!)

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

<iw:resource uri="http://<<Host Name>>/widgets/ecod.css" />

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

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

</iw:content>

</iw:iwidget>

Step 58 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 by the widget

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

Step 59 Click Save.

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

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

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

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

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


13

http://connections.demos.ibm.com/widgets/ecod.css


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

id=”com.ibm.ecod.prof.col3”

iScope=”com.ibm.ecod.prof.col3”

Step 66 Click Save.

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

id=”com.ibm.ecod.prof.tab”

iScope=”com.ibm.ecod.prof.tab”

Step 68 Click Save.

Step 69 Create a CSS file that will be used to support the widget. In the Eclipse project, right-click the “WebContent” folder and select New → File


Field Value

File name ecod.css

Step 71 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 72 Click Save.

Step 73 You now have everything in place for a Hello World iWidget(s)! 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 74 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.profiles/WebContent/* .


14


Step 75 In a web browser, navigate to URL: http://<<Host Name>>/profiles/html/myProfileView.do

Note: In this lab, you only configured HTTP in the Ajax Proxy (not HTTPS). So, make sure you are using HTTPin the above address or you might experience some loading errors.

Step 76 Log in with the following credentials

Field Value

User name dmisawa

Password passw0rd

Step 77 On the left side of the page, you should see your mandated widget in column 1 below the Tags widget.

Step 78 On the right side of the page, you should see your mandated widget in column 3 below the My Links widget.


15


Step 79 Finally, in the middle of the page, you should see a new tab in the tabbed interface with your new widget. Click EcoD Tab to see your widget.

Step 80 Notice that, in each case, the title of the widget in the user interface is the title you configured inthe strings resource bundle file!

Step 81 Hooray! You're finished (maybe)!

(OPTIONAL) 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 82 Return to the Eclipse IDE and open ecodProfTab.xml. Remove the existing “Hello World!” codeby deleting the content on line 9. When finished, your XML descriptor should look like the following image. Click Save.

Step 83 You will use an external JavaScript file to contain the application logic. So, you will need to addan additional resource tag. At line 4, add 1 blank line so that lines 4,5 are blank. At line 5, add the following resource tag: (Note: Make sure to update your host name!!!)

<iw:resource uri="http://<<Host Name>>/widgets/ecodProf.js" />


16

http://connections.demos.ibm.com/widgets/ecodProf.js


Step 84 When finished, your XML should look like the following:

Step 85 Click Save.

Step 86 Create a JavaScript file that will be used to support the widget. In the Eclipse project, right-click the “WebContent” folder and select New → File


Field Value

File name ecodProf.js

Step 88 In ecodProf.js, paste the following JavaScript code at line 1.

dojo.provide("com.ibm.ecod.prof.tab");dojo.declare("com.ibm.ecod.prof.tab", null, {

constructor: function() {

},onLoad: function() {

},onView: function() {

}});

Step 89 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 90 Click Save.


17


Step 91 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 attrs = this.iContext.getiWidgetAttributes();

var attrNames = attrs.getAllNames();var root = this.iContext.getRootElement();

var list = dojo.create("ul", {}, root);for (var x=0; x < attrNames.length; x++) {

dojo.create("li", {"innerHTML": attrNames[x]}, 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 (Note: The line ends in a “space” followed by a “period”!):

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

Step 94 Return to the browser, refresh the page, and click the EcoD Tab tab.

Step 95 Return to the Eclipse IDE and ecodProf.js. Now that you know how to obtain the possible available variables to your widget, you will probably want to obtain the values for each of those variables. Replace the existing onView function with the following code.

var attrs = this.iContext.getiWidgetAttributes();

var attrNames = attrs.getAllNames();var root = this.iContext.getRootElement();


var val = attrs.getItemValue(attrNames[x]);dojo.create("li", {"innerHTML": attrNames[x] + " = " + val},

list);}


18


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 99 Return to the Eclipse IDE and ecodProf.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 attr = this.iContext.getiWidgetAttributes().getItemValue("profileDisplayedUserKey");

var root = this.iContext.getRootElement();root.innerHTML = attr;

Step 100 Click Save.




19


Step 103 Return to the Eclipse IDE and ecodProf.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 attrNames = new Array("displayName", "email", "userid");

var root = this.iContext.getRootElement();


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

}

Step 104 Click Save.



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.

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

Access FREE education on the IBM Collaboration Solutions portfolio of products today!

1. Visit the IBM Greenhouse and create a free account.

Link → http://greenhouse.lotus.com/

2. Visit the IBM Collaboration Solutions Ecosystem Development Community

Link → https://greenhouse.lotus.com/communities/community/icsecod

3. Learn new skills and share these links with your friends and colleagues!


20

https://greenhouse.lotus.com/communities/community/icsecod

http://greenhouse.lotus.com/

Date post:	11-May-2015
Category:	Software
Upload:	paul-godby
View:	1,214 times
Download:	4 times

IBM Connections 5 iWidget Development - Profiles

Software