Customizing and Extending
IBM Connections
Claudio Procida — Software Developer, IBM Connections
July 2011
1

Note
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.
All features are subject to change without notice
©2011 IBM Corporation

Customizing IBM Connections
● IBM Connections is a white label product
─ Business Partners and ISSL often rebrand the software and make it look like the
client's enterprise applications
● IBM Connections supports a variety of customization options
─ Customizing the user interface
─ Adding widgets to Communities
─ Extending properties in Profiles
─ Communities themes
─ Customizing email digest templates
─ Blogs themes (deprecated)
All features are subject to change without notice
©2011 IBM Corporation

Customizing the User Interface
● Customizers can override static files, CSS stylesheets, and UI strings (labels,
window titles, etc.) without altering the source of the web applications.
● Create and publish your own CSS stylesheets and strings files.
─ They will be preserved when applying product upgrades or iFixes(*)
● Recommended Workflow
1) Enable Customization Debug Mode
● This will force the application to reload override files each time a request is
made (very resource intensive!)
2) Inspect the source of the web applications you desire to customize
● Identify property files and CSS files that contain string keys, or CSS rules you
wish to override
3) Make the changes
4) Reload the user interface to ensure the result is satisfactory
5) Disable Customization Debug Mode
● Very important!
(*)IBM reserves the right to apply minor changes to customizable files. Changes to customizable files will be advertised in the product documentation.
All features are subject to change without notice
©2011 IBM Corporation

Customizable Resources
● Refer to the table below for the name of the web application module that
contains customizable files
Application File name
Activities oawebui.war
Blogs blogs.war
Bookmarks dogear.webui.war
Bookmarklet lc-bookmarklet.war
Communities comm.web.war
Files qkr.share.files.war
Forums forums.web.war
Homepage homepage.war
Mobile mobile.web.war
Profiles lc.profiles.app.war
Search search.war
Wikis qkr.share.wiki.war
All features are subject to change without notice
©2011 IBM Corporation

Customizable Resources (continued)
● Layout
File location Description
<application_war>/nav/templates/menu/apps.jsp Applications menu
<application_war>/nav/templates/menu/communities.jsp Communities menu
<application_war>/nav/templates/menu/people.jsp Profiles menu
<application_war>/nav/templates/header.jsp Page header
<application_war>/nav/templates/footer.jsp Page footer
<application_war>/nav/templates/login.jsp Login page
<application_war>/nav/templates/error.jsp Error page
● Stylesheets
File location Description
<application_war>/nav/common/styles/defaultTheme.css Default theme stylesheet
<application_war>/nav/common/styles/custom.css Custom stylesheet
All features are subject to change without notice
©2011 IBM Corporation

Customizable Resources (continued)
● Strings
─ Blogs
blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/ui_en.properties
blogs.war/dojo/lconn/blogs/nls/strings.js
─ Bookmarks
blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/ui_en.properties
blogs.war/dojo/lconn/blogs/nls/strings.js
─ Communities
comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/tango/web/resources/resources_en.properties
comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/tango/web/taglib/taglib_en.properties
comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/lconn/communities/strings/ui_en.properties
comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/lconn/communities/strings/uiemail_en.properties
comm.web.war/javascript/source/lconn/communities/nls/strings.js
All features are subject to change without notice
©2011 IBM Corporation

Customizable Resources (continued)
● Strings
─ Bookmarklet
lc-bookmarklet.war/dojo/lconn/dogear/nls/strings.js
lc-bookmarklet.war/WEB-INF/lib/lc-bookmarklet.jar!/com/ibm/lconn/bookmarklet/strings/ui_en.properties
─ Activities
oawebui.war/WEB-INF/lib/oawebui.jar!/com/ibm/openactivities/web/coreui/resources/resources_en.properties
oawebui.war/WEB-INF/lib/oawebui.jar!/com/ibm/openactivities/web/coreui/servlet/servlet_en.properties
oawebui.war/WEB-INF/lib/oataglib.jar!/com/ibm/openactivities/taglib/taglib_en.properties
oawebui.war/WEB-INF/lib/oataglib.jar!/com/ibm/openactivities/taglib/resources/tlresources_en.properties
─ Files
Files.ear/lconn.files.ui.jar!/com/ibm/lconn/files/strings/ui_en.properties
Files.ear/lconn.files.ui.jar!/com/ibm/lconn/files/strings/uihelp_en.properties
Files.ear/lconn.files.ui.jar!/com/ibm/lconn/files/strings/uitemplates_en.properties
All features are subject to change without notice
©2011 IBM Corporation

Customizable Resources (continued)
● Strings
─ Wikis
Wikis.ear/lconn.wikis.ui.jar!/com/ibm/lconn/wikis/strings/ui_en.properties
Wikis.ear/lconn.wikis.ui.jar!/com/ibm/lconn/wikis/strings/uihelp_en.properties
Wikis.ear/lconn.wikis.ui.jar!/com/ibm/lconn/wikis/strings/uitemplates_en.properties
─ ...
─ Yeah, there's more!
All features are subject to change without notice
©2011 IBM Corporation

Enabling Customization Debug Mode
● Declare a WebSphere environment variable named
CONNECTIONS_CUSTOMIZATION_DEBUG and set it to true
─ This will cause Connections to look for overridden resource files every time a
request is served. It is really resource intensive and is heavily discouraged for
production use.
─ Remember to unset when finished with the customization work!
● Locate the directory declared as CONNECTIONS_CUSTOMIZATION_PATH
WebSphere environment variable
─ Defaults to <install_dir>/data/shared/customization/
─ This is the directory where your customization will be applied
● Customization can be global (i.e. applied to all Connections applications) or
targeted to a specific component (e.g. Wikis, Activities)
● When looking for a string bundle or a CSS file, Connections will look into:
1) <CONNECTIONS_CUSTOMIZATION_PATH>/common
2) <CONNECTIONS_CUSTOMIZATION_PATH>/<component name> (e.g. wikis)
3) Its original location (e.g. inside an expanded WAR file)
All features are subject to change without notice
©2011 IBM Corporation

Customization Example
Replace the welcome box title into Connections Wikis
1)Locate the property file used by Wikis to render the welcome box:
─ File is
<WAS_profile_dir>/installedApps/<cell_dir>/Wikis.ear/qkr.share.wiki.war/lconn.wik
is.jar/com/ibm/lconn/wikis/strings/ui_en.properties
2)Locate the string key you want to override
─ WELCOME.PUBLICWIKIS.TITLE=New to Wikis?
3)Create the <CONNECTIONS_CUSTOMIZATION_PATH>/strings directory
4)Create a file in the customized strings directory, with the exact bundle name
● File name must be
<CONNECTIONS_CUSTOMIZATION_PATH>/strings/com.ibm.lconn.wikis.strings.
ui_en.properties
5)Override the string
─ WELCOME.PUBLICWIKIS.TITLE=Wikis rocks! You should really use it.
6)Reload the page. W00t!
All features are subject to change without notice
©2011 IBM Corporation

Declaring a Custom String Bundle
● It is possible to declare a new string bundle to be used in custom widgets, UI
extensions, custom Profiles properties etc.
1)Create the resource bundle file in <customization_dir>/strings
─ e.g.
<customization_dir>/strings/com.yourcompany.example.resources_en.properties
2)Declare it into LotusConnections-config.xml
<resources>
<!-- The attribute 'prefix' must be globally unique as it
identifies the bundle when used in IBM Connections. -->
<widgetBundle prefix="yourcompany_resources"
name="com.yourcompany.example.resources"/>
</resources>
● For performance reasons, it is recommended to create a single bundle
containing all custom strings
All features are subject to change without notice
©2011 IBM Corporation

Customizing File Type Icons
● File type icons use sprited CSS backgrounds, so it's really
easy to override them with your custom icons.
● Start with the Connections sprite stylesheet
─ <application war>/nav/common/styles/base/sprite-lconn.css
─ Refer to the UI customization guidelines for more info
● Make a copy in the common customization directory
─ It makes more sense to change file type icons globally, but
you may still want to change them for a specific component
─ You may want to copy only the rules
● Edit the rules of interest, restart the application
─ You may have to update the version stamp to propagate
changes to clients
● Communities and Files support the addition of new file type
icons
─ It is sufficient to declare a CSS class for the desired file type
extension
All features are subject to change without notice
©2011 IBM Corporation

File Type Icons Customization Example
Goal: customize the file type icon for Symphony presentation files
1)Locate the rule in nav/common/styles/base/sprite-lconn.css
.lconn-ftype16-flw,.lconn-ftype16-key,.lconn-ftype16-mass,.lconn-
ftype16-odp,.lconn-ftype16-ope,.lconn-ftype16-otc,.lconn-ftype16-
otp,.lconn-ftype16-pot,.lconn-ftype16-potm,.lconn-ftype16-potx,.lconn-
ftype16-pp2,.lconn-ftype16-pp97,.lconn-ftype16-ppam,.lconn-ftype16-
pps,.lconn-ftype16-ppsm,.lconn-ftype16-ppsx,.lconn-ftype16-ppt,.lconn-
ftype16-pptm,.lconn-ftype16-pptx,.lconn-ftype16-prz,.lconn-ftype16-
shw3,.lconn-ftype16-sti,.lconn-ftype16-sxi {background-position: 0
-312px;}
2)Declare the following rule in <customization
dir>/common/nav/common/styles/base/sprite-lconn.css
.lconn-ftype16-odp {background-image: url(path/to/image/symphony-
16.png) !important; background-position: 0 0 !important;}
3)Repeat step 2. with 32 and 64 pixel icons
.lconn-ftype32-odp {background-image: url(path/to/image/symphony-
32.png) !important; background-position: 0 0 !important;}
.lconn-ftype64-odp {background-image: url(path/to/image/symphony-
64.png) !important; background-position: 0 0 !important;}
All features are subject to change without notice
©2011 IBM Corporation

Customization Best Practices
● Keep the customization directory under source control
● Copy only the resource files you want to modify to the customization directory
─ Makes it easier to track what was changed
─ Always comment customized files to remember where and why a change was
made
● Back up the customization directory before a product upgrade
─ Rename the customization directory to a temporary name
─ Apply the iFix or fixpack
─ Verify the functionality
─ Compare changed files to customized copy, and merge changes
─ Restore the customization directory to its original name
─ Test the customization
● Use a web inspector to locate the CSS rules you want to change
─ Firebug on Mozilla Firefox, Webkit Inspector on Chrome or Safari, Weinre for
Mobile
All features are subject to change without notice
©2011 IBM Corporation

Troubleshooting UI Customization
● If you didn't enable the Customization Debug Mode you may have to restart
the application to see changes
● Did you create the file name with the right Java package name ?
─ File must be in the strings/ directory, without subdirectories
● Enable WebSphere trace
─ Set “com.ibm.lconn.core.customization.*=all”
─ Restart the application
─ You will see customization debug messages during the application startup
● Clear the browser cache, or consider updating the product version stamp
─ Refer to the Infocenter to update the version stamp
All features are subject to change without notice
©2011 IBM Corporation

Perfect ? Maybe not...
● Treasure hunt to find resource file for a given string
─ Difficult to identify which property file contains the string
─ Not always clear which JAR contains the property file
● Inconsistent locations and names of web application modules
● Suggestions for improvement? We are listening!
● Several improvements coming with Connections Next
All features are subject to change without notice
©2011 IBM Corporation

Customizing Getting Started
● The Getting Started tab is the main entry point for the user after
authentication
─ It is recommended that users are educated on the use of social collaboration tools
● Very useful to publish information on the company's policy on social software
usage
─ Links to policy documents, directions for users etc.
● Configured through gettingstarted-config.xml
<step enabled="true">
<title bundle="com.yourcompany.resources">strings.key</title>
<body-links
secure="url/to/secure/page"
unsecure="url/to/non/secure/page" />
</step>
All features are subject to change without notice
©2011 IBM Corporation

Customizing Getting Started (continued)
● Check out the gettingstarted-config.xml file using the admin command
─ HomepageCellConfig.checkOutGettingstartedConfig("/opt/act/temp","foo01Cell01")
● Add or remove <step> elements, or set the “enabled” attribute to “false”
─ Copy one of the existing steps and use it as a model
● The <title> element lets you define the title of the vertical tab in the Getting
Started page
─ The bundle attribute specifies the resource file
─ The element text is the key of the string in the bundle
● The <body-links> element declares the URLs of content to display inside the
tab
─ The secure attribute is used when Homepage is configured to use SSL
─ URLs in secure and unsecure (?) attributes must be in the same domain
● When finished, check in the gettingstarted-config.xml and restart
Homepage
All features are subject to change without notice
©2011 IBM Corporation

Customizing Email Digest Templates
● Templates are written in Freemarker templating language
─ http://freemarker.sourceforge.net/docs/index.html
─ Version used is 2.3.15, as of IBM Connections 3.0.1
● Files located in <WAS_root>/profiles/<DM_profile_root>/config/cells/<cell-
name>/LotusConnections-config/news/email
● Customize existing daily, weekly, or following email templates and string
bundles, or
● Edit notification-config.xml to declare new templates and string
bundles, use existing templates as a reference
● List of story properties exposed in templates documented here
─ http://www-10.lotus.com/ldd/lcwiki.nsf/dx/IBM_Connections_3.0.1_Email_Digest
All features are subject to change without notice
©2011 IBM Corporation

Customizing Email Digest Templates (continued)
● Example excerpt from notification-config.xml
<type name="weeklyDigest" notificationType="FOLLOW">
<channel enabled="true" name="email">
<property name="sender">news-admin@mycompany.com</property>
<property name="ftl">/path/to/custom/weeklyDigest.ftl</property>
<property name="bundlePath">path/to/resource/bundle/</property>
<property name="bundleName">mycompany_resources</property>
</channel>
</type>
<type name="dailyDigest" notificationType="FOLLOW">
<channel enabled="true" name="email">
<property name="sender">news-admin@mycompany.com</property>
<property name="ftl">/path/to/custom/dailyDigest.ftl</property>
<property name="bundlePath">path/to/resource/bundle/</property>
<property name="bundleName">mycompany_resources</property>
</channel>
</type>
All features are subject to change without notice
©2011 IBM Corporation

Extending Communities Themes
● Add, edit, or delete entries in communities-config.xml
● Example theme declaration
<comm:theme>
<comm:themeUuid>my_company_theme</comm:themeUuid>
<comm:displayNameKey>label.my_company_theme</comm:displayNameKey>
<comm:cssUrl>/path/to/theme.css</comm:cssUrl>
<comm:cssRtlUrl>/path/to/themeRTL.css</comm:cssRtlUrl>
<comm:thumbnailUrl>/path/to/thumbnail.png</comm:thumbnailUrl>
</comm:theme>
● To disable Communities themes, comment all <theme> elements (?)
All features are subject to change without notice
©2011 IBM Corporation

UI Extensions
● Existing framework to declare UI extensions written in Javascript
● Configurable through uiextensions-config.xml
● Messy, requires manual dependency handling, callback delay etc.
● Example:
<extension name="global.pageRendering"
jsCallback="lconn.profiles.sametime.sametimeProxyInit" enabled="false"/>
<extension name="lc.IMAwareness"
jsCallback="lconn.profiles.sametime.sametimeProxyAddLiveName"
invokeDelay="2000" enabled="false" id="stProxy">
<params>
<param name="isConnectClient" value="true" />
<param name="lconnProxySvcUrl" value="admin_replace"/>
<param name="lconnProxySvcUrlSSL" value="admin_replace"/>
</params>
</extension>
● Will be deprecated soon in favor of a seamless JS extension framework
All features are subject to change without notice
©2011 IBM Corporation

Miscellaneous Known Issues
● Email templates are using a mix of technologies and are inconsistent
─ Some use Freemarker (Files, Wikis, News … ), others use JSP
─ Email templates in Connections Next will use Freemarker
● Activity templates saved by users are stored in a single directory
─ Over time, the number of files in this directory can grow bigger than the maximum
allowed for the file system
─ What happens then ?
● It is difficult to extend or override UI actions, e.g. adding a “Tell a Friend”
consistently across all applications
─ A better extension framework is needed
─ Major improvements coming with Connections Next
All features are subject to change without notice
©2011 IBM Corporation

Extending IBM Connections
● ISSL has developed a number of dedicated solutions that extend
Connections
─ B2C features, Self Sign-up, On-the-Glass Integration with WebSphere Portal, ...
● WebSphere Portlet Factory (WPF) is the recommended rapid application
development tool to write portlets for WebSphere Portal
─ Take advantage of the existing portlets in the Business Solutions Catalog
─ Download the IBM Connections 3.0.1 Portlets for free!
● It's really easy to consume the Connections public API to enable social
collaboration
─ Refer to the product Infocenter for documentation on the public API
● Ask your ISSL contact about the possibilities!
©2011 IBM Corporation

External References
● IBM Connections Product Documentation Wiki
─ http://www-10.lotus.com/ldd/lcwiki.nsf/
● IBM Lotus and WebSphere Portal Business Solutions Catalog
─ http://greenhouse.lotus.com/catalog/
All features are subject to change without notice
©2011 IBM Corporation

Thank You!
Questions? Suggestions?
©2011 IBM Corporation

Legal Disclaimer
© IBM Corporation 2011. All Rights Reserved.
The information contained in this publication is provided for informational purposes only. While efforts were made to verify the
completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express
or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM
without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any
other materials. Nothing contained in this publication 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.
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. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole
discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature
availability in any way. 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.
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.
IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, Quickr, Sametime, WebSphere, UC2, PartnerWorld and Lotusphere are
trademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark of
WebDialogs, Inc., in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service
names may be trademarks or service marks of others.
©2011 IBM Corporation