1.
IBM Connections
Extensions and Themes
Demystified
Claudio Procida <procidac@ie.ibm.com>
IBM Connections Technical Sessions
For Developers And Partners

2.
3
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.
● This deck refers to IBM Connections 5.0 unless otherwise noted.

3.
Use of Javascript in Connections
● IBM Connections 5.0 uses the Dojo Toolkit to build high quality desktop and mobile
web applications
– Dojo Toolkit version 1.9.2 (AMD base) is currently in use
– Code of most applications still written with legacy pre-AMD format
● Much of the front end is rendered on the client side
● In single-page AJAX applications, like Activities, Files, Wikis, Moderation:
– The front end is entirely rendered using Javascript: DOM manipulation, widgets
– The application itself is written in Javascript: lifecycle, user input, AJAX
● In other traditional web applications, like Profiles:
– Still using common widgets, and relevant areas written in Javascript e.g. widget
container
● Other applications e.g. Home Page, Communities are a mix of both

4.
How does Connections serve JavaScript
● Javascript resources in Connections are centrally served by the Common application
● Dojo layers are not static, but dynamically generated by servlets
– Powerful, flexible, on-demand
– Generates a Javascript file containing only required dependencies
● Layers are resolved dynamically based on configuration
● Script tags are inserted in a page using the <lc-ui:dojo> tag:
● This will be transformed to:
<!-- Inserts script tags that load Dojo layers required by this
module -->
<lc-ui:dojo include="lconn.comm.communitiesApp">
<script src="_js?include=dojo.main"></script>
<script src="_js?include=lconn.core.bundle_common"></script>
<script src="_js?include=lconn.comm.communitiesApp"></script>

5.
How does it work?
● IBM Connections implements a modified drop of Rational Team Concert SDK
– RTC can generate Dojo layers and CSS stylesheets on the fly
– Automatic dependencies traversal, aggregation, minification
● Connections extends the framework and adds extra features
– It is possible to override any resource through the customization directory
● When in debug mode:
– Resources are served unminified
– Dojo resources are not layered, but are served individually

6.
AMD Modules
● Any modules written with the AMD format can be aggregated
– define('<module_id>', [<list_of_dependencies>], function() { /* callback */});
● Modules can be referenced across bundles in a deployment
How does it work?
/* module1.js */
define('module1',
['module2'], function(m2) {
m2.a = m2.a + 1;
});
/* module2.js */
define('module2', [],
function() {
return {a : 1};
});
/* _js?include=module1 */
define('module2', [],
function() {
return {a : 1};
});
define('module1',
['module2'], function(m2) {
m2.a = m2.a + 1;
});

7.
Legacy Dojo Modules
● Modules written with the legacy Dojo Toolkit format can be aggregated
– Note: only provided for backwards compatibility; any new development should
use the AMD format
● Modules can be referenced across bundles in a deployment
How does it work?
/* module3.js */
dojo.provide('module3');
dojo.require('module4');
module4.foo();
/* module4.js */
dojo.provide('module4');
module4.foo = function() {
//...
};
/* _js?include=module3 */
dojo.provide('module4');
module4.foo = function() {
//...
};
dojo.provide('module3');
module4.foo();

8.
How does it work?
/* stylesheet1.css */
@import
url('stylesheet2.css')
p { line-height: 1.2; }
/* stylesheet2.css */
a:link, a:visited {
color: red;
}
a:active, a:focus {
color: blue;
}
/* _style?
include=stylesheet1 */
a:link, a:visited {
color: red;
}
a:active, a:focus {
color: blue;
}
p { line-height: 1.2; }
Stylesheets
● Stylesheets can be aggregated. The @import url('<stylesheet>') statement
inlines imported stylesheets recursively.
● Stylesheets can be referenced across bundles in a deployment

9.
What about third party libraries?
● CKEditor, Rangy, Timeago, etc. are wrapped in Dojo classes and served in Dojo
layers
● IBM Connections 5 can now aggregate, minify and serve any AMD libraries
– e.g. jQuery

10.
Extension Points
● The Rational Team Concert SDK provides predefined extension points that allow
developers to augment the framework with custom behavior:
– Web Bundles
– Dojo Module Provider
– Dojo Resource Module Provider
● Additionally, IBM Connections provides other extension points:
– Dojo Module Bindings
– Themes
– CSS Bindings

11.
Extension Points
Web Bundles
● This extension in the plugin.xml declares that this OSGi bundle serves the Dojo
package com.mycompany.foo
● When requesting a class in the com.mycompany.foo package, the framework will
look for it inside this bundle.
● If a base-name is set, it will be used as module path for the declared Dojo module
<?eclipse version="3.4"?>
<plugin>
<!-- Declares your Dojo extension package -->
<extension point="net.jazz.ajax.webBundles">
<alias value="com.mycompany.foo" />
<resource base-name="/path/to/js" />
</extension>
</plugin>

12.
Extension Points
Dojo Module Provider
● This extension declares that the Dojo module com.example.foo.Bar is provided
by the Java class com.mycompany.foo.Bar
● The provider is used to lazily create the resource for the module when a reference to
it needs to be resolved.
● Allows creation of Dojo modules from arbitrary data sources, e.g. XML configuration
<?eclipse version="3.4"?>
<plugin>
<!-- Declares a Dojo module provider -->
<extension point="net.jazz.ajax.dojoModules">
<dojoModule id="com.example.foo.Bar"
provider="com.mycompany.foo.Bar" />
</extension>
</plugin>

13.
Extension Points
Dojo Resource Module Provider
● This extension synthesizes a Dojo resource module from a Java ResourceBundle
providing string resources.
● Resource modules thus declared can be loaded using dojo/i18n! (AMD) or
dojo.i18n.getLocalization(package, name)
● If nested=”true”, the bundle is interpreted as a set of nested string objects
delimited by “.”
<?eclipse version="3.4"?>
<plugin>
<!-- Declares your Dojo extension package -->
<extension point="net.jazz.ajax.dojoResourceModules">
<dojoResourceModule package="com.example.foo"
name="bar" nested=”true”
file="/com/example/foo/nls/bar.properties" />
</extension>
</plugin>

14.
Extension Points
Dojo Module Binding
● Allows 3rd parties to bind an extension module to an arbitrary Dojo module. When the module
is loaded, the extension module will also be included — after the bound module, if a
dojo.require() exists in the extension module
● Attempting to load lconn.core.header via dojo.require() will guarantee that
com.mycompany.foo.Bar will also be returned
● The layer that contains lconn.core.header will have com.mycompany.foo.Bar, although
com.mycompany.foo.Bar may be loaded before A unless com.mycompany.foo.Bar
declares dojo.require('lconn.core.header');
<?eclipse version="3.4"?>
<plugin>
<!-- Binds your Dojo package to a class in Connections -->
<extension point="net.jazz.ajax.dojoModuleBinding">
<dojoModuleBinding bind="com.mycompany.foo.Bar"
to="lconn.core.header" />
</extension>
</plugin>

15.
Extension Points
Custom Themes
● Declares that this OSGi bundle provides a theme with id “example”
● Such a theme can be used for Communities themes or as a global theme
<?eclipse version="3.4"?>
<plugin>
<!-- Adds a custom theme with id “example” -->
<extension point="com.ibm.lconn.core.styles.themes">
<theme
id="example"
resource="/theme.css"
resource-rtl="/themeRTL.css"
version="oneui3"
/>
</extension>
</plugin>

16.
Extension Points
CSS Bindings
● Declares a binding between the other.css and the connectionsCore.css stylesheets.
● Allows 3rd parties to bind a custom stylesheet to an arbitrary built-in stylesheet. When the
stylesheet is loaded in Connections, the custom stylesheet will also be included
<?eclipse version="3.4"?>
<plugin>
<!-- Declares a CSS binding -->
<cssBinding
bind="com.ibm.lconn.core.styles.test/css/other.css"
to="com.ibm.lconn.core.styles/base/connectionsCore.css" />
</plugin>

17.
18
Cookbook

18.
Creating a new Theme
Customization Directory Only
● It is possible to create a new theme by placing stylesheets into a subdirectory of the
theme customization directory following simple naming conventions
● The subdirectory must be named '<theme_id>Theme' e.g. 'vanillaTheme'; the main
stylesheets must have a similar name: '<theme_id>Theme.css' and
'<theme_id>ThemeRTL.css' e.g. 'vanillaTheme.css' and 'vanillaThemeRTL.css'
– In the above example, the theme will be available as the 'vanilla' theme.
<CONNECTIONS_CUSTOMIZATION_DIR>/themes/<theme_id>Theme/
+--/<theme_id>Theme.css
+--/<theme_id>ThemeRTL.css
+--/applications/activities.css
| +--/activitiesRTL.css
...

19.
Creating a new Theme
Packaged Theme
● A theme can be packaged and distributed as an OSGi bundle with a well-defined
structure.
● A packaged theme can be easily distributed and published on a catalog e.g. the Solutions
Catalog on Greenhouse
– Example: the new theme for IBM Connections 4.5 CR
<bundle_root>/resources/
| +--/theme.css
| +--/themeRTL.css
| ...
+--/META-INF/
| +--/MANIFEST.MF
+--/plugin.xml

20.
Setting the Default Theme
● Any theme, built-in or custom, can be set as default throughout a Connections deployment
by adding a generic property to the master configuration file LotusConnections-config.xml
● To apply this generic property:
1) Check out the LotusConnections-config.xml file from the Deployment Manager
2) Edit the file to add the generic property at the end of the file, before the closing </config>
3) Update the version stamp
4) Check in the LotusConnections-config.xml file
5) Synchronize all nodes and restart the cluster
<properties>
<genericProperty
name="com.ibm.lconn.core.web.styles.theme.default">vanilla</genericProperty>
<!-- Other generic properties -->
</properties>
</config>

21.
Extending UI Components
Customization Directory
● Handy, casual approach to replace single modules to provide custom behavior
● This approach can only be used to customize existing Javascript modules
– Note: Javascript modules are subject to change at any time without notice. This
customization approach is offered as an 'as-is' basis
<CONNECTIONS_CUSTOMIZATION_DIR>/javascript/
+--lconn/
| +--core/
| +--header.js
+--com/
| +--ibm/
| +--oneui/
| +--controls/
| +--MessageBox.js
...

22.
Extending UI Components
Packaged Extension Bundle
● A self-contained bundle that can inject custom Javascript into a Connections
deployment.
● Combined with the Dojo Module Bindings, this approach can extend behavior of
default Connections components
– Ephox EditLive! is distributed as a packaged extension bundle
<bundle_root>/resources/
| +--com/
| | +--mycompany/
| | +--module1.js
| | +--module2.js
| ... ...
+--/META-INF/
| +--/MANIFEST.MF
+--/plugin.xml

23.
Extending UI Components
Hybrid Extension Bundle
● Bundles can actually contain a mix of CSS and Javascript, and an arbitrary number
of extensions
● Combined with the Dojo Module Bindings, this is the most flexible approach to
distribute extensions that provide add-ons to Connections
<bundle_root>/resources/
| +--com/
| | +--mycompany/
| | +--module1.js
| | +--module2.js
| ... ...
| +--theme.css
| +--themeRTL.css
| ...
+--/META-INF/
| +--/MANIFEST.MF
+--/plugin.xml

24.
Extending UI Components
Custom Widgets with Style Bindings
● The bundle contains a mix of Javascript and CSS resources
● Dojo Module Bindings attach custom behavior to OOTB widgets, while CSS bindings
attach custom styles to the OOTB stylesheet
<bundle_root>/resources/
| +--com/
| | +--mycompany/
| | +--widget1.js
| | +--widget2.js
| ... ...
| +--widget.css
| +--widgetRTL.css
| ...
+--/META-INF/
| +--/MANIFEST.MF
+--/plugin.xml

25.
26
Demos

26.
27
Questions?

27.
28
Questions?
Psst: perfect chance to request enhancements if you're a developer

28.
29
External References
● IBM Connections Product Documentation Wiki
– http://www-10.lotus.com/ldd/lcwiki.nsf/
● IBM Connections Application Development Wiki
– http://www-10.lotus.com/ldd/appdevwiki.nsf
● IBM Rational Jazz Community Site
– https://jazz.net/
● Jazz Web UI Development Book
– https://jazz.net/wiki/bin/view/WebUIBook/WebHome

29.
30
Claudio Procida is currently technical lead of the IBM Connections
Common UI development team. In the past, he was technical lead of the
IBM Connections Wikis team, and initiative lead for the Oauth 2
enablement of IBM Connections. He joined IBM in 2008 after having
spent a few years developing software for Mac OS X and LAMP web
applications. He is passionate about social software, agile development,
web components and the open web. Claudio has contributed to a number
of open source projects and also started a few of his own.
Email: procidac@ie.ibm.com
Twitter: @claudiopro
About

30.
31
Legal Disclaimer
© IBM Corporation 2014. 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 Oracle 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.