Customizing and extending the functionality of the IBM WebSphere Portal 6.1 Search Center portlet

Thanks to the new architecture of the IBM® WebSphere® Portal V6.1 Search Center portlet, redesigning the Search Center has never been easier. Learn how you can add functionality such as advanced search options to the existing Search Center portlet and replace the display by supplying your own widgets.


Eitan Shapiro, Software Engineer, IBM

Eitan Shapiro holds a BSc degree in Information Systems Engineering from the Technion, Haifa, Israel. He joined IBM in 2005, and he is the Team Lead of the Enterprise Information Discovery team that develops search solutions for WebSphere Portal and Lotus® Quickr™.

Boaz Ben-Nahum, Software Developer, IBM

Boaz Ben-Nahum holds a BSc degree in Computer Science from the Technion, Haifa, Israel. He joined IBM in 2004, and he is developing search front-end, UI, and AJAX applications for WebSphere Portal and Lotus Quickr.

30 December 2008 (First published 30 September 2008)

Also available in Japanese

IBM WebSphere Portal V6.1 provides many new features, one of which is the revamped Search Center portlet. The Search Center portlet has been redesigned to be Dojo and Asynchronous JavaScriptâ„¢ and XML (AJAX) based. Also, two portlets have been added to allow integration of search results from other content sources, such as external search engines and a predefined search collection for supporting the Suggested Links scenario.

The most important change, however, is in the Search Center architecture, which now lets you develop additional search-related applications based on your specific needs. You can add functionality such as advanced search options to the existing Search Center portlet and replace the display by supplying your own widgets. This article explains the new customization options in the Search Center page of WebSphere Portal V6.1 and provides detailed examples with code snippets.


You should have a basic understanding of portlet development, JSP, and JavaScript to get the most out of this article. We also rely on some features of the JSR 286 specification. To customize the display of search results, you need a good understanding of JavaScript and familiarity with the Dojo toolkit.

In addition, before you can customize the Search Center portlet, you need to have access to an installed WebSphere Portal server, on which you have two options for development. One option is to find the portlet under the <installableApps> directory and reinstall the portlet after modifying its code. Another option is to make the changes directly to the installed portlet on the server and then copy the changes to the portlet in the <installableApps> directory for future redeployment. The portlet is located on disk at \wp_profile\installedApps\<node>\PA_Search_Center.ear\searchCenter.war.

Understanding the Search Center architecture

Before diving into specific customization options, let's discuss the Search Center architecture. This overview describes the relationship between the different portlets on the page and the communication model of the portlets. We also go into more detail about the internal structure of the central Search portlet, its internal Dojo widgets, and the communication model between the widgets.

Search Center portlets

The Search Center page in WebSphere Portal V6.1 is composed of three different portlets, as described in table 1.

Table 1. Search Center portlets in WebSphere Portal V6.1
Portlet name Description
Search CenterDisplays search results from WebSphere Portal collections
Suggested Links Displays additional results from a predefined search collection
External Search ResultsDisplays search results from an external search engine, such as Web or enterprise search engines

The three portlets adhere to the Javaâ„¢ Portlet specification, version 2.0, which is also known as JSR 286. The portlets use a new feature of this specification, public render parameters, to share the query parameter between the portlets. Sharing the query parameter allows users to click the search button once and simultaneously receive search results from the three different content sources.

The deployment descriptor for the Search Center portlet application (portlet.xml) includes the definition of this public render parameter as shown in listing 1.

Listing 1. The public render parameter
	<qname xmlns:search="">

Each portlet declares its support for this public render parameter inside the definition of the portlet:


Whenever users submit a query, a new query action is performed in the Search Center portlet, which in turn sets the value of the public render parameter searchQuery to the search text that the user submitted. The portlet container of WebSphere Portal then distributes the query parameter to the other portlets.

One of the obvious ways to extend the Search Center functionality is to add a new portlet to the Search Center page. This portlet can listen to the same query event and enrich the search experience by returning more search results or any other relevant information. For example, you can develop a portlet that shows similar queries issued by other users or that displays bookmarks that are tagged with one or more terms from the query.

Search Center widgets

All portlets on the Search Center page use AJAX to retrieve the search results from the search back-end system. Hence, the search results are retrieved during neither the action nor the render phases of the portlet. Instead, the results are retrieved through an additional HTTP request that is initiated from the portlet's JavaScript code that runs on the client's browser, after the rendering of the portlet is complete.

For example, the main result set is retrieved from the WebSphere Portal search engine through the WebSphere Portal search Representational State Transfer (REST) service, which is described in the developerWorks® article, "Integrating IBM Lotus Sametime with the IBM Lotus Quickr Search REST service." The use of AJAX enhances the user experience because the search against the different systems takes place in parallel, and the results are immediately displayed when they are retrieved from any of the systems.

The widget architecture is presented in figure 1. Each portlet initializes two custom Dojo widgets that are responsible for fetching the results from the back-end servers and displaying the results to users. We call these widgets the fetcher and the displayer, respectively. The widgets communicate with each other using Dojo topics, a form of communication that allows loose coupling between components. Each widget can publish events to a specific topic and subscribe to events from other topics.

To isolate each pair of widgets from other widgets on the same page, each pair of fetcher and displayer widgets is contained by a SearchService widget, whose sole purpose is to define the topics that are used for communication between the two child widgets.

Figure 1. The widget architecture inside each of the search portlets
The widget architecture inside each of the search portlets

Notice that the fetcher widget is an invisible component that only sends AJAX calls to the back-end servers, while the displayer is responsible for rendering the results on the screen. This architecture enables you to change the look by replacing only the display widget. Table 2 lists descriptions of the possible topics (event messages) between the fetcher and displayer.

Table 2. Supported Dojo topics between the fetcher and displayer
Dojo topic nameDescriptionUsed in
DISPLAY_RESULTS The fetcher issues a search query using AJAX. When the fetcher retrieves the search results, it passes the results to the displayer for rendering.All portlets
NEXT_PAGE Users ask for the next page of results. The displayer asks the fetcher to get the next page of results. When the results are ready, the fetcher notifies the displayer, using the DISPLAY_RESULTS topic.The Search Center portlet
PREV_PAGEPREV_PAGE is similar to NEXT_PAGE but is used for getting the previous page of results.The Search Center portlet
ITEMS_PER_PAGE Users select a different number of items to display on the search page. The displayer asks the fetcher to retrieve this new number of search results. When the results are ready, the fetcher notifies the displayer, using the DISPLAY_RESULTS topic. The Search Center portlet

Empowering users with customized advanced search

Advanced search is one of the more common and useful features in search applications, enabling sophisticated filtering of the search results. The main problem with implementing advanced search is that it is largely based on the content metadata, which is not uniform across all corporations. In this section, we demonstrate how to add filtering that is based on the indexed content metadata by manipulating only a few lines of code.

Here we provide some advanced search examples that we explore (see figures 2 and 3), and we also provide step-by-step instructions on what code modifications are required for adding author and title filters.

Figure 2. Searching for documents with a specific author name
Searching for documents with a specific author name
Figure 3. Searching for documents with specific terms in the title
Searching for documents with specific terms in the title

Adding advanced search

Adding advanced search options to the WebSphere Portal V6.1 Search Center is as simple as manipulating a single JSP file: the Search Center's main JSP file, SearchCenterPortletView.jsp, which can be found at:


First, let's add the title and author as parameters to the search form (see the relevant code snippet in listing 2). Notice that the changes are marked by bold text. This code adds two text boxes with the labels "author" and "title" to the Search Center. The boxes are filled from two portlet render parameters, searchByTitle_Render and searchByAuthor_Render.

As previously described, the portlet refreshes and sends relevant messages to all other portlets on the page for each search operation before sending Dojo Topic messages between the widgets. Because of this round trip to the server, we manage the information about the author and title in the portlet render parameters and refill the boxes after refresh.

Listing 2. Adding the title and author filters to the Search Center (changes are in bold text)
<div dojoType=""
language="'<c:out value="${queryLang}"/>'"
submitUrl="<portlet:actionURL><portlet:param name="javax.portlet.action"
<label>Title: </label>
<input type="text" class="text" name="searchByTitle" value="<c:out
   	<label>Author: </label>
<input type="text" class="text" name="searchByAuthor" value="<c:out

To force the portlet to publish the two new render parameters, you must modify some portlet parameters. The first change notifies the portlet of two new action parameters, searchByTitle and searchByAuthor. For each action parameter, the portlet creates a new render parameter with the suffix _Render; for example, searchByTitle_Render and searchByAuthor_Render.

You must add searchByTitle and searchByAuthor to the Portlet parameter additionalQueryParams so it looks like this:


The second code change involves reading the title and author values and setting them in the JavaScript query object that is being used when submitting the query. The relevant code is shown in listing 3, in which changes are shown in bold text. The values are read from the portlet render parameters and not directly from the text boxes.

Listing 3. Filling in the JavaScript query object with author and title filters information
function <portlet:namespace/>initSearch() {

..... (some code around scopes)

	var query = "<lwp:escape type="javascript"><c:out value=
"${param.searchQuery}" escapeXml="false"/></lwp:escape>";
	var queryObject = new{
		text: query,
		language: "<c:out value="${queryLang}"/>",
		scope: scopeObj
var titleSearchValue = "<lwp:escape type="javascript"><c:out 
var authorSearchValue = "<lwp:escape type="javascript"><c:out 
	if (titleSearchValue.length > 0) {

"title", titleSearchValue));
	if (authorSearchValue.length > 0) {
"author", authorSearchValue));

	if (queryObject.getFullQueryText().length > 0) {
		dojo.publish(, [queryObject]);

The code for the new method createAdvancedQuery, which is used in the method initSearch, can be seen in listing 4. The method handles the scenario of multiple terms in the advanced query and adds the terms as multiple filters with OR between them.

Listing 4. New method of createAdvancedQuery
function <portlet:namespace/>
createAdvancedQuery(/*String*/ field, /*String*/ value) {
	var words = value.split(" ");
	if (words.length == 1) {
		return "+" + field + ":" + value;
	var buffer = [];
	for (var i = 0; i < words.length; i++) {
		if (i != 0) {
			buffer.push(" OR ");
	return buffer.join("");

In the Download section of this article, you can find the SearchCenterPortletView.jsp file that includes all the required code changes from this example.

Redesigning the look of the search results display

When considering customizations of the WebSphere Portal Search Center, the most common need is to modify or replace the look and feel of the search results display. To do this task in earlier WebSphere Portal versions, you had to write your own portlet. Now, thanks to the new version 6.1 Search Center architecture, you can replace the whole area in the portlet that is responsible for displaying the search results, simply by replacing the display widget.

In this section, we describe the process of replacing the results display widget, using an example in which the results display widget is replaced with a TreeMap view widget. Even though a TreeMap is not our recommended way for displaying search results, it's an interesting option because it shows you the following three dimensions of information about the search results:

  • Size. The size of the search results box is determined by the score (relevance) of the result.
  • Color. The color indicates the source of the search result, either a WebSphere Portal collection or a Web collection.
  • Shade. The shade is determined by the last modified date of the result. A bright color means a recent update date.

Figure 4 shows the Search Center when results are displayed by the TreeMap widget. The issued query is "ibm websphere" and is executed against two collections. The first collection is a WebSphere Portal collection that includes all the portlets in the system, and the second collection is a Web collection that contains articles from the IBM developerWorks site. The TreeMap displays 21 search results; those from WebSphere Portal are displayed on the left side in blue, and those from developerWorks are displayed on the right side in green.

Figure 4. Displaying search results in a TreeMap
Displaying search results in a TreeMap

Replacing the search results display widget

The first step in replacing the widget is writing a new widget. The file that holds all the search widgets in the Search Center portlet is called DisplayResultsWidgets.js, but we create a new file and call it DisplayResultsTreeMap.js. This new JavaScript file should be packaged as part of the portlet, unlike the other file, which is located in a shared location on the server for Dojo widgets. The widget is packaged as part of the portlet because it serves only one portlet, the Search Center portlet.

Next, we import this JavaScript file in the main JSP file, SearchCenterPortletView.jsp, and we replace the ResultsDisplayWidget method with the new ResultsDisplayTreeMapWidge method. Here are the detailed steps along with relevant code snippets:

  1. In the Download section of this article, you can find the DisplayResultsTreeMap.js file that includes a full TreeMap widget implementation and its XSLT file, resultsTreeMap.xsl. Create the directory \Javascript\ibm\portal\search\ext under \wp_profile\installedApps\<node>\PA_Search_Center.ear\searchCenter.war and copy the files to this location.
  2. Find and open the main JSP file, SearchCenterPortletView.jsp. Add the two lines of code (shown as three lines) in listing 5, which add the new path on disk to the JavaScript code path and also import all the widgets from this new JavaScript file.

    Listing 5. Import the TreeMap widget to the SearchCenterPortletView JSP file
    dojo.registerModulePath("", "<c:out value=
  3. Replace the widget that is used for the results display by finding the line <div dojoType=""…></div> and replacing it with the code shown in listing 6. Notice that most of the code consists of new style definitions that are used in the TreeMap widget.

    Listing 6. Use the ResultsDisplayTreeMapWidget in the SearchCenterPortletView JSP file
    .contentCell {
    	text-align: center;
    	width: 100%;
    	height: 100%;
    	border: solid 1px #FFFFFF;
    	vertical-align: middle;
    	overflow: hidden;
    	z-index: 0;
    	cursor: pointer;
    .mapFragment {
    	position: absolute;
    	top: 0px;
    	left: 0px;
    .container {
    	position: relative;
    	width: 100%;
    	height: 400px;
    span.contentLink {
    	padding: 5px;
    <div dojoType=""></div>

How the TreeMap widget works

A TreeMap widget is a method for displaying tree-structured data using nested rectangles. It was conceived by Professor Ben Shneiderman in the early 1990s. TreeMaps display rows of data as groups of rectangles that can be arranged, sized, and colored to graphically reveal underlying data patterns. This visualization technique allows users to easily recognize complicated data relationships that are otherwise not obvious.

The TreeMap implementation included in this article is completely based on JavaScript. It implements the Squarified Treemaps Algorithm to create a TreeMap with square-like rectangles that are easier to compare and select than thin, elongated rectangles. The general flow of the TreeMap widget is as follows:

  1. Convert the search results Atom feed retrieved from the server to an array of JavaScript objects.
  2. Assign each result with a base color (based on the category of the result), a weight (based on the relevance of the result), and a color weight (based on the date of the result). All weights are normalized on a scale from 0 to 1.
  3. The creation of the actual TreeMap involves two steps:
    • First, build a high-level TreeMap for the different categories. The weight of each category is the sum of the weights of all the results in that category.
    • Second, build the actual TreeMap for the results by using the specified algorithm. When the algorithm is finished, each search result is assigned a rectangular cell whose size is proportional to the weight of the result.
  4. Create a view for each cell, with each view containing a link to the actual search result. The exact color of the cell is now determined according to the base color and the color weight of each result. The font size is also set in proportion with the size of the cell.


You no longer need to rewrite the entire Search Center portlet to perform customizations. This article presented new customization options for the Search Center page of WebSphere Portal V6.1 that are now possible due to the Search Center portlet redesign. The new Dojo- and AJAX-based architecture lets you develop your own search-related applications that can seamlessly work with the main search portlet. We have shown how you can add functionality, such as advanced search, to the existing Search Center portlet by manipulating JSP files and how you can replace the display by supplying your own widgets.


Code sampleTreeMapRev.zip5.16KB
Code sampleSearchCenterPortletView.jsp7.36KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Customizing and extending the functionality of the IBM WebSphere Portal 6.1 Search Center portlet