webuijsf
Tag helpWindow


Use the <webuijsf:helpWindow> tag to display a link to a help window. When a user clicks the link, a popup window opens to display an online JavaHelp 2.0 system. See http://java.sun.com/products/javahelp for more information about JavaHelp 2.0 online help.

HTML Elements and Layout

The helpWindow component renders an XHTML <a> hyperlink element that references the main help window JSP page. The link uses an onclick attribute to execute JavaScript that opens a popup window to display a JavaHelp browser window.

The help window is displayed with a masthead that is similar to the masthead used in application pages. The mastheadImageUrl and mastheadImageDescription attributes can be used to provide content for the masthead. Below the masthead is a banner in which the optional pageTitle attribute value can be displayed to provide a title for the help file. The Close button is displayed in the page title banner.

The help window includes two panes. The left pane is a navigation page with tabs for Contents, Index, and Search. The right frame shows the help content pages. The following is a rough diagram of the help window.

Masthead

Page title banner
Close
JavaHelp Navigation tabs (Contents, Index, Search)
JavaHelp Toolbar icons (back, forward, print)  
Navigation pane
Content Pane

Help content goes here.








Configuring the <webuijsf:helpWindow> tag

The <webuijsf:helpWindow> tag relies on a backing bean and a set of JSP pages that are provided with the Sun Java Web UI Components. You must supply a JavaHelp 2.0 help set to be displayed by the helpWindow component.

You must complete the following configuration steps to use the <webuijsf:helpWindow> tag.

  1. Add a managed bean declaration for the JavaHelpBean backing bean.

  2. The <webuijsf:helpWindow> tag retrieves data from a managed bean called JavaHelpBean. You must add a <managed-bean> declaration for the JavaHelpBean to your web application's faces-config.xml file  so that the helpWindow component can access the bean at run time. Add the XML code shown below to your application's faces-config.xml file:

    <managed-bean>
        <description>The backing bean for the Java Help component</description>
        <managed-bean-name>JavaHelpBean</managed-bean-name>
        <managed-bean-class>com.sun.webui.jsf.bean.HelpBackingBean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
    </managed-bean>

    Note that this managed bean should have request scope.

  3. Deploy the helpWindow component's Java Server Pages.

  4. The <webuijsf:helpWindow> tag requires several JSP pages that are included with the component SDK in webui/jsp/help. The JSP pages are used to create the help popup window. The helpWindow component expects these JSP pages to be deployed to the absolute directory /com_sun_webui_jsf/help in your web application.

    If a prefix mapping (such as /faces) must be prepended to the default component JSP path of /com_sun_webui_jsf/help, specify the prefix with the <webuijsf:helpWindow> tag's jspPathPrefix attribute. Then add a <managed-property> entry to the <managed-bean> declaration for JavaHelpBean in your faces-config.xml file.

    For example, if the actual mapping for the help JSP at run time is /faces/com_sun_webui_jsf/help, add the managed-property as shown below:


    <managed-bean>
        <description>The backing bean for the Java Help component</description>
        <managed-bean-name>JavaHelpBean</managed-bean-name>
        <managed-bean-class>com.sun.webui.jsf.bean.HelpBackingBean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
        <managed-property>
            <property-name>jspPath</property-name>
            <value>/faces</value>
        </managed-property>
    </managed-bean>

    Note: If you deploy the helpWindow component's JSPs to a directory that is not covered by the FacesServlet mapping for your application, you must include an additional FacesServlet mapping to the help JSP directory in your application's web.xml file.

  5. Deploy the JavaHelp-compliant help set.

  6. You must provide a JavaHelp-compliant help set that can be used to populate the display of the <webuijsf:helpWindow> tag's online help system. The help set is expected to be located in the relative directory /html/currentLocale/help where currentLocale represents the abbreviation for a supported run time locale (such as en for English locale users).

    If a prefix mapping is required, you should specify the prefix with the  <managed-property> entry for the helpSetPathproperty to the <managed-bean> declaration for JavaHelpBean in your faces-config.xml file.

    For example, if your help files are located in the absolute directory of /yourApp/helpfiles/html/en/help, add the <managed-property> element in the faces-config.xml file as shown in the following example.

    <managed-bean>
        <description>The backing bean for the JavaHelp component</description>
        <managed-bean-name>JavaHelpBean</managed-bean-name>
        <managed-bean-class>com.sun.webui.jsf.bean.HelpBackingBean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
        <managed-property>
            <property-name>helpSetPath</property-name>
            <value>/helpfiles</value>
        </managed-property>
    </managed-bean>

Facets

None.

Theme Identifiers

The helpWindow component uses the following theme image identifiers for the buttons and icons in the help window.

 HELP_BACK
 HELP_BACK_HEIGHT
 HELP_BACK_WIDTH
 HELP_BACK_DISABLED
 HELP_BACK_DISABLED_HEIGHT
 HELP_BACK_DISABLED_WIDTH
 HELP_FORWARD
 HELP_FORWARD_HEIGHT
 HELP_FORWARD_WIDTH
 HELP_FORWARD_DISABLED
 HELP_FORWARD_DISABLED_HEIGHT
 HELP_FORWARD_DISABLED_WIDTH
 HELP_PRINT
 HELP_PRINT_HEIGHT
 HELP_PRINT_WIDTH
 HELP_PRINT_DISABLED
 HELP_PRINT_DISABLED_HEIGHT
 HELP_PRINT_DISABLED_WIDTH
 HELP_BTNNAV_GRADIENT
 HELP_BTNNAV_GRADIENT_HEIGHT
 

Client Side Javascript Functions

None.

Examples

Example 1: Add a HelpWindow link to the masthead

This example shows how to use the webuijsf:helpWindow tag in the webuijsf:masthead tag's helplink facet. These tags add the Help hyperlink to the top right side of the masthead of the application page.

<webuijsf:masthead id="Masthead" productImageURL="../images/productimage.jpg"
        productImageDescription="Java Web Console">
    <f:facet name="helpLink">
        <webuijsf:helpWindow windowTitle="Help Window" pageTitle="Help"
                jspPathPrefix="/faces"
                mastheadImageUrl="/images/webconsole.png"
                helpFile="sunwebconsole.html"                 
                mastheadImageDescription="Sun Java Web Console Logo"
                toolTip="Help for This Page (Opens a New Window)"/>
    </f:facet>               
</webuijsf:masthead>

Example 2: Add a HelpWindow link as part of inline help

This example shows how to create a hyperlink within the inline help text of an application page to open the help window. This approach is used to provide more detailed help on a topic.

<webuijsf:helpInline id="pageHelp1" type="page"
    text="Page inline help can be enhanced by a link to
       provide more information using webuijsf:helpWindow tag.">
   
    <webuijsf:helpWindow windowTitle="Window Title Param"
            pageTitle="Page Title Param"
            mastheadImageUrl="/images/webconsole.png"
            mastheadImageDescription="Sun Java Web Console Logo"           
            helpFile="accessibility.html"
            toolTip="Help for This Page (Opens a New Window)"
            linkIcon="true" linkText="Click for more about Accessibility." />
</webuijsf:helpInline>


Tag Information
Tag Classcom.sun.webui.jsf.component.HelpWindowTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
onDblClickfalsefalsejava.lang.String Scripting code executed when a mouse double click occurs over this component.
targetfalsefalsejava.lang.StringNo Description
styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

helpSetPathfalsefalsejava.lang.String

The context relative path to the help set to be displayed. This attribute overrides any value set for the helpSetPath property in the application's HelpBackingBean instance.

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

helpFilefalsefalsejava.lang.String

The help file to be displayed in the help window content frame when the help link is clicked. The value can be a relative path or a file name.

linkIconfalsefalsejava.lang.String

Set linkIcon to true to display the default icon in front of the text for the help window link. The icon is useful in inline help links to the help window. By default the value is false.

windowTitlefalsefalsejava.lang.String

The text to display in the browser window frame for the help window. This text is rendered in the HTML title element.

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

linkTextfalsefalsejava.lang.String

The text to display for the hyperlink that opens the help window.

onMouseDownfalsefalsejava.lang.String

Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.

toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

widthfalsefalsejava.lang.String

Image width override. When specified, the width and height attributes tell user agents to override the natural image or object size in favor of these values.

onKeyPressfalsefalsejava.lang.String

Scripting code executed when the user presses and releases a key while the component has focus.

disabledfalsefalsejava.lang.String

Flag indicating that clicking of this component by the user is not currently permitted.

onFocusfalsefalsejava.lang.String

Scripting code executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when a mouse out movement occurs over this component.

renderedfalsefalsejava.lang.String Use the rendered attribute to indicate whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
idfalsetruejava.lang.StringNo Description
onMouseOverfalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer into the boundary of this component.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

onKeyUpfalsefalsejava.lang.String

Scripting code executed when the user releases a key while the component has focus.

onMouseUpfalsefalsejava.lang.String

Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.

alignfalsefalsejava.lang.String

Specifies the position of the image with respect to its context. Valid values are: bottom (the default); middle; top; left; right.

onKeyDownfalsefalsejava.lang.String

Scripting code executed when the user presses down on a key while the component has focus.

onClickfalsefalsejava.lang.String

Scripting code executed when a mouse click occurs over this component. If the component submits the form (by using the action attribute), the script that you use with the onClick attribute should not return from the function. When the action attribute is used, the component handles the return with a script that is appended to the anchor element's onclick property. When you supply an onClick attribute, this return script is appended after your script in the anchor's onclick. It is ok to return from your script to abort the submit process if necessary.

tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

onBlurfalsefalsejava.lang.String

Scripting code executed when this element loses focus.


Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.