IBM Connections - Customizing and Extending


Published on

Presented by Claudio Procida of IBM at Social Connections 1 on 4th July 2011.

  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

IBM Connections - Customizing and Extending

  1. 1. Customizing and ExtendingIBM ConnectionsClaudio Procida — Software Developer, IBM ConnectionsJuly 2011 1
  2. 2. NoteInformation regarding potential future products is intended to outline ourgeneral product direction and it should not be relied on in making apurchasing decision. The information mentioned regarding potentialfuture products is not a commitment, promise, or legal obligation todeliver any material, code or functionality. Information about potentialfuture products may not be incorporated into any contract. Thedevelopment, release, and timing of any future features or functionalitydescribed for our products remains at our sole discretion. All features are subject to change without notice ©2011 IBM Corporation
  3. 3. Customizing IBM Connections● IBM Connections is a white label product ─ Business Partners and ISSL often rebrand the software and make it look like the clients 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
  4. 4. 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
  5. 5. 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 Search search.war Wikis All features are subject to change without notice ©2011 IBM Corporation
  6. 6. 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
  7. 7. Customizable Resources (continued)● Strings ─ Blogs blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/ blogs.war/dojo/lconn/blogs/nls/strings.js ─ Bookmarks blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/ blogs.war/dojo/lconn/blogs/nls/strings.js ─ Communities comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/tango/web/resources/ comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/tango/web/taglib/ comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/lconn/communities/strings/ comm.web.war/WEB-INF/lib/comm.web.jar!/com/ibm/lconn/communities/strings/ comm.web.war/javascript/source/lconn/communities/nls/strings.js All features are subject to change without notice ©2011 IBM Corporation
  8. 8. 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/ ─ Activities oawebui.war/WEB-INF/lib/oawebui.jar!/com/ibm/openactivities/web/coreui/resources/ oawebui.war/WEB-INF/lib/oawebui.jar!/com/ibm/openactivities/web/coreui/servlet/ oawebui.war/WEB-INF/lib/oataglib.jar!/com/ibm/openactivities/taglib/ oawebui.war/WEB-INF/lib/oataglib.jar!/com/ibm/openactivities/taglib/resources/ ─ Files Files.ear/lconn.files.ui.jar!/com/ibm/lconn/files/strings/ Files.ear/lconn.files.ui.jar!/com/ibm/lconn/files/strings/ Files.ear/lconn.files.ui.jar!/com/ibm/lconn/files/strings/ All features are subject to change without notice ©2011 IBM Corporation
  9. 9. Customizable Resources (continued)● Strings ─ Wikis Wikis.ear/lconn.wikis.ui.jar!/com/ibm/lconn/wikis/strings/ Wikis.ear/lconn.wikis.ui.jar!/com/ibm/lconn/wikis/strings/ Wikis.ear/lconn.wikis.ui.jar!/com/ibm/lconn/wikis/strings/ ─ ... ─ Yeah, theres more! All features are subject to change without notice ©2011 IBM Corporation
  10. 10. 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
  11. 11. Customization ExampleReplace the welcome box title into Connections Wikis1)Locate the property file used by Wikis to render the welcome box: ─ File is <WAS_profile_dir>/installedApps/<cell_dir>/Wikis.ear/ is.jar/com/ibm/lconn/wikis/strings/ui_en.properties2)Locate the string key you want to override ─ WELCOME.PUBLICWIKIS.TITLE=New to Wikis?3)Create the <CONNECTIONS_CUSTOMIZATION_PATH>/strings directory4)Create a file in the customized strings directory, with the exact bundle name ● File name must be <CONNECTIONS_CUSTOMIZATION_PATH>/strings/ ui_en.properties5)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
  12. 12. 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.properties2)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
  13. 13. Customizing File Type Icons ● File type icons use sprited CSS backgrounds, so its 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
  14. 14. File Type Icons Customization ExampleGoal: customize the file type icon for Symphony presentation files1)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
  15. 15. 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
  16. 16. Troubleshooting UI Customization● If you didnt 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 “*=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
  17. 17. 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
  18. 18. 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 companys 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
  19. 19. 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
  20. 20. Customizing Email Digest Templates● Templates are written in Freemarker templating language ─ ─ 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 ─ All features are subject to change without notice ©2011 IBM Corporation
  21. 21. Customizing Email Digest Templates (continued)● Example excerpt from notification-config.xml <type name="weeklyDigest" notificationType="FOLLOW"> <channel enabled="true" name="email"> <property name="sender"></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"></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
  22. 22. 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
  23. 23. 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
  24. 24. 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
  25. 25. 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!● Its 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
  26. 26. External References● IBM Connections Product Documentation Wiki ─● IBM Lotus and WebSphere Portal Business Solutions Catalog ─ All features are subject to change without notice ©2011 IBM Corporation
  27. 27. Thank You!Questions? Suggestions? ©2011 IBM Corporation
  28. 28. 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 thecompleteness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, expressor implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBMwithout notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or anyother materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties orrepresentations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreementgoverning 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 whichIBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s solediscretion based on market opportunities or other factors, and are not intended to be a commitment to future product or featureavailability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that anyactivities 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 theymay 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 aretrademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark ofWebDialogs, 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 servicenames may be trademarks or service marks of others. ©2011 IBM Corporation