IBM Connections Share Box Integration

Social Business Application Development Workshop

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


Lab Manual

IBM Connections Share Box Integration

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_files solutions located at:

/labs/solutions/ecod.sharedlg

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

1


Introduction:IBM Connections provides a quick way to share content with others. From anywhere in IBM Connections, users can click Share to share a status message or a file. To enable an opensocial gadget to surface in the Share dialog you need to specify feature requirements in the gadget xml and add the gadget using theAdministration option on the Home page.

You can create your own gadgets and add them to the Share dialog. In this context, your gadgets should probably allow a user to share content with other users, but you can add anything.

You can optionally add the following features to your gadget:

• A feature to close the share dialog from the gadget, for example allowing you to add a Close button to your gadget that closes the dialog.

• A feature to inform the dialog of a submit state, for example allowing you to show a progress indicator while something is being submitted.

Description:In this lab, you will be using the Eclipse IDE to to create a new OpenSocial gadget. You will then learn how to deploy the gadget into the IBM Connections Share dialog. Finally, you will learn some of the APIs and callbacks available to the Share dialog.

Objective:This lab will explain the following tasks:

Creating a Share dialog OpenSocial gadget

Deploying a Share dialog OpenSocial gadget

How to implement APIs and callbacks specific to a Share dialog gadget


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.

REVIEW THE DEFAULT SHARE DIALOG

The Share dialog in IBM Connections allows you to share a status update or a file from any application or contextin IBM Connections. In this lab, you will learn how to add additional actions to the Share dialog. However, beforeyou begin, you should review the default Share dialog included in IBM Connections.

Step 4 In a web browser, navigate to URL: http://connections.demos.ibm.com/homepage

Step 5 Log in with the following credentials

Field Value

User name dmisawa

Password passw0rd

Step 6 In the top right corner of the page, click the Share box to open the Share dialog.


3


Step 7 This should open the Share dialog. As you can see under the “Share Something” heading, there is a list of clickable actions the end user can take to share various things in IBM Connections. IBM Connections provides two out-of-box actions: performing a status update and sharing Files.

Step 8 By default, the dialog will load on the “Status Update” tab. Click the “Files” tab to view available actions for working with your files. Feel free to experiment with both options to see how the Share dialog works. When finished, close the Share dialog and Log Out of IBM Connections.

CONFIGURE A HOME PAGE ADMINISTRATOR

To make the Open Social gadgets available for use in the Activity Stream, you need to add the gadgets from theAdministration tab in the Home page user interface and then enable them for use.

Note: Depending on which labs you have already finished, you may have already completed the steps in thissection. If so, you may proceed to the next section.

Step 9 In a web browser, navigate to URL: https://connections.demos.ibm.com:9043/ibm/console

Step 10 Log in with the following credentials

Field Value

User name wasadmin

Password passw0rd

Step 11 On the left, select Applications → Application Types → WebSphere enterprise applications


4


Step 12 On the right, click the link for Homepage

Step 13 Under the Detail Properties section, click the Security role to user/group mapping link.

Step 14 On the next page, place a check beside “admin” and click Map Users...

Step 15 In the Search and Select Users section, search for “dmisawa” and click Search.


5


Step 16 From the Available list, highlight “DMisawa” and click the right arrow to move his name to the Selected list. When finished, the Selected list should look as follows:

Step 17 Click OK. You should see “DMisawa” under the mapped users for the admin role.

Step 18 Click OK again. When you return to the Homepage Configuration page, click the Save link at the top.

Step 19 Click Logout to exit the Integrated Solutions Console.

CONFIGURE NEW OPENSOCIAL GADGETS FOR IBM CONNECTIONS

The Share dialog in IBM Connections uses OpenSocial gadgets to render the content. In order to use an externalOpenSocial gadget in IBM Connections, it will have to be registered with the system by an administrator.

In this example, a user has already been defined as a “Home Page administrator”.

Step 20 In a web browser, navigate to URL: http://connections.demos.ibm.com/homepage

Step 21 (If prompted, accept the certificate) Log in with the following credentials

Field Value

User name dmisawa

Password passw0rd

Step 22 On the left, select the Administration link.


6


Step 23 On the right, under the “Disabled widgets” section, click the Add another widget button.

Step 24 In later steps, you will be creating a new OpenSocial gadget. Enter the following information for the gadget so that it is registered in IBM Connections.

Field Value

Widget Type Open Social Gadget

Security Trusted

Use SSO <checked>

Show in Share dialog after the gadget <checked>; Then, choose “Files Share” in the drop-down list

Server access via Proxy All servers

Widget Title ICS EcoD Share Dialog

URL Address http://connections.demos.ibm.com/gadgets/ecodShare.xml

Step 25 Scroll to the bottom and click Save.

Step 26 In the “Disabled widgets” section, highlight the ICS EcoD Share Dialog entry.

Step 27 Underneath the “Disabled widgets” section, click Enable.

Step 28 Leave the browser open on the current page and proceed to the next section.


7


PREPARE A PROJECT USING THE ECLIPSE IDE

The Eclipse IDE for Java EE Developers is free and contains tools for creating Web applications, includingeditors for JavaScript, HTML, CSS, and XML. Best of all, this IDE is free to use. Visit www.eclipse.org/downloads for more information.

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

Step 30 In the Workspace Launcher window, you will select a location for your development workspace.A workspace is a development profile that contains your projects, folders, files, and settings. Enter the following information and click OK.

Field Value

Workspace /labs/workspaces/connections_web

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

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

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


8

http://www.eclipse.org/downloads


Step 34 Enter the following information and click Finish.

Field Value

Project name ecod.sharedlg

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

Step 36 From the Eclipse file menu, click Window → Preferences

Step 37 Expand General → Editors → Text Editors

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

CREATE AN OPENSOCIAL GADGET

The IBM Connections Share dialog extensions are implemented via OpenSocial gadgets. In this section, you willcreate the framework for a Hello World OpenSocial Share Box gadget.

Step 39 In the Eclipse IDE, expand the current project. You can find the project on the left in the Project Explorer.

Step 40 Create a new HTML file. In the Eclipse project, right-click the “WebContent” folder and select New → File

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

Field Value

File name ecodShare.xml


9


Step 42 At the bottom of the XML editor, click the Source tab. Paste the following XML code into the file on line 1. This XML includes all of the minimum requirements for a Share dialog gadget. A description of the code can be found in the following steps.

<?xml version="1.0" encoding="UTF-8" ?><Module><ModulePrefs title="Hello World Share Dialog">

<Require feature="ibm.connections.sharedialog"/><Require feature="dynamic-height"/><Require feature="views"/><Require feature="actions">

<Param name="action-conributions"><![CDATA[

<actions><action id="ecod.share" path="container/sharebox"

label="Hello World" tooltip="Tooltip text" /></actions>

]]></Param>

</Require></ModulePrefs><Content type="html" view="default">

<![CDATA[<b>Share Dialog OpenSocial Gadget!</b>

]]></Content></Module>

Step 43 Click Save.

Step 44 Refer to the following table for a description of the code:

Lines Description

3 Serves as a container element for all Metadata and Features

4 – 7 Required features for a Share dialog gadget

7 – 16 Defines this gadget as a Share dialog specific gadgetAction tag attributes:

• id = unique, will be referenced in future callbacks• path = will render the gadget in the Share dialog• label = text that appears on the gadget tab• tooltip = text that appears when hovering over the gadget tab

18 Contains the views that will be rendered to the user


10


Step 45 You now have everything in place for a Share Dialog Gadget! The next step is to place the gadget 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 “gadgets” directory with the following commands:

cd /opt/IBM/HTTPServer/htdocs

mkdir gadgets

cd gadgets

Step 46 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.sharedlg/WebContent/* .

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

Step 48 Return to the web browser and click the “I'm Following” link on the left.

Step 49 On the right side of the page, click the Share button.

Step 50 You should now see your Hello World gadget in the Share dialog! Hover over the Hello World tab to view the tooltip text. Click the Hello World link to view the gadget.


11


Step 51 When finished, close the Share dialog.

EXPLORE THE SHARE DIALOG CALLBACKS

In this section, you will learn how to perform some common Share dialog development tasks. For example,registering a callback for when your gadget is clicked.

Step 52 Return to the Eclipse IDE. After line 20, add a blank line so that line 21 is blank. When finished, your code should look like the following:

Step 53 You will probably want to perform some initialization routines once the gadget has loaded. TheOpenSocial specification has a callback available that you can use to be notified when the gadget has finished loading. Beginning at line 21, add the following code in the CDATA sectionof ecodShare.xml.

<p/><div id="data"></div><script type="text/javascript">

var elem = document.getElementById("data");var count = 0;

function output(str) {var div = document.createElement("div");div.innerHTML = str;elem.appendChild(div);gadgets.window.adjustHeight();

}

function init() {output("Init called");

}

gadgets.util.registerOnLoadHandler(init);</script>

Step 54 Click Save. Refer to the following table for a description of the code:

Lines Description

22 Target DIV for output statements

25 A variable for demonstrating gadget state and callbacks

27 – 32 Generic function to output statements to the UI

31 After modifying the DOM you should readjust the gadget size

34 – 36 Function to be called when the gadget loads

38 Register the callback for when the gadget loads


12


Step 55 Return to the terminal window where you entered the copy command and leverage the Linux command history feature to recopy the files to the IBM HTTP Server.

Step 56 Return to the web browser and refresh the page. Open the Share dialog and click on the HelloWorld tab. You should see the following displayed:

Step 57 Close the Share dialog and return to the Eclipse IDE.

Step 58 Next, you will want to implement a callback so that you know when your gadget has been selected by the end user. Replace the contents of the existing “init” function with the following code to register this callback.

output(“Init called”);var customAction = { id: "ecod.share", callback: updateContext };gadgets.actions.updateAction(customAction);

Step 59 You will now need to implement the “updateContext” function associated with this callback. At line 39, add 2 blank lines so that lines 39,40,41 are blank. At line 40, add the following code forthis function:

function updateContext(selection) {if (selection.type == "com.ibm.social.sharebox.context") {

output("UpdateContext called " + count++);}

}

Step 60 Click Save. Refer to the following table for a description of the code:

Lines Description

36 – 37 Defines a callback. The ID must match the ID defined on line 11

40 Function to be called when the gadget is selected by the user

41 Verifies that this selection came from the Share dialog

42 General output statement, leverages the “count” variable



13


Step 62 Return to the web browser and refresh the page. Open the Share dialog and click on the HelloWorld tab. You should see the following displayed:

Step 63 Click the Files tab. Click the Hello World tab and view the output. Close the Share dialog. Open the Share dialog and (if not already selected) click the Hello World tab again. Review the output. You should see the following:

Step 64 As you can see, your new gadget will maintain it's state unless the page is refreshed or you navigate to a new page. The registered callback will be fired when the gadget first loads, whenthe tab is clicked, or when the Share dialog is closed and reopened.

Step 65 (Optional: Repeatedly alternate clicking the Files tab and the Hello World tab to output additional statements. The gadget window will resize itself as additional content is written to the DOM thanks to your window adjustment code on line 31.)

Step 66 Close the Share dialog and return to the Eclipse IDE.

Step 67 Next, you will want to implement code to return the gadget to it's default state after the Share dialog window has been closed. You can do this by registering an additional callback to catch this event. Add two blank lines at the end of the “init” function so that lines 38,39 are blank. At line 39, add the following code. When finished, click Save.

ibm.connections.sharedialog.registerCloseListener(function() {count = 0;

});


14



Step 69 Return to the web browser and refresh the page. Open the Share dialog and click on the HelloWorld tab. Click the Files tab. Click the Hello World tab again. You should see the count variable incrementing like before as the gadget selection callback is continually fired.

Step 70 Now, close the Share dialog to invoke your new callback function that catches the close event. As you'll recall, it should set the count variable back to zero. Reopen the Share dialog, click the Hello World tab (if it is not already selected) and review the results.

Step 71 Close the Share dialog. Return to the Eclipse IDE.

Step 72 Finally, the whole purpose of the Share dialog is to share content. When you build your OpenSocial gadget, you will construct a UI that allows the user to perform some type of action and share some type of data. If you just close the Share dialog when this event occurs, the user may or may not know whether he/she has performed a successful action. You can post messages to the user directly in the IBM Connections UI to notify the user of success or failure.


15


Step 73 For lab brevity, rather than construct a new UI to demonstrate this capability, we will just add it to the callback you have already written that catches the Share dialog close events. At the endof this callback, add two blank lines so that lines 41,42 are now blank. At line 42, add the following code to display a “success” message to the user.

ibm.connections.sharedialog.displayMainPageMessage(ibm.connections.sharedialog.MessageTypeParam.SUCCESS,"The content was successfully shared."

);

Step 74 Click Save. When finished, the code block should look like the following image:


Step 76 Return to the web browser and refresh the page. Open the Share dialog and click on the HelloWorld tab so that your “init” function is fired and your callback that displays the message is registered. Now, close the Share dialog to see the message in the IBM Connections UI.


16


Step 77 (Optional) Repeat the previous steps but replace the message code with the following code, recopy the files to the IHS server, reload the page, and close the Share dialog to see an error message.

ibm.connections.sharedialog.displayMainPageMessage(ibm.connections.sharedialog.MessageTypeParam.ERROR,"There was an error sharing this content."

);

Step 78 (Optional) Repeat the previous steps but replace the message code with the following code, recopy the files to the IHS server, reload the page, and close the Share dialog to see an informative message.

ibm.connections.sharedialog.displayMainPageMessage(ibm.connections.sharedialog.MessageTypeParam.INFO,"Here is some information about your shared content."

);

Summary:

In this lab, you learned how to extend the IBM Connections Share dialog with a custom OpenSocial gadget. Youalso learned how to register some of the more common callbacks associated with the Share dialog lifecycle.Next, you should begin exploring the OpenSocial APIs and integrating your own application into the Share dialog!


17

Software

IBM Connections Share Box Integration