Introduction

The IBM Connections (IC) portlets integrates social data from IBM Connections in the WebSphere Portal environment with the similar user experience as the Connections UI. Customers and Business Partners can download the IC Portlets for WebSphere Portal from the Business Solution Catalog and have them deployed in their environment. However in many scenarios the portlets are not as-is consumable and hence needs to be customized to meet the specific needs. In this article we'll cover the out of the box configuration options available to achieve customization and the hook points for styling and extensibility of the out of the box portlets. This article focuses on the v3.0.1.1 onwards release of the portlets.

Customization

Customizing the pagination

IC portlets by default renders the pagination at the bottom of the displayed content list as shown below:




Users can change this to display the pagination at the top and bottom of the content by configuring the portlet. This option is available in the Configure mode of the Blogs, Bookmarks, Forums, Wikis, Activities and Profiles portlet.







After un-checking this option in Configure mode, user will see the following pagination in the respective portlet:




This pagination is useful in certain scenarios because it's possible to change the number of items to view per page as well as user can jump to a specific page directly from the current view.

Customizing the content headers display with/without skin in the portlet

While a user navigates within the portlet content from one screen to another, at every screen the portlet show the current screen content title e.g. If a user is viewing the Latest Entries in the Blogs portlet then the portlet title reflects the "Blogs", and when user goes inside an entry, then the entry title is displayed at the top as shown below:





Though this is the default behavior and is useful when portlets are skinless (which is the default skin of the portlets with the Portal 8 and later releases), this can be changed, if a customer is using the portlets with a skin. In that case, the portlet title area can be utilized to display the content title instead of displaying it within the portlet content as shown below:


This is called dynamic portlet title change. With this, as you navigate, the portlet title reflects the currently viewed item. This is done by changing the 'showContentTitleInPortlet' property (true by default) in the 'WP ConnectionsIntegrationService' Resource Environment provider (REP) in WAS admin console.

Customizing the navigation links to navigate within the portlet vs. in connections

IC portlets can be customized to open links in portlets vs. in connections via the setting 'Display link to open IBM Connections in a browser window' from the configure mode of the portlet. When this option is selected then by default, it Opens up in a new browser window, however, this can be changed to open in same window as mentioned here.


Note: This configuration is not available in Forums and Profiles portlets.

Customizing the CSS styles

IC portlets mainly use OneUI styles, however there are instances where custom styles are also being used and this is mainly to align the Portlets user interface with the Connections User interface.

Prerequisites

• Install a web inspector (e.g. Firebug on Mozilla Firefox, Webkit Inspector on Chrome or Safari, IE Developer Tools for Internet Explorer) to inspect the markup.

Recommended Workflow

1. Inspect the source of the Portlet area you desire to customize

2. Use the web inspector to inspect markup

3. Identify property files and CSS files that contain string keys, or CSS rules you wish to override

4. Make the changes

5. Use OneUI public documentation as a reference

6. Reload the user interface to ensure the result is satisfactory

Custom CSS files are available under lcaccelerator\css folder of the deployed Connections portlets application. After updating the styles in the CSS file, clear the browser cache and then refresh the page to load the updated CSS files.

Styles are also used to show/hide certain user actions in portlets, as mentioned here.

Customizing the Product strings

Follow the procedure below to change the labels in the portlets, e.g. the confirmation messages, error messages, view names etc.

• Identify a label in the user interface that you want to customize e.g. Public Bookmarks (the name of the Public Bookmarks view in Bookmarks portlet)

• Locate the property file used by the component to declare the string resource.

• All portlets use the property file at \WEB-INF\work\classes\com\ibm\lconn\lcaccelerator\resources_en.properties for the labels.

• However in addition, Forums portlet also uses the property file \WEB-INF\work\classes\com\ibm\lconn\lcaccelerator\resources\forumResources\resources_en.properties and

• Wikis portlet also uses the property file \WEB-INF\work\classes\com\ibm\lconn\lcaccelerator\wikiResources_en.properties for defining the respective labels.

• Locate the string key you want to override e.g. bookmarks_all=Public Bookmarks

• Override the string

• bookmarks_all=All Bookmarks

• Reload the page.

Extending/Integrating with IC portlets

IC portlets publish and subscribe events in form of Public Render Parameter as well as through Property broker event using wiring interface in Portal.

Property broker events supported by the IC portlets

The first property broker event is SelectedTag event wherein the portlets receive the tag from the Tags portlet when wired and filter the content according to the tag selected. The definition of this event looks like this:

Blogs, Forums, Wikis, Bookmarks, Profiles and Activities portlets supports this event.

The next property broker event is the 'TagsPayload' wherein the tags portlet shows the tags as per the url specified in the event payload. Here is the definition of this event:

Sample payload format for firing this event is as below:

<payload><tagsURL>https://cldegdg6.in.ibm.com:9444/blogs/home/feed/tags/atom?lang=en_us</tagsURL><portletName>Blogs</portletName></payload>

in the above format tagsURL is the tags feed url and portletName is one of

Blogs, Forums, Wikis, Bookmarks, Profiles and Activities. This event is processed by the Tags portlet and Blogs, Forums, Wikis, Bookmarks, Profiles and Activities portlets publish this event.

Public Render parameters (PRP) processed by the IC portlets

IC portlets process two public render parameters as below. First one is defined as below:

connectionsPOC PRP is used during the interportlet navigation to share the content definition between the portlets. This PRP is set by the Piece of Content servlet (POC) and, besides setting the PRP, the POC also navigates users to the appropriate page. Refer to the Custom URI syntax for the syntax of the URL to invoke POC and generate this PRP.

The next PRP processed by IC Portlets is connectionsCOMMROLE which is defined as below:

When there are Portal pages mapped to the community (Mapping a page to community) in connections, then connectionsCOMMROLE holds the role of logged-in user in the respective community. This PRP is published by the Community overview portlet for the respective community. A user may Join or Leave the community from Community Overview portlet, and this PRP then reflects the role accordingly. Depending upon the user's role in the community, the connectionsCOMMROLE holds following values:

• NON_MEMBER@communityID

• member@communityID

• owner@communityID

Conclusion

You should now be familiar with the various ways IC portlets can be customized and extended, as well as how third party portlets can interact with the IC portlets.

Resources

IC portlets 3.0.1.1 documentation

http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+3.0.1+documentation#action=openDocument&res_title=IBM_Connections_3.0.1.1_Portlets_for_WebSphere_Portal_ic301&content=pdcontent

IC portlets 4.5 documentation

http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=Integration+Plug-ins+Documentation+for+IBM+Connections+4.5#action=openDocument&res_title=IBM_Connections_Portlets_for_WebSphere_Portal_lv45&content=pdcontent

Participate in the discussion forum:

http://www.ibm.com/developerworks/forums/forum.jspa?forumID=168

WebSphere Portal Server Version 8.0 Product Documentation:
http://www-10.lotus.com/ldd/portalwiki.nsf/xpDocViewer.xsp?lookupName=IBM+WebSphere+Portal+8+Product+Documentation#action=openDocument&content=catcontent&ct=prodDoc

developerWorks WebSphere product page:
http://www.ibm.com/developerworks/websphere/zones/portal/

About the author

Jyoti Rani is based at IBM's India Software Labs, working in the domain of ICS for the past 8.5 years. His technical expertise lies in WebSphere Portal platform and application development on WebSphere Portal using Web Experience Factory. You can reach her at jyotirani10@in.ibm.com.