Customizing IBM Connections - LS2012

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

© 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.

2 | © 2012 IBM Corporation

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








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

Customization Directory Installed Content User Sees

Custom Custom
Header Footer Footer
Header Header

Custom Custom
Header Footer Header
Footer Footer

Custom Custom Custom Custom
Header Footer
Header Footer Header Footer


More Details on Customization (cont.)
1) Find the file you want to change from the installed application
2) Copy the file into the customization directory at the correct sub-directory
3) Make changes to the copied file
4) Restart the affected applications on your application server
5) Clear browser cache or change version stamp
6) 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

Profiles Customization Common Customization Installed Content Profiles User Sees Wikis User Sees

Footer Footer Header Footer Header Footer Header Footer

Header Footer Header Footer Header Footer Header Footer

Footer Header Footer Header Footer Header Footer Header Footer

Header Footer Header Header Footer Header Footer Header Footer

Header Footer Header Footer Header Footer Header Footer Header Footer


Agenda







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.1
2) Turn on customization debug mode
3) Restart the server


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
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

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

Integrated Header
■ Locate the header file
nav/templates/header.jsp
■ Copy the header file to the common customization directory
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
nav/templates/menu/people.jsp
■ Copy the header file to the common customization directory with a new name
nav/templates/menu/intranet.jsp

─ 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.)


Enhanced Log In Page
■ Locate the login JavaServer Page (JSP) file
nav/templates/login.jsp
■ Copy the style sheet file to the common customization directory
nav/templates/login.jsp
─ Remove IBM branding and add informational text
─ Add a very simple click through agreement using JavaScript
─ Save changes


Enhanced Log In Page (cont.)
─ http://<server>:<port>/files/login


Altering Product Text
■ 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 (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
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


Getting Started Page (cont.)
■ Visit Connections Homepage in your web browser
─ http://<server>:<port>/homepage


Agenda








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


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


Agenda








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


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 directory
2) Disable all customization by renaming the customization directory
3) Apply the iFix or fixpack
4) Test that the fix has been applied successfully
5) Identify any files that have changed in the fixpack that you have customized
6) Compare each new file from IBM to your customized copy, and merge changes
7) Rename your customization directory to the correct name
8) 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


Agenda







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!


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.


Customizing IBM Connections - LS2012

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Customizing IBM Connections - LS2012

Similar to Customizing IBM Connections - LS2012 (20)

More from Lidia Vikulova

More from Lidia Vikulova (20)

Recently uploaded

Recently uploaded (20)

Customizing IBM Connections - LS2012