# Help Authoring Guide

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:

- Help Integration Support in the IDE. Describes the difference in support for help integration between Java controls and other extensions.
- Organizing Your Help System. Describes how the various help files you are creating should be organized.
- Creating Help Pages. Discusses how to create help content that will look and feel like the help provided by WebLogic Workshop.
- Making Search Results Useful. Discusses how to make your help content searchable.
- Creating a TOC. Describes how to create a table of contents for the help topics that can be merged into WebLogic Workshop help.
- Localizing Help for Non-English Locales. Describes how to properly format localized help content for use in the Table of Contents and Search.

## Help Integration Support in the IDE

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:

- Visibility of topics to full-text search.
- Visibility of topics in the table of contents.
- Visibility of class, annotation, and JSP tag reference topics when context-sensitive help is requested (such as when the user presses F1 in Source View or Design View).

### Help Integration for Java Controls

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:

- Explodes the top-level help folder and copies its contents into <workshop_home>/help.
- Merges the provided table of contents file (toc.xml) with the installed table of contents. The result is that the control help is available beneath the Extensions -> <vendor_name> node in the table of contents.
- Rebuilds the search index so that the new topics are available for full-text search.

### Help Integration for Other Kinds of Extensions

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:

- Copy your top-level help folder and its contents to <workshop_home>/help. Note that your help hierarchy should not include a copy of workshop.css in any <locale> folders. (See Organizing Your Help System for more information.)
- Rebuild the search index and table of contents by invoking the workshop.core.IndexIdeHelp class. You can do this with the following command:

      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.

## Organizing Your Help System

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.

- Help root — The root directory for your help files should be help/doc/<locale>/partners/<vendor_name>.
- Table of Contents file — The toc.xml file, which is used to add your help pages to the table of contents, must be located at the root of your help structure, at help/doc/<locale>/partners/<vendor_name>/toc.xml
- CSS file — The workshop.css file, the CSS style sheet for help topics, should be located in the <locale> folder. Using the style rules defined in this file helps to ensure that your content has a look and feel consistent with the rest of the Workshop documentation.

  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.

- Context-sensitive topics — Be sure to place all help files that are used for context-sensitive help in the folder structure described below. The context-sensitive help mechanism (used when the user presses F1 while an API or tag is selected) is designed to identify the item selected, then look for a corresponding help topic according to the following rules.
  - <vendor_name>/java-class for Javadoc or similar references for Java APIs. Subfolders should reflect the API package structure, and HTML files should be named after the classes. For instance, the context-sensitive help for the ControlException class, which is part of the package com.bea.control, is located in java-class/com/bea/control/ControlException.html.

    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.

  - <vendor_name>/javadoc-tag for annotation references. Subfolders should reflect the prefix of the custom annotation, and HTML files should be named after the tags. For instance, the context-sensitive help for the @jc:sql annotation is located in javadoc-tag/jc/sql.html. All segments of the path are case-sensitive.
  - <vendor_name>/taglib for custom JSP tag library references. Subfolders should be structured based on the tag library URI. (The tag library URI is the value of the <uri> element in the tag library's TLD file.) For example, the context-sensitive help for the callControl tag, whose URI is http://www.bea.com/workshop/netui-tags-databinding-1.0, is located in <vendor_name>/taglib/www.bea.com/workshop/netui-tags-databinding-1.0/callControl.html. All segments of the path are case-sensitive.

- Other topics — In the <vendor_name> folder, in any number and arrangement of subfolders, you can put any number of HTML help files that are not used for context-sensitive help. For instance, the WebLogic Workshop convention is to locate all help files that are not used for context-sensitive help in a guide folder. In your structure, this would be <vendor_name>/guide.

## Creating Help Pages

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:

- Title. Use this style for the title of a help topic.
- h1, h2, and h3. Use these styles for first, second, and third-level headings within the body of a topic.
- relatedTopics. Use this style for the section Related Topics.
- procTitle. Within the body of How Do I..? topics, use this style for headings that are followed by
  bulleted procedures. These headings generally start with To do 'X'.
- pre. If you want to include a section with sample code, use the preformatted paragraph, and use four spaces for indentation.
- langinline. For code fragments, file names, class names, etc., within a (non-code) regular section, you should apply this style.
- notepara. To add a note section, apply this style. Start a note with "Note:" (where "Note" is in bold and the rest of the note text is not).

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.

### Required Functions

Through JavaScript functions provided with WebLogic Workshop, your help topics can support three features that are available with the Workshop help system:

- Automatically syncing the table of contents to the topic displayed.
- Writing the topic's URL into the topic so that users can refer to it specifically.
- Specifying an email address to which topic feedback should be sent.

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.

### Including the Required Script Files

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>

### Supporting Automatic Syncing

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:

- Be represented by a corresponding element in the toc.xml file.
- Include a call to the displayInFrames() function provided by the help system.
- Include an <a> tag whose href attribute value resolves to the index.html file in the <workshop_home>/help/doc/<locale>/core directory, and whose id attribute value is "index".

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>

### Supporting Feedback Links and Current Topic URLs

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>

## Making Search Results Useful

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.

## Creating a toc.xml File

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>

## Localizing Help for Non-English Locales

### Character Encoding for Localized Help Pages

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:

- Japanese -- Shift-JIS
- Korean -- EUC-KR
- Simplified Chinese -- GB2312

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.

Localized Search Index

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).

Related Topics

workshop.css