The WebLogic Workshop help system contains a collection of HTML pages that are organized in a table of contents. In addition, a user can search the help pages and receive context-sensitive help by selecting an element in Source View or Design View and pressing F1.
When you are creating help for WebLogic Workshop extensions and controls that are intended for redistribution, you can take full advantage of the features of the WebLogic Workshop help system. That is, you can create help pages that are visible in the table of contents, are searchable, and can be accessed through context-sensitive help. This topic describes what you need to know to author help topics and add these to the WebLogic Workshop help system.
This topic contains the following sections:
The guidelines provided below describe how to create and structure your help files so that they integrate smoothly with installed WebLogic Workshop documentation. Note that how these files are handled when the extension is installed differs between controls and other kinds of extensions.
For extension help that follows the guidelines in this topic, WebLogic Workshop provides support for the following:
In version 8.1 SP3, WebLogic Workshop supports automatic integration for documentation provided with Java controls.This means that if you follow the guidelines in this topic and include your help in a control deliverable ZIP file, your help files will be automatically integrated. See Packaging Controls for Installation for more information on creating a control deliverable.
When the user installs a control deliverable for the first time, the IDE does the following to integrate the help provided with the control:
For other kinds of extensions, you must copy your documentation to the correct location — for example, you can do this with an installer program. In addition, after installation, you must rebuild the table of contents and search index to integrate your content with the Workshop documentation.
For seamless integration that does not require the user's help, your installation process should do the following:
java -Djava.system.class.loader="workshop.core.AppClassLoader" -cp wlw-ide.jar;wlw-rebuild-index.jar workshop.core.IndexIdeHelp
You can find the wlw-ide.jar and wlw-rebuild-index.jar files on the user's machine in the $WL_HOME/workshop directory.
If your installation process is unable to invoke IndexIdeHelp class, you should prompt the user to index help by clicking Help -> Rebuild Search Index. Your help will not appear in the table of contents or be visible to full-text search until one of these procedures has occurred.
Note: For material you can use to build and test your help installation, see the Help Test Kit at the WebLogic Workshop Extensibility Portal page at dev2dev.
Your help topics should be organized as described in the following list. Note the presence of <locale> and <vendor_name> placeholders for folder names. The <locale> placeholder represents the locale for the content. This would be "en" for English, "ja_JP" for Japanese, and so on. The <vendor_name> placeholder represents your company name, such as "Acme". All English locales use "en", not "en_US" or "en_UK", etc.
Note: As of WebLogic Platform 8.1 Service Pack 3, the IDE help system changed the way localized content is handled. The help system now uses <locale> instead of <language> to identify localized content. Hence, if a user attempts to install localized help that was intended for use with 8.1 SP2 or earlier, the user may need to change the name of the directory containing the localized help from <language> to <locale> (e.g. from "ja" to "ja_JP").
Note: You should choose the name of the <vendor-name> directory carefully. A user may have a large number of extensions installed on his or her system. The name of your vendor directory should clearly and uniquely identify your company and product name.
Note: You should not include the workshop.css file in your <locale> folder with your packaged control. If the file is present in your system, your installer may overwrite the installed version. In other words, the file is useful for authoring topics and applying styles, but should be ignored during packaging.
All segments of the path are case-sensitive; the HTML file name must have exactly the same capitalization as the class name. Note that while the directory structure is the same as produced by Javadoc, the content of the files does not have to be Javadoc output. Javadoc is a convenient tool for producing reference documentation for Java classes, but you could place a manually constructed (non-Javadoc) conceptual topic at the expected location if you desire.
WebLogic Workshop requires that help topics are HTML files. You can use the HTML editor of your choice to write them. To make these pages look and feel like the other help pages in WebLogic Workshop help, your topics should reference the CSS file workshop.css, which is included with the ControlDevKit sample at ExtensionDevKit/ControlDevKit/DBScripter/help/doc/en.
The workshop.css file contains detailed comments for each of the styles used. The styles you are most likely to use are:
To insert a link in your document, you can add the standard HTML tag <a href>. You can use relative links to refer to other help topics you provide. To refer to help topics in WebLogic Workshop help, you can either link to the online documentation at http://edocs.bea.com, or you can use relative links. Note that for relative links the path will include the folder weblogic81, which is the default version-specific product installation directory for WebLogic Workshop. During installation, users have the option of using a different folder name instead, and if they do so, relative links from your help topics to WebLogic Workshop help will no longer work.
Through JavaScript functions provided with WebLogic Workshop, your help topics can support three features that are available with the Workshop help system:
The JavaScript files and functions described here are included in the Help Test Kit, which you can find at the WebLogic Workshop Extensibility Portal page at dev2dev. You are strongly encouraged to use the Help Test Kit to validate your topics before packaging your extension for distribution. Also, use the included files for testing only; they are not needed in your deployed help because the files are present with WebLogic Workshop installed documentation.
To ensure that your topics have access to all of the functionality exposed by the help system, you will need to include three script files in the <head> section of each topic's HTML. These files are topicInfo.js, CookieClass.js, and displayContent.js. The src attribute of each <script> tag must resolve to a file in the "core" folder of the WebLogic Workshop help installation. By default, this folder is located at <workshop_home>/help/doc/<locale>/core. In other words, the src attribute's value must be a path that is relative from the installed location of the current help topic to the core folder.
As described in Organizing Your Help System, your help topics are installed in <workshop_home>/help/doc/<locale>/partners/<vendor_name>. Consider a vendor named "MyCompany" whose help has a topic at guide/introduction.html. Once installed, the English version of that topic would be located at:
<workshop_home>/help/doc/en/partners/MyCompany/guide/introduction.html
<script> tags in that topic's <head> section, with URLs to the required JavaScript files, would look like this:
<script language="JavaScript" src="../../../../core/topicInfo.js"></script> <script language="JavaScript" src="../../../../core/CookieClass.js"></script> <script language="JavaScript" src="../../../../core/displayContent.js"></script>
Assuming you have created a toc.xml file as described in Creating a toc.xml File, you can support the help system's ability to automatically sync the table of contents to your topic when the topic is displayed. In other words, when the topic is displayed, the table of contents expands to that topic's place in the hierarchy so that users can see the topic's location in context.
To support this feature, each topic to which the table of contents should automatically sync must:
Note that the first two requirements are interdependent. If the function is not called in the topic's HTML the table of contents will not sync, whether or not the toc.xml includes the topic; if the topic was requested via context-sensitive help (by pressing F1), then the table of contents will not display at all. If the function is called, but the topic is not represented in the toc.xml, then a WebLogic Workshop default topic will be displayed in place of the requested topic.
Note: As you might have guessed, this represents a design decision. Do you want your help to participate in the WebLogic Workshop frameset and table of contents or not? If you do, you must provide a toc.xml that represents, and call displayInFrames() from, every topic. If you don't want to participate, you don't need to provide a toc.xml and you should not call displayInFrames().
For more information on creating a toc.xml file, see Creating a toc.xml File. To call the function, place the following code just after each topic's <body> tag, before other body content:
<script language="JavaScript"> displayInFrames(); </script>
Finally, the third requirement mentioned above ensures that the topic will be able to find the frameset in order to display itself within the frameset. Due to the way the script works, the <a> tag must be the first anchor with an href attribute in the topic. Putting the following line of code either in the <head> section (along with the <script> tags) or immediately following the <body> tag should do the trick.
In keeping with the "introduction.html" example above, the line of HTML would look something like this:
<a href="../../../../core/index.html" id="index"></a>
WebLogic Workshop documentation supports a feedback mechanism that sends email to the documentation team. You can specify a different email address through the writeCustomTopicInfo JavaScript function. The same function also provides a way for you to specify the current topic's location, perhaps that topic's location at your company's web site; this URL will be printed at the bottom of the topic.
The function is described as follows:
writeCustomTopicInfo(customHelpURL, customFeedbackAddress)
The customHelpURL argument specifies a base URL at which the current topic may be found. The Workshop help system will append the current topic's relative URL to customHelpURL. For example, if you specify "http://mycompany.com/docs/" as customHelpURL, and the topic is located under the partners help directory at MyCompany/guide/introduction.html, the resulting URL will be "http://mycompany.com/docs/en/partners/MyCompany/guide/introduction.html". If you specify null for this argument, the help system will insert a path to the topic on the user's computer.
The customFeedbackAddress argument specifies the email address to which feedback should be sent. The Workshop help system will provide a form in which users can enter feedback details. The resulting information will be sent to the email address you specify in the customFeedbackAddress argument.
To support the feedback and URL features, place the following code just before each topic's </body> tag:
<script language="JavaScript"> writeCustomTopicInfo("http://mycompany.com/docs/", "feedback@mycompany.com"); </script>
When a user searches the help topics, the search algorithm returns a list of the topic titles that match the search parameters. Specifically, the list will contain the topic title as given in the <title> tag in the <head> section of each help topic's HTML file, for example:
<title>WebLogic Workshop Help Authoring Guide</title>
In order for search to add your topic to the search list, you must include a <title> tag. If a help topic does not contain this tag, the search algorithm might return this help topic as matching, but it cannot add its topic title to the list of matching topics and users will not be able to select the topic.
When selecting a title for your topics, you should be careful to provide a title precise enough to identify the subject among many potential search results. Help for controls should include some form of the vendor name in every topic title. However, be aware that if you use the same long prefix in every topic title, the search panel will appear to return multiple identical results unless the search results panel is made wider. Be concise but informative.
For more information on the search algorithm, see the WebLogic Workshop help topic Search Tips.
To add your help topics to the table of contents of WebLogic Workshop help, you need to provide a toc.xml file in help/doc/<locale>/partners/<vendor_name>. When users choose to add your documentation to WebLogic Workshop when they add your control JAR file to the application, the help topics are added underneath the table of contents book Extensions.
The toc.xml file must comply with the XML schema defined in the toc.xsd file. A copy of toc.xsd can be found in the Help Test Kit at the WebLogic Workshop Extensibility Portal. The toc.xml file that you create should follow this template:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- 'My Company' TOC -->
<toc-root component="other" xmlns="http://www.bea.com/help/toc.xsd">
<toc-reference anchor="extensions">
<toc-node label="My Company" url="somePageA.html">
<toc-node label="My Control 1" url="somePageB.html">
<toc-node label="My Control 1, Topic 1" url="somePageC.html"/>
<toc-node label="My Control 1, Topic 2" url="somePageD.html"/> ...
</toc-node>
<toc-node label="My Control 2" url="somePage.html"> ...
</toc-node> ...
</toc-node>
</toc-reference>
</toc-root>
In the example, the book My Company has its own help topic somePageA.thml and contains a nested book My Control 1. This nested book in turn has its own help topic somePageB.html, a nested topic My Control 1, Topic 1 with a help topic somePageC.html, etcetera.
Your toc.xml file must contain a <toc-root> element exactly as shown in the example, followed by a <toc-reference> element, again exactly as shown in the example. The <toc-reference> element should hold exactly one <toc-node> element, with a label name that clearly reflects the name of your company and product. This element will create the top level book for your help topics, and will be placed beneath the table of contents book Extensions. Within this element you should nest all your help topics.
You should choose the label of the top-level <toc-node> directory carefully. A user may have a large number of extensions installed on his or her system. The name you choose must clearly and uniquely identify your company and product name.
Every <toc-node> element must have label and url attributes. The label contains the title of the topic in the table of contents, while the url contains a relative link to the help page. When the <toc-node> element represents a single help topic, the tag is closed at the end, as is shown in the following example:
<toc-node label="My Control 1, Topic 1" url="somePageC.html"/>
Note that the table of contents will automatically display as a book any <toc-node> entry that contains other entries. When the toc-node element represents a book, it will have a begin tag and an end tag, and its nested topics (or books) are contained between these two tags, as is shown in the following example:
<toc-node label="My Control 1" url="somePageB.html">
<toc-node label="My Control 1, Topic 1" url="somePageC.html"/>
<toc-node label="My Control 1, Topic 2" url="somePageD.html"/> </toc-node>
The character encoding of localized help content is specified in the <locale>/core/toc-master.xml file in the WebLogic Workshop help installation. When you provide localized help page, you must use the following character encodings for non-English help content:
Each localized page should specify its character set encoding. If you omit this specification, the topic titles may appear garbled in the Table of Contents. Following is an example of the character set specification for a Japanese content page:
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=Shift_JIS">
A META tag such as this should appear in the <HEAD> section of each localized document. Note that in addition to supplying the META tag correctly, you must also actually store the content files in the specified encoding.
When the WebLogic Workshop Help search index is built, only help content in the current locale is included in the index. This means that if you rebuild the search index in the Japanese locale, for example, English help from the 'en' directory is not included in the index. To include non-localized help content in the index for a different locale, copy the English content from the 'en' directory to the <locale> directory for the desired locale(s).