Customizing the Help Link in the Menu Bar

Overview

The Web Center menu bar contains a help button that displays a help file, for example a PDF, in a separate browser window.Since loading the PDF directly into the help window shows some minor inconveniences, Web Center first loads an HTML wrapper into the help window which then in turn loads the help file.

The wrapper allows for setting a localized window title and a shortcut icon.Also, without the wrapper it’s not possible for the main Web Center page to bring the help window to the front if the user clicks the help button and the help window is already open but hidden behind other windows (in Internet Explorer).

Customizing the Help Button in the Menu Definition

In file WEB-INF/config/identity/menu-defs.xml, you can define and customize the help button.

Defining the Help Menu

The menu is defined as usual.The only specific part is the value of attribute “titleItem” which specifies

  • The help file location.This can be

    • The path (within Web Center) of the HTML wrapper.

    • The path (within Web Center) of the help file (no wrapper).

    • The URL of an external help file.

    The location may contain the expression “${language}” which is replaced with the user’s Web Center language at runtime.

  • targetName - The name of the help window. If you define the same window name for more than one Web Center application, the applications’ help files will all be loaded into the same window. If you define a different name per application, each application loads its help file in a separate window.

  • targetType - The identifier of the configuration property for the window properties and shortcut key (see section “Customizing the Help Window” below). The window properties are evaluated only when the window is opened, not when loading a help file into an already open help window. Therefore, applications sharing the same help window should also have the same window properties.

The default definition for the help button is:

<!-- Help menu -->
<definition name=".menuHelp" extends=".menu">
    <put name="msgPrefix" value="help"/>
    <put name="titleItem"
         value="help:/resources/help/${language}/WebCenterHelp.html::
                targetName=webCenterHelp,targetType=help"/>
</definition>

Adding the Help Menu to a Menu Bar

The help button is by default placed before the login button in the main menu bar:

<definition name=".defaultMenubar">
    <put name="items" value=".menuHome;sep;…;
                             .menuTools;sep;
                             .menuHelp;.menuLogout;nl;
                             …/>
</definition>

You can move it to another position within the main menu bar, or remove it from the main menu bar and add it to another one.If you don’t need the help button at all, just remove it here.

Providing the Help Files

Copy your help files to folder resources or one of its sub folders.The empty default help files are resources/help/en/WebCenterHelp.pdf and resources/help/de/WebCenterHelp.pdf.

Customizing the Help Window

General Properties

In file resources/build/config/config.js, you can configure some properties of the help window and the shortcut key for help.The properties are transparently passed to the Javascript function window.open, so confer to any documentation of that function for a complete list of supported properties and valid property values.

By default, the key F1 opens the Web Center help window.The window is 800 pixels high, 1000 pixels wide, and its top left corner is 50 pixels left and 100 pixels below the top left corner of the screen.The window is resizable but shows no scroll bars.

target: {
    help: {
        key:   "F1",
        props:
    "height=800,width=1000,left=50,top=100,scrollbars=no,resizable=yes"
    }
}
F1 usually opens the browser’s help page. When assigned to the Web Center help F1 does no longer trigger the browser help.

Per-Language Properties

The provided HTML wrappers allow for setting the window title and the shortcut icon. They also contain the help file name. The wrappers for the standard Web Center applications are located in folders resources/help/de and resources/help/en.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
 <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE9" />
 <title>Web Center Help</title>
 <link rel="shortcut icon" href="../../images/logos/DirXIdentity.ico"/>
</head>
<body style="padding:0;margin:0;overflow:visible">
  <iframe src="WebCenterHelp.pdf"
          frameborder="0" scrolling="0" style="width:100%;height:100%">
  </iframe>
</body>
</html>

Adjust the title, the “href” attribute of the shortcut link and the “src” attribute of the iframe according to your needs.