Sun Java System Portal Server 7.1 Developer Sample Guide

Chapter 11 Customizing the Service Providers

This chapter provides common customization tasks for modifying the Search provider and Discussion provider.

This chapter contains the following sections:

Overview of Customizing the Service Providers

The Portal Server software includes a search service and discussion service provider.

Overview of Customizing the Search Provider

The Search provider (SearchProvider) furnishes a basic reference user interface that contains both search and browse functionality. Search functionality includes basic search mode, and advanced search for more complex searches. You can perform specific field searches in advanced search mode. For example, while in advanced mode, you can search within the title, URL, last modified date, author, and so on.

SearchProvider provides a link for category browsing. In addition, you can create a taxonomy for the Search Engine along with category filter rules. You can browse through the taxonomy tree and view documents within a category through the Search provider interface.

Search Provider Design

The Search provider uses JSPProvider to access the Portal Server back end services. The Search provider users JavaServer Pages^TM (JSP^TM) helper tag libraries to avoid using Java^TM scriptlets. The searchServer is a global service list type attribute that is configured and updated at installation time. The Search provider is responsible for directing the search request to the appropriate back end Search Engine server.

See the Sun Java System Portal Server 7.1 Technical Reference for the display profile properties you can set for the provider.

Search JavaServer Pages and Tag Libraries

The Search provider consists of two stages (input form and results) and the JSPs used by the Search provider fall into one of those two stages.

The following Example 11–1explains the JSP layout for searchContent.jsp. In the input stage (Stage 1), searchContent.jsp makes use of searchMenu.jsp and psSearch.jsp to set up the initial interface. The basicSearch.jsp file is used for a basic search and advancedSearch.jsp file for an advanced search. The description menu (that is, the Full, Brief, and Title menus) is displayed for both basic and advanced searches by descMenu.jsp file. The browseHeader.jsp file defines the browse interface.

In the results stage (Stage 2), one of three JSPs is used: browseOnly.jsp file sets and executes the parameters for category browsing using the Search tag library, and includes the browseResults.jsp page; browseSearch.jsp file sets and executes the parameters for searching and browsing within categories using the Search tag library and includes browseSearchResults.jsp; and searchOnly.jsp file sets and executes the parameters for search using search the Search tag library and includes results.jsp and score.jsp for the match relevance. The pageFooter.jsp file displays the list of pages, Next, and Previous links.

Example 11–1 JSP Layout for `searchContent.jsp`

searchContent.jsp
	|
	|------>searchMenu.jsp
	|
	|------>psSearch.jsp
	|
	|------>basicSearch.jsp----->descMenu.jsp (if search mode is basic)
	|
	|------>advancedSearch.jsp-->descMenu.jsp (if search mode is advanced)
	|
	|------>browseHeader.jsp (if browse mode is selected)
	|
	|					STAGE 1 INPUT
	_______________________________________________________________________________
	|	|
	|	|				STAGE 2 INPUT
	|	|
	|	|--->browseOnly.jsp----->browseResults.jsp (category browsing in browse mode)
	|
	|------>browseSearch.jsp--->browseSearchResults.jsp (only for category search)
	|
	|------>searchOnly.jsp----->results.jsp--->score.jsp(displays the match relevance)
	|
	|------>pageFooter.jsp

See the Sun Java System Portal Server 7.1 Technical Reference for more information on the Search JSP files.

The Search JSPs use the following tag libraries, which ship with the Portal Server software:

Jakarta tag library, for any generic tags
Desktop tag library, for the Portal Server software related information
Search tag library to cover all Search Engine server access functionality and to provide a tag-based wrapper for the existing public search and SOIF API

See the Sun Java System Portal Server 7.1 Technical Reference for more information.

Overview of Customizing the Discussion Provider

The DiscussionProvider is JSPProvider based and hence customizable. It uses the Desktop themes. It retrieves data from the back end Search service using search taglibs and API. The discussions and comments are stored as separate Resource Descriptors (RDs) in the discussion database.

The DiscussionProvider includes features such as discussion threads, starting discussions based on documents or new topics, searching discussions, and rating discussions. By default, the Discussions channel is available on the sample portal for anonymous users. However, an anonymous user cannot subscribe to a discussion or edit the Discussion channel.

The DiscussionProvider supports a full view (through the Discussions channel) and a lite view (through the DiscussionLite channel.) It has the following main functions:

Start a new discussion from the discussion channel.
Start a new discussion based on web documents from the search channel.
Add a comment to an existing discussion or post a reply to an existing discussion.
Rate all discussions and comments. Note that the displayed ratings are based on an algorithm such that the rating for any comment goes up gradually. For example, a comment has to be rated important three times before it is marked as important.
Search all discussions and search within a discussion. These functions are routed to the search provider. The displaySearch property can be disabled if the search feature is not required in the discussion channel. Users can also search by rating in Advance Search.
Authenticated users can choose to subscribe to a particular discussion by selecting the subscribe link. The request is handled by the SubscriptionProvider. The displaySubscription property can be disabled if the feature is not required. By default, the value is true.

A Discussion Lite view retrieves main posts sorted by last-modified date and has pagination so users can access older discussions. View discussion displays each discussion subtree. The main item is displayed in detail and the subtree is displayed below the main item.

View discussion includes:

Several filters on the page. A document display can be based on filters such as document rating (irrelevant, routine, interesting, important, and must read).
Display preference can be set to threaded or flat display.

Expansion threshold helps to control displayed items in the subtree. The users can choose to expand only highly rated documents, or expand all or collapse all. Default value is collapse all. Expand all will expand all the filtered comments. It will also show a description of the discussion, provide a menu for rating the discussion, and allow the user to post a reply.

Discussion Service Channels

The DiscussionLite channel and the Discussions channel are based on the DiscussionProvider.

DiscussionLite Channel

The DiscussionLite channel displays the top twenty discussion titles (which can be reconfigured) and the date. The discussions are sorted by creation date (last modified) and the newest discussion is displayed first. The DiscussionLite channel view has links to view each discussion, view all discussions, and start a new discussion. All these links target the Discussions channel which gets displayed in the JSPDynamicSingleContainer.

Properties for this channel can be configured from the administration console. By default, there are no user editable properties for this channel.

Discussions Channel

The Discussions channel includes a full view that:

Shows detailed descriptions for the top eight discussions sorted in descending order. This can be reconfigured from the channel edit page.
Includes pagination so that users can see all the discussions.
Supports search. The search returns discussion and comment results.

Discussion JavaServer Pages and Tag Libraries

Similar to the search channel JSPs, the discussion channel JSPs have a query portion, a display portion, and use Desktop themes.

For more information on the channel specific JSP files, see the Sun Java System Portal Server 7.1 Technical Reference.

Tips for Customizing the Service Providers

This section provides some basic tips for customizing the search and discussion providers.

Debugging the Service Providers

The Portal Server software provides files to help debug the Search and Discussion providers.

The following directory contains various search log files:

PortalServer-DataDir/searchservers/search1/logs

The following search log file records the search query sent to the Search Engine by the Search server:

PortalServer-DataDir/searchservers/search1/logs/rdm.0.0.log

Location of JavaServer Pages

JavaServer Pages for the Search channel are in the PortalServer-DataDir/portals/portal-ID/desktop/default/SearchProvider directory.

JavaServer Pages for the DiscussionLite channel are in the PortalServer-DataDir/portals/portal-ID/desktop/default/DiscussionLite directory.

JavaServer Pages for the Discussions channel are in the PortalServer-DataDir/portals/portal-ID/desktop/default/DiscussionProvider directory.

Modifying JavaServer Pages

When you modify statically included JavaServer Pages, be sure to run the touch command, otherwise no changes are reflected. You need to either run the touch command on the top-level JSP file or on all JSP files. For example,

touch searchContent.jsp

touch *.jsp

Accessing Channels Directly

You can access the search channel directly at the following URL:

http://server:port/portal/dt?provider=JSPDynamicSingleContainer&JSPDynamicSingleContainer.selectedChannel=Search&last=false&action=content

Modify all the links to use these extra parameters in the URL. For example, edit searchMenu.jsp file as follows:

<nobr>&nbsp;&nbsp;<a class=noUnderline href="<%=dpurl%>?mode=basic">Basic Search</a>&nbsp;&nbsp;</nobr>

Replace the bold portion with:

http://server:port/portal/dt?provider=JSPDynamicSingleContainer&JSPDynamicSingleContainer.selectedChannel=Search&last=false&action=content

You can access the Discussion channel directly at the following URL:

http://server:port/portal/dt?provider=JSPDynamicSingleContainer&JSPDynamicSingleContainer.selectedChannel=Discussions&last=false&action=content

Customizing the Search Provider

This section describes how to perform some common customizations on the Search provider.

To Add last-modified to the Search Result Display

Modify searchOnly.jsp file by adding last-modified to the list of viewAttributes.

For example:

<search:setViewAttributes viewAttributes="hl-url,hl-title,hl-description,score,content-length,hl-classification,last-modified"/>

Modify results.jsp file to display the last-modified date for document results using the SOIF getValue tag.

For example:

<% if (formbean.getDescription().equals("full")) { %>
    <FONT color=<%=tFontColor%> face=<%=tFontFace%>><search:getValue soifAttribute="description" escape="false"/></FONT><BR>
    <FONT color=#707070 face=<%=tFontFace%>><search:getURL escape="true"/><BR>
    <search:getValue soifAttribute="content-length" id="sz"/>
    <search:getValue soifAttribute="last-modified"/><BR>
<% } %>

Run the touch command.

For example, type touch *.jsp.

Reload the Desktop to verify the change.

To Remove content-length from Search Results

(Optional) Modify searchOnly.jsp file by removing content-length from the list of viewAttributes.

The line to modify is the following:
<search:setViewAttributes viewAttributes="hl-url,hl-title,hl-description,score,content-length,classification hl-classification"/>
Remove content-length from this line.

Modify results.jsp file by removing the line that displays the content-length.

Comment the lines as shown here:

<%--
	<search:getValue attribute="content-length" id="sz"/>
	<jx:declare id="sz" type="java.lang.String"/>
	<%
		int sizek = 1;
		try {
			sizek = Math.max(1, (Integer.parseInt(sz) + 512)/1024 );
		} catch (Exception e) {
		}
	%>
	<i18n:message key="size" bundle="searchjsp"/>
	<%= sizek %>k&nbsp;
--%>"

Run the touch command.

For example, type touch *.jsp.

Reload the Desktop to verify the change.

To Remove author from the Advanced Search Interface

Comment out or remove the author related HTML from the advancedSearch.jsp file.

For example:

<!--     -->
<!-- To disclude the "author" row, remark out the following section -->
<!--     -->
<TR>
    <td valign=middle align=right height=40><FONT color=<%=tFontColor%> face=<%=tFontFace%>><nobr> <LABEL FOR="advAuthor">Author</LABEL>
    <SELECT NAME="authorOp">
    <OPTION VALUE=<%=SearchContext.CONTAIN%> <%=formbean.authorOpSelection(SearchContext.CONTAIN)%>>does</OPTION>
    <OPTION VALUE=<%=SearchContext.NOTCONTAIN%> <%=formbean.authorOpSelection(SearchContext.NOTCONTAIN)%>>does not</OPTION>
    </SELECT>contain&nbsp;</FONT></nobr></TD>
    <td valign=middle align=left height=40><INPUT TYPE="text" NAME="authorVal" id="advAuthor" VALUE= "<%=SearchContext.htmlEncode(formbean.getAuthorVal())%>"></TD>
</TR>

Comment out author- related lines in advQuery.jsp file.

if (!formbean.getAuthorVal().equals("")) {
    h = new HashMap();
    h.put(SearchContext.OPERAND, "author");
    h.put(SearchContext.OPERATION, formbean.getAuthorOp());
    h.put(SearchContext.VALUE, formbean.getAuthorVal());
    l.add(h);
}

Run the touch command.

For example, type touch *.jsp.

Reload the Desktop to verify the change.

To Add a New Field to Advanced Search

Uncomment the keywords section in advancedSearch.jsp file.

<!--     -->
<!-- To Include the "Keywords" row, unremark the following section -->
<!--
<TR>
<td valign=middle align=right height=40><FONT color=<%=tFontColor%> face=<%=tFontFace%>><nobr> <LABEL FOR="advKeywords">Keywords</LABEL>
<SELECT NAME="keywordsOp">
<OPTION VALUE=<%=SearchContext.CONTAIN%> <%=formbean.keywordsOpSelection(SearchContext.CONTAIN)%>>does</OPTION>
<OPTION VALUE=<%=SearchContext.NOTCONTAIN%> <%=formbean.keywordsOpSelection(SearchContext.NOTCONTAIN)%>>does not</OPTION>
</SELECT>contain&nbsp;</FONT></nobr></TD>
<td valign=middle align=left height=40><INPUT TYPE="text" NAME="keywordsVal" id="advKeywords" VALUE= "<%=SearchContext.htmlEncode(formbean.getKeywordsVal())%>"></TD>
</TR>
-->

Remove the  comment marks from this section.

Add the keywords to advQuery.jsp file.

if (!formbean.getKeywordsVal().equals("")) {
  h = new HashMap();
  h.put(SearchContext.OPERAND, "Keywords");
  h.put(SearchContext.OPERATION,formbean.getKeywordsOp());
  h.put(SearchContext.VALUE, formbean.getKeywordsVal());
  l.add(h);
}

Run the touch command.

For example, type touch *.jsp.

Reload the Desktop to verify the change.

Customizing the Discussion Channels

This section contains the following:

To Display Additional Fields in the List View of Discussions

Change directories to PortalServer-DataDir/portals/portal-ID/desktop/default/DiscussionProvider.

Modify query.jsp file and add xxx field to viewAttributes.

For example, add content-length as follows:

<search:setViewAttributes viewAttributes= "url,title,description,rd-rating,author,last-modified,rd-last-changed,rd-reference-id, rd-num-rating,rd-sum-rating,rd-peak-rating,rd-reference-url,htmldesc,content-length"/>

Add the new fields in fullDiscussionDisplay.jsp file wherever appropriate.

For example:
<search:getValue soifAttribute="content-length"/>

To Modify the Sort Order in List All Discussions Page

By default, discussions are sorted by the last-modified date/time. That is, discussions are displayed in a descending order with the latest or most recent discussion shown first.

To modify the sort order in list All Discussions page, modify the viewOrder property in fullDiscussion.jsp file. For example, you can reset the value below to author or rd-last-changed:

<jx:set var="viewOrder" value="-last-modified"/>

To Inherit Classification and readACL

If you have classified only the parent discussion manually or modified the access control for the parent discussion, you may want to inherit those values in discussion replies as follows:

Change directories to PortalServer-DataDir/portals/portal-ID/desktop/default/DiscussionProvider.

Edit feedbackProcess.jsp file and modify the values of inheritClassification and inheritReadACL.

By default, these are set to false. Reset them to true if you want comments to inherit the parent’s classification field and readACL field. Note that comments are automatically protected in this case.

Save the file.

Run the touch command.

For example, type touch *.jsp.

To Control Access to Discussions

This can be accomplished by one of the following two ways:

Modify the dbname property in the display profile for Discussions channel for each role to point to a different database.

In this case users in one role cannot view discussions created by users in a different role.

Chapter 11 Customizing the Service Providers

Overview of Customizing the Service Providers

Overview of Customizing the Search Provider

Search Provider Design

Search JavaServer Pages and Tag Libraries

Example 11–1 JSP Layout for searchContent.jsp

Overview of Customizing the Discussion Provider

Discussion Service Channels

DiscussionLite Channel

Discussions Channel

Discussion JavaServer Pages and Tag Libraries

Tips for Customizing the Service Providers

Debugging the Service Providers

Location of JavaServer Pages

Modifying JavaServer Pages

Accessing Channels Directly

Customizing the Search Provider

To Add last-modified to the Search Result Display

To Remove content-length from Search Results

To Remove author from the Advanced Search Interface

To Add a New Field to Advanced Search

Customizing the Discussion Channels

To Display Additional Fields in the List View of Discussions

To Modify the Sort Order in List All Discussions Page

To Inherit Classification and readACL

To Control Access to Discussions

Example 11–1 JSP Layout for `searchContent.jsp`