Social Connections VI — IBM Connections Extensions and Themes Demystified

My deck on IBM Connections Extensions and Themes presented at the Social Connections VI event in Prague, 16-17 June 2014.

Transcript

1. IBM Connections Extensions and Themes Demystified Claudio Procida <procidac@ie.ibm.com> IBM Connections Technical Sessions For Developers And Partners
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>
18. 18 Cookbook
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
26. 26 Demos
27. 27 Questions?
28. 28 Questions? Psst: perfect chance to request enhancements if you're a developer
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
31. 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.