ibm connections iwidget development

© 2014 IBM Corporation

iWidget DevelopmentIBM Connections 5.0 Workshop

Author: Paul GodbyIBM Ecosystem DevelopmentDuration: 45 minutes

Agenda

● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication

Overview

● Definition, according to the iWidget 1.0 specification:● “A browser-oriented component, potentially extending a server-side component,

that provides either a logical service to the page or a visualization for the user (normally related to a server-side component or a configured data source).”

● An iWidget is a basic building block for adding new features to IBM Connections● Use iWidgets to socialize and integrate your applications into IBM Connections● Custom iWidgets can be added to: Home Page, Profiles, and Communities● Comprised of the following components

● XML widget descriptor● JavaScript files (optional)● CSS files (optional)

iWidgets vs OpenSocial Gadgets

iWidget OpenSocial Gadget

Activity Streams * X

Share Dialog X

Home Page X X

Profiles X

Communities X

Rendering inline iFrame

Specification iWidget 1.0 OpenSocial 2.0

● Recommendation: Use an OpenSocial Gadget when possible● Provides better integration and code reuse opportunities with other products

– Example: IBM Notes / Domino 9

* Available in the following applications: Home Page, Profiles, Communities

Agenda

● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication

XML widget descriptor

● Placed on any HTTP server

Tag Attribute Description

iw:iwidget id Unique identifier

supportedModes View modes supported by the widget

mode Default view mode to use

iScope Name of the JavaScript instance

iw:resource uri Links to additional JavaScript or CSS files

iw:content mode Default HTML to use when a view is loaded

Resource bundle

● A .properties file that defines UI strings for the application● Create a text file and give it a name unique to your application

● Example: com.ibm.idr.exercise1.properties● Place the file in the “strings” folder of the shared customization directory● Add key / value string pairs for the widget title and description

● Overrides the default values generated by the iWidget framework● Add additional key / value string pairs as appropriate for the application

LotusConnections-config.xml

Tag Attribute Description

widgetBundle name ● Name of the resource bundle containing your strings

● Corresponds to the name of the file placed in the strings customization directory

prefix ● Unique ID of the bundle in Connections● Used for later references to the bundle

● Define any custom resource bundles used

widgets-config.xml

Tag Attribute Description

widgetDef defId ● Unique identifer● The key in the properties file for the title

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

bundleRefId ● Name of resource bundle to load● Bundle was defined in LotusConnections-config.xml

url Location of the XML descriptor for the iWidget

itemSet item name Name for a predefined attribute

value Value for the predefined attribute

● Inform IBM Connections about the widget and where to find it● Provide configuration information in the form of ItemSets

Putting all of the components together

Agenda

● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication

Common iWidget deployment tasks

● Optional tasks● Create a resource bundle

– Contains UI strings such as the title, description, labels, etc.

● Register the resource bundle in IBM Connections (required, if using bundles)– Tell Connections to load the bundle and where to find it

● Configure the AJAX Proxy– Only required if the widget makes AJAX requests to other servers/ports

● Required tasks● Create the widget XML descriptor file

– Contains details about your widget, including pointers to additional resources to load

Configure the AJAX proxy

● If your application will make AJAX requests to other servers...

● Navigate to the “LotusConnections-config” directory

● Make a copy of proxy-config.tpl and rename it according to the IBM Connections application that will contain the widget

● Using wsadmin, check out/in the proxy-<app>-config.tpl file

● Add a new proxy rule for the HTTP server that will be hosting the iWidget

Home Page iWidget deployment

1) Declare Home Page administrator(s)

2) Home Page administrators can:● add/remove widgets● enable/disable widgets

3) End users can then customize their Home Page from the widget palette

Add/Remove Home Page widgets

● Use the Home Page administration UI to add/remove widgets

Enable/Disable Home Page widgets

iWidgets in the Home Page

Communities iWidget deployment

● In addition to the common tasks, register the widget in IBM Connections● Tell Connections about your widget and where to find the XML descriptor● Widget will appear in the widget palette (unless showInPalette=”false”)

● Optionally can configure mandated widgets● Define the UI location for the widget in the “layout” section of widgets-config.xml

Tag Attribute Description

widgetInstance uiLocation Defines the location of the widget on the page.Possible values: col1, col2, col3

defIdRef The widget definition to which this instance is bound.Maps to the “defId” attribute in the widget definition.

iWidgets in Communities

Profiles iWidget deployment

● In addition to the common tasks, register the widget in IBM Connections● Tell Connections about your widget and where to find the XML descriptor

● Define the UI location for the widget in the “layout” section of widgets-config.xml

Tag Attribute Description

widgetInstance uiLocation Defines the location of the widget on the page.Possible values: col1, col2, col3, or tabsWidget1

defIdRef The widget definition to which this instance is bound.Maps to the “defId” attribute in the widget definition.

iWidgets in Profiles

Agenda

● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication

iScope

● Defines the name of the instance of the JavaScript class● The class written by the widget developer that contains the widget logic

Lines Description

1 Tells Dojo a module has been provided with the given name (the iScope)

2 Dojo class declaration

4 Called once when class is instantiated

7 Called when iWidget is loaded

10 Called when iWidget mode is “view

13 Called when iWidget mode is “edit”

iContext

● An iContext instance is automatically provided for the iScope class● Used to interact with the iWidget framework● Provides access to

● DOM● I/O functions● Widget attributes● User attributes

● Important functions:● iContext.getRootElement()● iContext.getElementById()● iContext.getiWidgetAttributes()● iContext.getUserProfile()● iContext.io.rewriteURI()● iContext.iEvents.fireEvent()

ItemSet

● A data abstraction in the form of key / value string pairs● Provide the widget with information about the embedding environment● Can be declared in the widget preferences● Can be retrieved using the iContext object and function: getItemValue(“key”)

Widget preferences

● Default widget attributes can be specified in widgets-config.xml● <widgetDef> → <itemSet> → <item>

User Profile

● A predefined itemSet containing information about the authenticated user● Returns “null” if user is not logged in (Profiles and Communities allow anonymous)

● displayName = display name● email = e-mail address● userid = the IBM Connections unique user ID

Using the persistent data store

● Persist data on a per widget basis across sessions

● Tip!● If you need to store a lot of data, consider consolidating the data in a single JSON

object, then write the serialized string to the store● Quickly store / retrieve information with a single API operation and improve

responsiveness by minimizing HTTP requests

Making AJAX requests

● Dojo provides cross-browser XHR functions for making AJAX requests● dojo.xhrGet, dojo.xhrPost, dojo.xhrDelete, dojo.xhrPut

io.rewriteURI

● Modern browsers have a “Same Origin Policy” in place to prevent cross-site scripting (XSS) attacks

● JavaScript can only make AJAX calls to the originating server● To get around this problem, IBM Connections has an AJAX Proxy● If your application makes AJAX requests to different servers (or ports), you must

rewrite URLs so that they are processed by the proxy

Making AJAX requests using the Proxy

● Updated code with rewritten URL for the AJAX Proxy● An asynchronous callback (such as an AJAX request) can lose track of it's scope

● Use dojo.hitch to force a function to use the provided scope

IBM Connections REST API

● A REST API is available that allows you to perform most functions that are possible with the default web UI

● The API for each Connections application is fully documented in the official wiki● Uses AtomPub standard and HTTP CRUD operations for working with content

● These HTTP requests may not need to be proxied depending on your environment!● Only an issue if features reside on separate servers

Accessing IBM Connections features

● Due to different deployment configurations, the URL of a particular IBM Connections feature might not be known during widget development

● You can insert the root URL of IBM Connections features using ItemSets

Component Variable

Activities activitiesSvcRef

Blogs blogsSvcRef

Bookmarks dogearSvcRef

Communities communitiesSvcRef

Profiles profilesSvcRef

Retrieve Feeds using the REST API

Create new entries using the REST API

*** Line 25: You MUST set this header or IBM Connections will reject the API request!

Use an iFrame

● Quickly develop a POC or demo using iFrames to display external sites or pages

Agenda

● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication

Authentication Options

● Single Sign-on (SSO)● IBM session cookies = LtpaToken or LtpaToken2

– Can be used between WebSphere and Domino environments

● If your back-end server is not WebSphere or Domino based...– Can use 3rd party products to integrate IBM and non-IBM servers

● Tivoli Acess Manager, SiteMinder, etc.

– Can generate own trusted cookies using a combination of the current user's ID and some unique keys entered in widgets-config.xml

● Basic● Provide a Base 64 encoded username / password pair with each request● Can store the credentials in the iWidget persistent store

● OAuth● Login provided by a 3rd party provider● User authorizes application to access resources for a given time period

Thanks!

● 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!