Extending IBM Connections Profiles, Communities
and Homepage with iWidgets
IBM SBT Webinar 08/14/13

© 2013 IBM Corporation2
Future Webinars
Tentatively:
● 09/11: How to extend the Embedded Experience in IBM Connections

© 2013 IBM Corporation
IBM Connections App Dev Contest
● http://connectionscontest.openntf.org
● All types of OpenNTF projects can be nominated that utilize IBM Connections.
This includes the following areas:
● Accessing IBM Connections via the Social Business Toolkit SDK
● Accessing IBM Connections via the Connections REST APIs
● OpenSocial Gadgets for IBM Connections
● iWidgets for IBM Connections
● Customization solutions for IBM Connections
● All contributions need to work on IBM Connections 4.0 and can use the latest fix
packs
● Developers can use a free shared development environment in the cloud

© 2013 IBM Corporation
Agenda
Overview of iWidget
● iWidget specs
● iWidgets in IBM Connections
Registering iWidgets in IBM Connections
● widget-config.xml - registering iWidget in Profiles and Communities
● Proxy
● Homepage administrative interface
Development of custom iWidgets
● Tools
● Basics
● Best practices
Q & A

© 2013 IBM Corporation5
Disclaimers
IBM’s statements regarding its plans, directions, and intent are subject to change or
withdrawal without notice at IBM’s sole discretion.
Information regarding potential future products is intended to outline our general product
direction and it should not be relied on in making a purchasing decision.
The information mentioned regarding potential future products is not a commitment,
promise, or legal obligation to deliver any material, code or functionality. Information about
potential future products may not be incorporated into any contract. The development,
release, and timing of any future features or functionality described for our products remains
at our sole discretion.
Performance is based on measurements and projections using standard IBM benchmarks in
a controlled environment. The actual throughput or performance that any user will
experience will vary depending upon many factors, including considerations such as the
amount of multiprogramming in the user’s job stream, the I/O configuration, the storage
configuration, and the workload processed. Therefore, no assurance can be given that an
individual user will achieve results similar to those stated here.

© 2013 IBM Corporation6
Overview of iWidget
● iWidget: IBM-lead specification for defining “widgets”
● Supported in number of IBM products including IBM Connections, IBM Mashups,
IBM Portal, …
● “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).”
● In IBM Connections:
● iWidget is the basic building block for surfacing new content in the Connections UI
● Provision of “extension points” across the Connections UI where widgets following
the iWidget spec can be deployed
● Custom iWidgets can be deployed in Profiles, Communities and Homepage
● Catalog of publically available iWidget on Greenhouse
https://greenhouse.lotus.com

© 2013 IBM Corporation7
Overview of iWidget
● From a technical point of view – an iWidget is:
● An XML descriptor containing HTML rendered to the end-user
● … and optionally referencing external resources such as JavaScript and CSS
<iw:iwidget name="helloWorld" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
iScope="HelloWorldWidgetClass" supportedModes="view">
<iw:resource uri="helloworld.js" />
<iw:content mode="view">
<![CDATA[
<div id="root">
Hello World! <br/>
<button id="click" onclick="iContext.iScope().onClickButton()">Click
me!</button>
<div id="placeHolder"></div>
</div>
]]>
</iw:content>
</iw:iwidget>

© 2013 IBM Corporation8
iWidget placement areas in Profiles

© 2013 IBM Corporation9
iWidget placement areas in Communities

© 2013 IBM Corporation10
iWidget placement areas in Homepage

© 2013 IBM Corporation11
iWidget placement areas in Homepage

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.5
Recommendation:
● Use an OpenSocial Gadget in Homepage
● Provides better integration and code reuse opportunities with other products
– Example: IBM Notes / Domino 9
● Continue to use iWidget in Profiles and Communities
* Available in the following applications: Home Page, Profiles, Communities

Registering iWidgets in IBM Connections

© 2013 IBM Corporation14
iWidget catalog
● IBM maintain a catalog of available iWidget on Greenhouse
https://greenhouse.lotus.com

© 2013 IBM Corporation15
Registering an iWidget in Profiles and Communities
● widgets-config.xml – main configuration file for iWidget registration in
Profiles and Communities
● Register the location of the widget XML definition (“widgetDef”)
● Tell Connections where the XML descriptor of the iWidget is located (by url)
● Register widget instance(s) in the Connections UI
● Tell Connections where to render the iWidget in Profiles/Communities UI

© 2013 IBM Corporation16
Proxy registration (Profiles & Communities only)
● iWidget resources are fetched by the end-user browser
● JavaScript “same domain” policy – requests to remote resources must be proxied
through an “Ajax proxy”
● The “Ajax Proxy” is bundled in Connections out-of-the-box
● … but it is configured to allow traffic only to Connection applications
● Thus, if iWidget resources are located on a different domain than Connections,
there is the need to configure the “Ajax Proxy” to allow retrieval of remote
resources
● Add an entry for the domain under which the iWidget is deployed in
proxy-config.tpl

© 2013 IBM Corporation17
Registering an iWidget in Profiles and Communities
Demo:
● Registering “Learning” widget in Profiles main tab area
● Registering “Learning” widget in Communities

© 2013 IBM Corporation18
Registering an iWidget in Profiles and Communities
● widgetDef attributes in widgets-config.xml
Attribute Description
defId Unique id for the widget
url URL to the widget Xml descriptor
requires Specify which IBM Connections applications are
required by the iWidget. If the application are not
available, the iWidget is not rendered
modes List of supported modes by the iWidget: “view”,
“search”, “fullpage”, “edit”
resourceOwnerWidget
[ Profiles specific ]
Specify whether the iWidget should only be seen by
the resource owner
showInPalette
[ Communities specific ]
Specify whether the iWidget is available to the
Communities owner through the “widget palette”

© 2013 IBM Corporation19
Registering an iWidget in Profiles and Communities
● widgetInstance attributes
● Note: widgetInstance element are optional for Communities
● If showInPalette is set to true in widgetDef element, then community owners can
add and remove widget instance from the widget palette (accessible from the
“customize” button)
● widgetInstance element is used to specify a “mandated” widget in Communities –
ie: a widget that is open by default and that cannot be removed by Community
Owners
Attribute Description
defIdRef Define the widget definition to which the instance is
bound – it maps to the defId in the widgetDef
element
uiLocation Location of the widget on the page: last column,
central column, right column

© 2013 IBM Corporation20
Registering an iWidget in Homepage
● iWidget registration in Home Page is distinct from Profiles /
Communities
● Graphical user interface to manage iWidget
● Register, configure, enable / disable
● Admin section is only available to user in JEE role “admin” in Homepage application
● Administration through wsadmin scripting (command line)

© 2013 IBM Corporation21
Registering an iWidget in Homepage
Homepage admin section only accessible to users in JEE “admin” role

© 2013 IBM Corporation22
Registering an iWidget in Homepage
● Adding a widget

© 2013 IBM Corporation23
Registering an iWidget in Homepage
● Enabling / Disabling widgets
● Deleting widgets

© 2013 IBM Corporation24
Registering an iWidget in Homepage
● Enabled widgets are made available to end-users through the “widget
palette”

iWidget development

© 2013 IBM Corporation26
Required skills and tool
iWidgets are 'just' XML, HTML, JavaScript and CSS
● Basic knowledge on web development is required
● Knowledge of Dojo Toolkit is optional but advised for
advanced iWidget
Tools – usual web development tools:
● You can pick your favorite text editor / IDE!
● Eclipse is good enough
● … with Tomcat plug-in to publish iWidget resources on a
web server to streamline workflow
● Debugging:
● Firefox with Firebug plugin
● Chrome – includes development tools out of the box

© 2013 IBM Corporation27
Anatomy of an iWidget
<iw:iwidget name="helloWorld"
xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
iScope="HelloWorldWidgetClass"
supportedModes="view">
<iw:resource uri="helloworld.js" />
<iw:content mode="view">
<![CDATA[
<div id="root">
Hello World! <br/>
<button id="click"
onclick="iContext.iScope().onClickButton()">Click
me!</button>
<div id="placeHolder"></div>
</div>
]]>
</iw:content>
</iw:iwidget>
1. Root of the widget definition
iScope: name of the JavaScript
“class” backing the iWidget
supportedModes: list of views
supported by the widget
2. Reference to the external files
to fetch
3. HTML markup for the default
mode (“view” mode)
1
2
3

© 2013 IBM Corporation28
iScope and encapsulation
● iScope attribute is the name of the JavaScript 'class' backing the
iWidget – JavaScript class defines:
● Methods implementing the behavior of the iWidget
● Variables – typically the state and model of the iWidget
● An instance of the class is created by the framework for each
instance of the iWidget on the page
helloworld.jsiWidget.xml

© 2013 IBM Corporation29
iScope and encapsulation
● If defined, framework invokes specific methods in the iScope class
for main lifecycle events:
● onLoad, on<ModeName> (ie: onView), onDestroy
● A reference to the “iContext” is injected into the iScope class
● Allows access to additional iWidget APIs – see in next slides
● A reference to the iScope class can be obtained from HTML markup
through iContext.iScope()
helloworld.jsiWidget.xml

© 2013 IBM Corporation30
iContext – access to iWidget APIs
iContext: Main object allowing access to iWidget Apis
● DOM manipulation (within the portion of page for the iWidget instance)
iContext.getElementById()
iContext.getRootElement()
● ItemSets – name/value pairs holding properties for the iWidget
● Name/value pairs defined in iWidget XML
● Accessible from JavaScript through iContext.getItemSet
● User details – display name, email address and user id
● iContext.getUserProfile() returns an ItemSet containing user profile information
Example:
● iWidget attributes – widget metadata (usually customization/contextual
options)
iContext.getiWidgetAttributes()
XML descriptor JavaScript code

© 2013 IBM Corporation31
iContext – access to iWidget APIs
Demo:
● iWidget outputting user profile information

© 2013 IBM Corporation32
Making requests to remote servers
● “Same origin policy”: JavaScript can only make AJAX calls to the
originating server
● Leverage the Connections Ajax proxy to make request to remote
servers on other domain with iContext.io.rewriteURI
Note: the Connections Ajax Proxy must be configured to allow request to remote servers –
see slide 14 ...

© 2013 IBM Corporation33
Making requests to remote servers
Demo:
● iWidget accessing Yahoo Weather RSS APIs

© 2013 IBM Corporation34
iWidget modes
Several views (“modes”) can be defined per widget
● One (and only one) view displayed at a given time
“View” mode
Edit
Full page
Search

© 2013 IBM Corporation35
iWidget modes
iWidget mode
● Specific modes are recognized by IBM Connections for different contexts
● d
Component Modes
Communities ● “view”: facet displayed when the widget is located in the “Overview”
page
● “fullpage”: view displayed when the user clicks the widget name in the
left column
● “edit”: view displayed when a community owner selects “Community
Action” → “Edit Community”
● “search”: view displayed when an end-user performs a search in the
Community
Homepage ● “view”: Default view
● “edit”: Edit view when user clicks “Edit” option in drop down menu from
the widget title bar
Profiles ● “view” only

© 2013 IBM Corporation36
iWidget modes
Demo:
● View, edit, search and full page modes of a same widget in Communities

© 2013 IBM Corporation37
iWidget specifics for Profiles and Communities
Is the widget running in Communities or Profiles?
● Available through the “resourceType” attribute
In which Community / on which Profiles the widget is running?
● Available through the “resourceId” attribute
Is the user authenticated?
● this.iContext.getUserProfiles() returns null if the user is not authenticated
What is the role of the current user in the Community?
● Additional attributes in the userProfile object for Access control
● canPersonalize: determines if user can personalize the content of the resource. Only
a resource owner is allowed
● canContribute: determines if the user can contribute content to a resource.
(Community - member in a private or moderated community can contribute)

© 2013 IBM Corporation38
iWidget specifics for Profiles and Communities
In Profiles/Communities: administrator can predefine widget attributes
name/value pair in widgets-config.xml
● Accessible programmatically from widget through
iContext.getiWidgetAttributes().getItemValue...
● widgets-config.xml supports a number of variables replaced at runtime
● In particular variable resolving to the actual context root of Connections Services
● Full list of variables available at http://www-
10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?
lookupName=IBM+Connections+4.5+Documentation#action=openDocument&re
s_title=Profiles_widget_configuration_variables_ic45&content=pdcontent

© 2013 IBM Corporation39
iWidget specifics for Homepage
Homepage replaces variables/tags directly in widget XML descriptor
<iw:itemSet id="feeds">
<iw:item id="todos" value="{activities}/service/atom2/todos"/>
</iw:itemSet>
<iw:itemSet id="feeds">
<iw:item id="todos" value="http://activities.tap.ibm.com/activities/service/atom2/todos"/>
</iw:itemSet>
Replaced by Homepage at runtime
I
● To benefit from variable substitution, the widget must be registered with the option
● Supported variable/tag name restricted to name of services registered in
LotusConnections-Config.xml

© 2013 IBM Corporation40
Best practices
Look and feel
● Use OneUI CSS in iWidget DOM to leverage existing loaded CSS styles
from Connections
● Prefix custom CSS classes to avoid clashes with existing styles on page
● Test your widget with different themes (Communities)
Fetching external resources
● Use iw:resource element to fetch resources within your widget
● When loading resources dynamically; use the iWidget IO module to avoid
Cross-domain restrictions
Performance
● Minimize the number of Ajax requests of iWidget load
● Combine JavaScript files into one single file
● JavaScript / CSS / images / XML files should be browser cachable
whenever possible

© 2013 IBM Corporation41
Resources and going further
● iWidget development guide for IBM Connections
http://www-10.lotus.com/ldd/lcwiki.nsf/dx/development-guide
● iWidget specifications
http://www-10.lotus.com/ldd/mashupswiki.nsf/dx/widget-programming-guide
● Using Lotus Connections factory to generate iWidgets
http://www.ibm.com/developerworks/lotus/library/connections-widgets/
● Wrapping a Google gadget into an iWidget
http://www.ibm.com/developerworks/lotus/library/connections-gadgets/
● Product Documentation: various sections covering all administrative options related
to iWidgets and Ajax Proxy (search for “iWidget”)
http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?
lookupName=IBM+Connections+4.5+Documentation#action=openDocument&conte
nt=catcontent&ct=prodDoc

© 2013 IBM Corporation42
Resources and Questions
● Home page: http://ibmdw.net/social
● SDK: http://ibmsbt.openntf.org
● GitHub: https://github.com/OpenNTF/SocialSDK
● StackOverflow: #ibmsbt
● Twitter: @ibmsbt
● YouTube: http://youtube.com/ibmsbt
● Playground: http://bit.ly/sbtplayground

© 2013 IBM Corporation43
Acknowledgements and Disclaimers
© Copyright IBM Corporation 2013. All rights reserved.
– U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
IBM, the IBM logo, ibm.com, Rational, the Rational logo, Telelogic, the Telelogic logo, Green Hat, the Green Hat logo, and other IBM
products and services are trademarks or registered trademarks of International Business Machines Corporation in the United States,
other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a
trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information
was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is
available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml
Other company, product, or service names may be trademarks or service marks of others.
Availability: References in this presentation to IBM products, programs, or services do not imply that they will be available in all
countries in which IBM operates.
The workshops, sessions and materials have been prepared by IBM or the session speakers and reflect their own views. They are
provided for informational purposes only, and are neither intended to, nor shall have the effect of being, legal or other guidance or
advice to any participant. While efforts were made to verify the completeness and accuracy of the information contained in this
presentation, it is provided AS-IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising
out of the use of, or otherwise related to, this presentation or any other materials. Nothing contained in this presentation is intended to,
nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and
conditions of the applicable license agreement governing the use of IBM software.
All customer examples described are presented as illustrations of how those customers have used IBM products and the results they
may have achieved. Actual environmental costs and performance characteristics may vary by customer. Nothing contained in these
materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific
sales, revenue growth or other results.