© 2014 IBM Corporation iWidget Development IBM Connections 5.0 Workshop Author: Paul Godby IBM Ecosystem Development Duration: 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 iWidgetOpenSocial Gadget Activity Streams *X Share DialogX Home PageXX ProfilesX CommunitiesX RenderinginlineiFrame SpecificationiWidget 1.0OpenSocial 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 TagAttributeDescription iw:iwidgetidUnique identifier supportedModesView modes supported by the widget modeDefault view mode to use iScopeName of the JavaScript instance iw:resourceuriLinks to additional JavaScript or CSS files iw:contentmodeDefault 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 TagAttributeDescription widgetBundlename 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 TagAttributeDescription widgetDefdefId Unique identifer The key in the properties file for the title descriptionThe key in the properties file for the widget palette description bundleRefId Name of resource bundle to load Bundle was defined in LotusConnections-config.xml urlLocation of the XML descriptor for the iWidget itemSet itemnameName for a predefined attribute valueValue 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- - 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) 1) Home Page administrators can: add/remove widgets enable/disable widgets 2) 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 TagAttributeDescription widgetInstanceuiLocationDefines the location of the widget on the page. Possible values: col1, col2, col3 defIdRefThe 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 TagAttributeDescription widgetInstanceuiLocationDefines the location of the widget on the page. Possible values: col1, col2, col3, or tabsWidget1 defIdRefThe 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 LinesDescription 1Tells Dojo a module has been provided with the given name (the iScope) 2Dojo class declaration 4Called once when class is instantiated 7Called when iWidget is loaded 10Called when iWidget mode is “view 13Called 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 → →

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 = 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 ComponentVariable ActivitiesactivitiesSvcRef BlogsblogsSvcRef BookmarksdogearSvcRef CommunitiescommunitiesSvcRef ProfilesprofilesSvcRef

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 3 rd 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 3 rd 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 → 1. Visit the IBM Collaboration Solutions Ecosystem Development Community Link → 1. Learn new skills and share these links with your friends and colleagues!