IBM Connections uses JavaScript extensively to build its applications and UI components. JavaScript resources are centrally served by the Common application and dynamically generated into layers based on dependencies. Modules can be written using the AMD or legacy Dojo format and aggregated. Extensions are supported through extension points like web bundles, themes, and module bindings. Developers can customize or extend Connections using these extension mechanisms.
IBM Connections Demystified: Extensions and Themes
1. IBM Connections
Extensions and Themes
Demystified
Claudio Procida <procidac@ie.ibm.com>
IBM Connections Technical Sessions
For Developers And Partners
2.
3. 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.
4. 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
5. 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>
6. 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
7. 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;
});
8. 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();
9. 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
10. 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
11. 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
12. 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>
13. 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>
14. 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>
15. 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>
16. 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>
17. 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>
19. 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
...
20. 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
21. 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>
22. 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
...
23. 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
24. 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
25. 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
29. 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
30. 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