ShowTable of Contents
Overview of IBM Eclipse HelpAdvisor Service
IBM® Eclipse HelpAdvisor Service (IEHS) is a customized portlet service in IBM® WebSphere® Portal Server. The service displays a Help topic in a pop-up window by using the Eclipse Help System Web Infocenter UI for JavaTM Specification Request (JSR) portlets. The topic is shown by use of the user's preferred locale from their WebSphere Portal user profile.
IEHS is composed of the following components:
HelpAdvisor Service interface. Defines the functionality that the service will provide and extends the com.ibm.portal.service.PortletService interface (see listing 1). This service ensures there is only one HelpAdvisor instance, shared among all portlets.
Listing 1. HelpAdvisor Service interface
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import com.ibm.portal.portlet.service.PortletService;
import com.ibm.wkplc.helpadvisor.*;
public interface HelpAdvisorService extends PortletService
{
/**
* Locate the HelpAdvisor singleton
*/
public HelpAdvisor getHelpAdvisor();
/**
* Display a help topic in the pop-up window
*/
public void showHelpTopic(RenderRequest request, RenderResponse response, String topic_ref);
}
. Implements the PortletServiceProvider interface of com.ibm.portal.portlet.service.spi package to enable use of the portlet service lifecycle methods in addition to its own service interface (see listing 2).
Listing 2. HelpAdvisor Service implementation
public class HelpAdvisorServiceImpl
implements HelpAdvisorService, PortletServiceProvider
{
public void init(Preferences servicePreferences)
{
/**
* Initialize this service by creating a HelpAdvisor and
* initializing it with the app_context definitions for base Portal
*/
}
private static synchronized void initHelpAdvisor()
{
if (s_helpAdvisor == null)
{
s_helpAdvisor = HelpAdvisorFactory.makeHelpAdvisor();
}
}
private Properties getConfig(Preferences prefs)
{
/*
* Read initialization parameters
* from <wp_profile>/PortalServer/config/config/services/helpadvisorservice.properties
* to contribute the app_context.xml files used by base Portal.
* The app_context files are listed in helpadvisorservice.properties with
* consecutive keys "appcontext1", "apppcontext2", etc
*
* Extension products should have their own properties files with the paths(s)
* to their app_context.xml files and call addAppContexts() directly.
*/
}
public HelpAdvisor getHelpAdvisor()
{
/**
* Return the HelpAdvisor
*/
}
public void showHelpTopic(RenderRequest request, RenderResponse response, String topic_ref)
{
/**
* Display a help topic using preferred language from Portal user profile
*
* Redirects the Portal Help pop-up window to the Eclipse Help Server
*/
}
public void showHelpTopic(PortletRequest request, PortletResponse response, String topic_ref)
{
showHelpTopic(APIConverterFactory.getInstance().getRenderRequest(request),
APIConverterFactory.getInstance().getRenderResponse(response),
topic_ref);
}
}
How IEHS works when a portlet calls its Help
The following steps are executed at run time when a portlet launches its Help; in this section, we have used the ManagePages portlet as an example:
1. A portlet is loaded along with configuration settings defined under config-param in portlet.xml file. Here we are more concerned with appId and helpjsp parameters (see listing 3).
Listing 3. portlet.xml file showing the config params
<config-param>
<param-name>helpjsp</param-name>
<param-value>WEB-INF/help/pageManagerHelp.jsp</param-value>
</config-param>
<config-param>
<param-name>appId</param-name>
<param-value>com.ibm.wp.admin.help.managing_pages</param-value>
</config-param>
2. A user pulls down the portlet menu and clicks Help, the portlet turns into Help ,mode and call its doHelp() method to take the necessary actions. In doHelp(), the portlet calls
AbstractAdminPortlet.java's do Help(). This class is available at:
ui\wp\code\wp.admin.common\src\com\ibm\wps\portlets\admin\AbstractAdminPortlet.java
3. AbstractAdminPortlet.java calls
helpAdvisor.getHelpContextRef(appId), which is retrieved from Step 1 (
com.ibm.wp.admin.help.managing_page).
4. IEHS refers to a configuration file,
com.ibm.wp.admin.help.managing_pages, which is available under the directory,
\PortalServer\config\config\service. This file contains key value pairs corresponding to
appId and
help html files. HelpAdvisor returns the corresponding context-ref (
com.ibm.wp.admin.help/admin/h_main_managing_pages.html), as shown in listing 4.
Listing 4. Mapping between appId and context-ref
<?xml version="1.0" encoding="utf-8" ?>
<app-contexts>
<app-context app-id="com.ibm.wp.admin.help.managing_pages" context- ref="com.ibm.wp.admin.help/admin/h_main_managing_pages.html"/>
<more entries....>
</app-contexts>
5. AbstractAdminPortlet.java calls
helpAdvisorService.showHelpTopic(portletRequest, portletResponse, contextRef).
6. HelpAdvisor Service redirects to the Help window, which displays on clicking over Help in the portlet menu, to the URL:
Note that:
- wps/iehs is a separate Web application running under WebSphere Portal Server, which is an Eclipse Help Web application.
- The document plugin, com.ibm.wp.admin.help, can be found under IEHS_war.ear\IEHS.war\WEB-INF\lib\eclipse\plugins\com.ibm.wp.admin.help.
- The Help file, admin/h_main_managing_pages.html, can be found inside the doc.zip, inside doc plugin.
Listing 5 shows the doHelp method in the AbstractAdminPortlet.java file
.
Listing 5. doHelp method in AbstractAdminPortlet.java file
public void doHelp(PortletRequest portletrequest, PortletResponse portletresponse)
throws PortletException, IOException
{
String helpJSP = portletrequest.getPortletSettings().getAttribute(CONFIG_PARAM_HELPJSP);
String appId = portletrequest.getPortletSettings().getAttribute(CONFIG_PARAM_APPID);
if(Product.isEclipseEnabled())
{
LoadISCHelp loadischelp = new LoadISCHelp();
loadischelp.ISCAdminHelp(portletrequest, portletresponse, helpJSP);
} else
if(appId != null && !appId.trim().equals(""))
try
{
HelpAdvisorService helpadvisorservice = (HelpAdvisorService)getPortletConfig().getContext().getService(com/ibm/wkplc/helpadvisorservice/HelpAdvisorService);
if(helpadvisorservice == null)
{
if(logger.isLogging())
logger.text("doHelp", "HelpAdvisorService is not found.");
getPortletConfig().getContext().include(helpJSP, portletrequest, portletresponse);
} else
{
HelpAdvisor helpadvisor = helpadvisorservice.getHelpAdvisor();
String contextRef = helpadvisor.getHelpContextRef(appId);
helpadvisorservice.showHelpTopic(portletrequest, portletresponse, contextRef);
}
}
catch(Exception exception)
{
if(logger.isLogging())
logger.text("doHelp", "An exception is caught.", exception);
getPortletConfig().getContext().include(helpJSP, portletrequest, portletresponse);
}
else
getPortletConfig().getContext().include(helpJSP, portletrequest, portletresponse);
}
How IEHS can be integrated by an application
A portlet application in WebSphere Portal Server can follow steps mentioned below to get the help using HelpAdvisorService.
1. Acquire reference to the HelpAdvisor Service, using Java Naming and Directory Interface (JNDI) to get the HelpAdvisorService (see listing 6):
a) First, define a class variable of type PortletServiceHome.
b) Then perform the JNDI lookup.
c) If the HelpAdvisorService is found, then set the PortletServiceHome variable; if PortletServiceHome is not null, then get the HelpAdvisorService.
Listing 6. JNDI lookup for IEHS
PortletServiceHome helpAdvisorServiceHome=null;
try{
Context ctx=new InitialContext();
// JNDI lookup for HelpAdvisorService
Object home = (PortletServiceHome)
ctx.lookup("portletservice/com.ibm.wkplc.helpadvisorservice.HelpAdvisorService");
if(home!= null){
helpAdvisorServiceHome = (PortletServiceHome) home;
}
}catch(javax.naming.NamingException ne){
ne.printStackTrace();
}
// HelpAdvisorService handler
if(helpAdvisorServiceHome!=null){
HelpAdvisorService helpAdvisorService =(HelpAdvisorService)
helpAdvisorServiceHome.getPortletService(HelpAdvisorService.class);
}
2. Get HelpAdvisor Service handler:
a) After getting the references to HelpAdvisorService, obtain HelpAdvisor config object using getHelpAdvisor method:
HelpAdvisor helpadvisor = helpAdvisorService .getHelpAdvisor();
b) Get context references for the portlet application using config. Object, like:
helpadvisor.getHelpContextRef(appId);
c) Finally, call showHelpTopic to get the Help contents in a separate dialog box:
helpAdvisorService.showHelpTopic(portletrequest, portletresponse, contextRef);
Conclusion
This article explained how IEHS works in WebSphere Portal Server to get the Help of a portlet application and how it can be consumed in any application. You can now take advantage of this service to enable your application with Help support.
Tell us what you think
Please visit this link to take a one-question survey about this article:
Resources
WebSphere Portal product documentation:
http://www-10.lotus.com/ldd/portalwiki.nsf/xpViewCategories.xsp?lookupName=Product%20Documentation
About the author
Deepak Gupta is Staff Software Engineer based at IBM's Delhi, NCR, India, facility, where he works on WebSphere Portal development and customer engagements and is currently the worldwide focal point for People Components for WebSphere Portal. He also is a SME for WebSphere Portal. Deepak holds a Bachelor degree in Computer Science and Eng. from the Indraprastha University, India. He can be reached at
deepak.gupta@in.ibm.com.