HelpSvc Class

com.bea.ide.ui.help
HelpSvc Class

public class HelpSvc

    extends Object

This service is used to find and display context-sensitive help topics from the IDE. In the local case, HelpSvc is also used to integrate new help into the help system's table of contents and search index.

When the IDE is started, HelpSvc constructs a help path consisting of locations where help topics may be found. The help path includes help provided with IDE extensions, help provided with third-party controls and API help such as Javadoc for the J2SE and J2EE APIs.

When F1 is pressed in the IDE, the implementation of IHelpDriver (if any) for the current view is found and IHelpDriver.getHelpContextList(IElement) is invoked (by the shell). IHelpDriver.getHelpContextList(IElement) returns an ordered array of context URNs that indicate the context for which help is being sought.

The list of context URNs is passed to HelpSvc.I.resolveContextAsync(URI[]), which attempts to resolve the context URNs against the entries in the help path. If resolution is successful, the topic is displayed in a browser via HelpSvc.I.displayHelp(URL)

Context-Sensitive Help

Context-sensitive help is a two step process. When help is desired for the current UI context (typically, when F1 is pressed), the IDE looks for an implementation of IHelpDriver on the current view. The IHelpDriver is invoked and returns an ordered list of context URNs (URNs). Context URNs uniquely identify the entity for which help is desired, such as a Java class, a language keyword, or a JSP tag from a tag library. Once the list of context URNs has been generated, the HelpSvc attempts to resolve the context URNs against a help path - a list of potential help topic locations.

The Help Path

HelpSvc constructs and maintains a help path, which is a list of potential locations for context-sensitive help topics.

The help path consists of the following:
  1. paths specified in extension.xml files with URN "urn:com-bea-ide:help", for all extensions
  2. paths to help content associated with "external components" (typically controls)
  3. arbitrary user-specified help path entries
  4. paths to API docs such as J2SE and J2EE Javadoc
The format for a "urn:com-bea-ide:help" entry in extension.xml is:
 <extension-xml id="urn:com-bea-ide:help">
     <help-root [parent="parent"] dir="directory"/>
     <help-root url="url-to-help-root/>
 </extension-xml>
 
directory the directory to be searched as a help root. directory is relative to parent and/or url.
parent a path to a directory relative to the extension directory of workshop. an absolute path may be used, but it is not recommended. If ommitted, the directory is assumed to be in the extension's own directory.
url-to-help-root an absolute URL that specifies a new help root. this may be any url, but will typically be htpp or file based.

A help-root may specify both a url and a parent. When the IDE help mode is "online", url will be used. When the help mode is "local", parent will be used.

Context URNs

Each context URN is of one of the following forms:

Some example context URNs are:

An implementation of IHelpDriver generates context URNs that are appropriate for selected items in that view. For example, a Java source editor would generate context URNs appropriate for the current location of the text cursor. This might be a keyword, an annotation (Javadoc tag), a variable (resolving to a class) or a method (also resolving to a class). In the case of a Java class, the list of URNs returned would reflect the inheritance hierarchy of the class, so that the most specific help topic would be found first, followed by less specific topics if the most specific topics do not exist.

Context-Sensitive Help Resolution

The HelpSvc may also be used to resolve a list of context URNs to a URL using the help path. Context URNs are described above.

When HelpSvc.I.resolveContextAsync(URI[]) is called with a list of context URNs, the help service attempts to resolve each context URN (converted to a relative URL) against each entry in the help path. If a resolution occurs, the complete URL to the resolved topic (which is "help path URL" + "context URL") is sent to a browser for display.

HelpDrivers

DocumentViews and FrameViews may have an IHelpDriver, which will generate context URNs for the current context when context-sensitive (F1) help is requested in that view.

Displaying Help

The HelpSvc provides three mechanisms for displaying help:
  1. call HelpSvc with the path to a specific help file, relative to a help path entry. The help service will attempt to resolve the path against the entries in the help path.
  2. call HelpSvc with an array of context URN URIs. The help service will attempt to resolve each of the context URNs against each of the help path entries, in order.
  3. call HelpSvc with a URL.
Locales and Internationalization The WebLogic Workshop help system is internationalized and will attempt to provide help for the current locale whenever such content is available. This is accomplished by using the placeholder $locale in help path entries.

A locale is a 2-letter ISO language code optionally followed by a 2-letter country/region code. The following are examples of locales:

When the help system attempts to resolve a URL, it attempts resolution by replacing the $locale placeholder with the following values, in order:
  1. the value of the system property workshop.help.locale
  2. the user's complete current locale
  3. the language code of the current locale
  4. en
The user's current locale is obtained by calling Locale.getDefault().

Related Topics

IHelpDriver


Hierarchy
Object
  HelpSvc

Nested Class Summary

public static interfaceHelpSvc.I
          

The interface that must be implemented by a help service provider.

Field Summary

protected static HelpSvc.I
instance
HelpSvc.I
 

Constructor Summary

HelpSvc()

 

Method Summary

public static HelpSvc.I
get()
get the single instance of this service.
 
Methods from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
   

Field Detail

instance

protected static HelpSvc.I instance

 

Constructor Detail

HelpSvc

public HelpSvc()
 

Method Detail

get() Method

public static HelpSvc.I get()
get the single instance of this service.