Customizing IBM Connections - LS2012

© 2012 IBM Corporation

AD201: Customizing IBM® ConnectionsTM 3.0.1Josh Ghiloni | Staff Software Engineer, IBM Connections Files | IBM

2 | © 2012 IBM Corporation

IBM’s statements regarding its plans, directions, and intent are subject to change or withdrawal without notice at IBM’s sole discretion.

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.


Agenda

■ What's Different in Connections 3.0.1 from 2.5?

■ Understanding the New Customization Process

■ Branding a Simple Website

■ Adding a custom widget to a community

■ Best Practices for Creating, Maintaining, and Debugging

■ Migrating Customization from Previous Versions

■ Questions and Answers


What Has Changed in 3.0.1 from 2.5?

■ Deploying changes to markup, style sheets, or images is much simpler

■ There is a new “Getting Started” page on the Homepage – this customizable page can help introduce users to your deployment

■ The header and footer now support JavaServer PageTM (JSP) logic, and it is easy to add new menus or links to the header

■ The log in page is shared by all applications in Connections and can be easily customized

■ Most text in the user interface is replaceable

■ Themes for communities are easier to deploy and manage

■ Daily and weekly email digests (part of the Following feature) can be changed


What Hasn't Changed (Much)?■ Customizing Profiles for your company is very similar to 2.5

■ Changing the business card

■ Adding custom widgets to Homepage, Profiles, or Communities

■ Defining custom languages for users to choose from

■ Blog customization


“Typical” Organizational Roles■ Administrators

─ Configure Connections to match organizational objectives─ Maintain installation and manage deploying customization─ Work with developers to update customization when fixpacks are deployed

■ Designers─ Determine how Connections should be branded within an organization─ Produce images and aesthetic guidance

■ Web Developers─ Implement branding and customization with HTML through JavaServer Pages (JSP), Cascading

Style Sheets (CSS), and JavaScriptTM

– Assume sufficient familiarity to make basic changes to JSP files─ Update customization when fixpacks or iFixes are applied─ Implement deeper customization of Profiles, Communities, or other components to fit

organizational objectives


Agenda■ What's Different in Connections 3.0.1 from 2.5?








How Can Customization Improve?■ Feedback from users, developers, support staff

─ Visual styling hard to change across the entire product, very piecemeal─ “Other” customizations require changing product code directly, which fixpacks could overwrite─ Login page not easy to change and different between each application─ Setting up a custom header and footer can be tricky in complicated networks

■ Goal #1: Make it simple to deploy customization■ Goal #2: Applying Fixpacks and iFixes should not delete customization■ Goal #3: Most customization should follow a similar pattern

■ Solution: Allow customer-provided files to override the installed files. Custom files are placed in a special shared customization directory. Removing the file from this directory undoes the customization.


More Details on Customization■ Content in the customization directory overrides installed content■ Works on many different file types – JSP, HTML, CSS, GIF, JPG, etc

FooterCustom Header

Custom Header FooterHeader

Customization Directory Installed Content User Sees

Custom FooterHeaderCustom

Footer FooterHeader

Custom Footer

Custom Header

Custom Footer

Custom Header FooterHeader


More Details on Customization (cont.)

1) Find the file you want to change from the installed application2) Copy the file into the customization directory at the correct sub-directory3) Make changes to the copied file4) Restart the affected applications on your application server5) Clear browser cache or change version stamp6) Done!

■ Connections manages deploying the custom file transparently – no separate server or additional configuration necessary

■ To undo, delete the customized file and restart the affected applications.■ The InfoCenter describes where you copy from and where you copy to –

generally, you copy the file from where it sits in the WAR to the same relative path inside of the common customization directory


More Details on Customization (cont.)■ Application-specific customization directories override the common

customization directory

Common Customization Installed Content Profiles User Sees Wikis User SeesProfiles Customization

FooterHeaderFooterHeader FooterHeader FooterHeaderFooter

FooterHeaderFooterHeaderFooter FooterHeaderFooter

FooterHeaderFooter FooterHeader FooterHeaderHeader

FooterHeaderHeader FooterHeader FooterHeaderFooterHeader

FooterHeaderFooterHeader FooterHeader FooterHeaderFooterHeader










Branding a Simple Site■ Convert the default look and feel to a Renovations branding■ Demonstrate linking a deployment to an intranet■ Enhance the log in page with a click-through agreement

1) Install IBM Connections 3.0.12) Turn on customization debug mode3) Restart the server

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Customizing_the_user_interface_lc3


Changing Colors

■ Open the style sheet file for the default theme in a text editor─ <websphere>/profiles/<profile>/installedApps/<cell>/Files.ear/qkr.share.files.war/

nav/common/styles/defaultTheme/defaultTheme.css■ Create a new, empty style sheet file in the common customization directory

─ <connectionsinstall>/data/shared/customization/common/nav/common/styles/defaultTheme/custom.css

■ Open custom.css file in a text editor─ Locate rules for sections of the page with accent colors – title bar and left navigation – in

defaultTheme.css─ Paste those rules in custom.css, and change the colors from light blue to red─ Save changes

■ Tip: defaultTheme.css contains most color settings for the product■ Tip: Figuring out which CSS rules control which elements can be difficult. Use

a tool like Firebug for Mozilla® Firefox® to locate the rules you want to change.


Changing Colors (cont.)

● Visit Connections in your web browser─ Clear your browser cache!─ http://<server>:<port>/profiles

■ Tip: If you are making extensive changes or sending CSS to an external party alter defaultTheme.css instead.


Adding a Logo Image

■ Create a new logo image for the site─ toolbar_logo.gif (306x66 pixels)

■ Copy the image to the common customization directory─ <connectionsinstall>/data/shared/customization/common/

nav/common/styles/images/toolbar_logo.gif■ Verify that the image appears in your browser

─ Open http://<server>:<port>/profiles/nav/common/styles/images/toolbar_logo.gif


Adding a Logo Image (cont.)

■ Open custom.css in a text editor─ Change the source URL for the logo in this file─ Minor style changes to align the menus with the logo─ Save changes

● Visit Connections in your web browser

─ Clear your browser cache!─ http://<server>:<port>/profiles

■ Tip: Any file you add to the common directory becomes available in all applications


Integrated Header

■ Locate the header file─ <websphere>/profiles/<profile>/installedApps/<cell>/Files.ear/qkr.share.files.war/

nav/templates/header.jsp■ Copy the header file to the common customization directory

─ <connectionsinstall>/data/shared/customization/common/nav/templates/header.jsp

■ Open the copied file in a text editor─ Create a new “Intranet” menu drop down by copying the “People” menu link─ Add a “Support Forum” link in the upper right─ Move the logo element in the page─ Save changes


Integrated Header (cont.)

■ Locate the header menu file─ <websphere>/profiles/<profile>/installedApps/<cell>/Files.ear/qkr.share.files.war/

nav/templates/menu/people.jsp■ Copy the header file to the common customization directory with a new name

─ <connectionsinstall>/data/shared/customization/common/nav/templates/menu/intranet.jsp

■ Open the copied file in a text editor─ Using the “People” menu as an example, create links pointing to intranet locations─ Save changes

■ Tip: Popup menus can use dynamic logic or JavaScript – very flexible■ Tip: Menu contents can be styled as desired


Integrated Header (cont.)

● Visit Connections in your web browser─ Clear your browser cache!─ http://<server>:<port>/profiles


Enhanced Log In Page

■ Locate the login JavaServer Page (JSP) file─ <websphere>/profiles/<profile>/installedApps/<cell>/Files.ear/qkr.share.files.war/

nav/templates/login.jsp■ Copy the style sheet file to the common customization directory

─ <connectionsinstall>/data/shared/customization/common/nav/templates/login.jsp

■ Open the copied file in a text editor─ Remove IBM branding and add informational text─ Add a very simple click through agreement using JavaScript─ Save changes


Enhanced Log In Page (cont.)

● Visit Connections in your web browser─ http://<server>:<port>/files/login


■ Locate the string resource file for the header and login pages─ Unzip the JAR file <websphere>/profiles/<profile>/installedApps/<cell>/Files.ear/lc.util.web-

3.0.jar to a temporary directory with a zip program─ In the temporary directory, find the file /com/ibm/lconn/core/strings/templates.properties

■ Create a new file in the string customization directory with the name─ <connectionsinstall>/data/shared/customization/strings/

com.ibm.lconn.core.strings.templates.properties■ Open both the existing resource file and the new file in a text editor

─ Copy the entire line (or lines) you want to change from the old to the new file─ Change text strings for the log in page to match branding─ Save changes

Altering Product Text


Altering Product Text (cont.)

■ Restart the Lotus Connections server■ Visit Lotus Connections log in page in your web browser

─ http://<server>:<port>/files/login


Getting Started Page

■ Create a new HTML file in the common customization directory─ <connectionsinstall>/data/shared/customization/common/

nav/gettingstarted/renovations.html

■ Open the file in a text editor─ Add informational text about guidelines for Renovations users. ─ Save changes to the file

■ Change the first <step> in gettingstarted-config.xml (as described in the InfoCenter)

─ Secure link: ${lcurl:homepage.secure}/nav/gettingstarted/renovations.html─ Unsecure link: ${lcurl:homepage}/nav/gettingstarted/renovations.html

■ Restart Homepage application

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Customizing_the_Getting_Started_tab_lc3




Getting Started Page (cont.)

■ Visit Connections Homepage in your web browser─ http://<server>:<port>/homepage










Why use custom widgets?■ Allows seamless integration of data into Communities, Homepage, or Profiles

─ Existing business applications─ IBM Connections Data─ Third party APIs

■ Uses flexible IBM iWidget architecture─ Development can target server-side, client-side, or both─ Can be used in other iWidget containers

■ Self contained─ All code in its own module─ Only references to module exist in configuration files

http://www-10.lotus.com/ldd/mashupswiki.nsf/dx/iwidget-spec-v1.0.pdf/$file/iwidget-spec-v1.0.pdf

http://www-10.lotus.com/ldd/mashupswiki.nsf/dx/iwidget-spec-v1.0.pdf/$file/iwidget-spec-v1.0.pdf


Adding widgets to communities■ Add a new <widgetDef> element under <resource type="community"> as

described in the InfoCenter─ <widgetDef defId="Twitter Feed" modes="view edit"

url="http://<server>:<port>/path/to/widget.xml"/>■ Restart Communities

■ Tip: The same procedure is used to add widgets to Profiles

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Enabling_custom_widgets_for_Communities_lc3










Best Practices: Creating

■ Only copy the files you need into the customization directory─ Reduce the number of files to manage─ Makes it easier to know what you have changed

■ Keep track of the changes you make through documentation or comments─ Put comments directly into JSP or CSS files to simplify merging─ Extensive changes may be difficult to update from release to release

■ Use custom.css whenever possible─ Easier to track your style changes and handle migration

■ Back up frequently, and have a process around deploying customization─ If you have a staging or test environment, it is easy to back up your old customization before

copying over the new customization─ If you rename or move the customization directory you will completely disable customization─ You may want to use a version control system for your customization folder

■ When you are ready to deploy, always update the version stamp─ This ensures that old versions of the site are removed from browser caches

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Required_postcustomization_step_lc3


Best Practices: Maintaining

■ Occasionally IBM will change a file you have customized■ All Fixpacks and iFixes will document which files are being changed

1) Back up your customization directory2) Disable all customization by renaming the customization directory3) Apply the iFix or fixpack4) Test that the fix has been applied successfully5) Identify any files that have changed in the fixpack that you have customized6) Compare each new file from IBM to your customized copy, and merge changes7) Rename your customization directory to the correct name8) Test your customization

● Most changes to supported customization files will be simple


Best Practices: Debugging

■ Use customization debug mode in test environments─ Changes take effect immediately─ Never use debug mode on a production server!

■ Why don't I see my changes?─ Check that the file is in the right location in the customization directory (#1 source of problems!)─ Clear your browser cache─ Restart the application (or server) if debug mode is off─ Syntax error in file you changed? Check that there are no errors being output to the page or to

the logs

■ Printing the list of customized files─ Enable IBM® WebSphere® trace for “com.ibm.lconn.core.web.customization.*=all”─ Restart the Connections application─ trace.log will contain customization debug information during application startup


Super-Secret Developer Tricks

■ Use Firebug to find out what style rules are being used where─ Install Firebug to Firefox and open Connections─ Find the visual element you want to change─ Right click the element and select “Inspect Element”─ In the bottom right corner you should see the “Style” tab – this lists all CSS rules affecting this

file. ─ If you click the link next to a rule you can find its location in the CSS, and then easily copy it to

custom.css for changing

■ Use Stylish to mimic changing custom.css─ Install Stylish to Firefox and open Connections─ Click on the Stylish icon in the bottom left, then select “Write new style” → “For <domain>” and

choose the right domain─ Give the stylesheet a name, and copy things into the @-moz-document chunk─ Your styles will now show up when you browse to the server─ Once you're satisfied, copied to custom.css and then disable the Stylish sheet









Migrating from 2.5 to 3.0.1

■ Style customization─ Some style rules have been changed, especially those that affect color and borders─ If you have added additional CSS files via the header, copy the contents of those files into

<connectionsinstall>/data/shared/customization/common/nav/common/styles/defaultTheme/custom.css

─ If you have a complete visual override, you may want to port your changes to the new format by following the InfoCenter topic “Making extensive color and style changes”

─ An example of the 2.5 theme (using the new style rules) is located at <websphere>/profiles/<profile>/installedApps/<cell>/Files.ear/qkr.share.files.war/nav/common/styles/gen1Theme

■ Header and Footer─ Because the header exposes new features in Connections 3.0.1, we recommend that you

migrate your changes on top of the new header─ An example of the 2.5 header as a JSP is located at:

<websphere>/profiles/<profile>/installedApps/<cell>/Files.ear/qkr.share.files.war/nav/templates/originalHeader.jsp


Questions and (Hopefully) Answers

■ More detail on a type of customization?■ Can I customize other things?

─ Yes, but support is limited outside of the types covered here. Change at your own risk, and consult with your support team.

■ Can support team answer customization questions?─ Yes, for directly supported customization, and can provide info about what files need to be

changed for other parts of the application─ Use recommended debugging steps – support team will ask you to work through those

■ Thank you!


Related Sessions (Highlights Only!)Insights and Innovation (22 in all)● INV204: A view into the future of IBM Connections and IBM Lotus® Quickr® (Tues 10:00)● INV301: IBM's Social Business Strategy (Tue 11:15)

Infrastructure and Deployment (15 in all)● ID221: What's New in IBM Connections 4 (Tue 11:15)● ID224: What's Coming in IBM Lotus Quickr and Beyond (Wed 1:30)● ID229: Make Your Microsoft® Stack Social with IBM Connections (Wed 3:00)

Cross-SWG Solutions Sessions (12 in all)● SPN210 The Social Enterprise: Social Analytics and your Workforce (Mon 3:45)● SPN214 Applying Social Business to Software Development Projects (Tue 1:30)

Application Development (6 in all)● AD204 Mastering the art of social application development (Wed 1:30)● AD203 Developing Custom Client Applications Using the IBM Connections APIs (Wed 11:15)

Other related sessions● ASK 101 Ask the Developers (Thurs 1:30pm)● ASK102 Ask the Product Managers (Thurs 11:15am)● FS216 Social App Throwdown (Wed 5:30pm)


Reference Material■ InfoCenter

─ Overview and common process - Link─ Extensive color and style changes – Link─ Customizing the Getting Started page - Link─ Changing the header - Link─ Changing product strings – Link─ Customizing Email Digests - Link

■ developerWorks – Customizing IBM Lotus Connections 3.0■ Lotusphere 2010 – SHOW303: Putting Sparkle in Your Social Applications!

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Customizing_the_user_interface_lc3

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Making_extensive_color_and_style_changes_lc3


http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Customizing_the_navigation_bar_lc3

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Customizing_product_strings_lc3

http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Customizing_email_digests_lc3

http://www.ibm.com/developerworks/lotus/documentation/lc3customize/

http://www.slideshare.net/curiousmitch/putting-sparkle-in-your-social-applications-customization-and-branding-with-the-new-ibm-lotus-connections-25


Example Files

Changing Colors ● Changes to custom.css to alter colors

Adding a Logo Image ● Add a new logo for the header● Change the styles which show the logo

Integrated Header ● Add a “Support Forum” link in the upper right● Add an “Intranet” menu to the header

Enhanced Log In Page ● Provide a simple click-through agreement before log in● Remove IBM specific image

Altering Product Text ● Alter the text on the Log In page

Getting Started Page ● Add a Renovations step to the Getting Started page


Legal Disclaimer© IBM Corporation 2012. 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.

IBM, the IBM logo, Lotus, WebSphere, Rational, Rational Jazz and Lotusphere are trademarks of International Business Machines Corporation 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.

Other company, product, or service names may be trademarks or service marks of others.

All references to Renovations refer to a fictitious company and are used for illustration purposes only.

Technology

Customizing IBM Connections - LS2012