HDAPI.AddCustomToolbarButton Method

HDAPI AddCustomToolbarButton Method

This function adds a button to the interview toolbar. When a user clicks the button, a JavaScript function is called that performs any action you may wish to make available to users of your host application, such as displaying your host application's help file.

JavaScript API: Direct
Assembly: api.js Version: 1.0.0.0 (1.0.0.0)

Syntax

JavaScript

Copy

function AddCustomToolbarButton(funcClick, imageNormal, imageHot, statusText, tooltip, funcActive, imageActive, imageActiveHot, tooltipActive, buttonIndex, textOnlyCaption);

Parameters

funcClick: Type: function
A Javascript function that should be called whenever the button is clicked. This function should accept one parameter, which is the ID for the toolbar button being clicked.
imageNormal: Type: System String
This is the URL for the button's "normal" image. To create a text-only button, set this parameter to null.
imageHot: Type: System String
This is the URL for the image displayed when the mouse is hovered over the button.
statusText: Type: System String
This is the text that is displayed in the browser status bar when the mouse is hovered over the button.
tooltip: Type: System String
This is the text that is displayed as a hint (tool tip/alternate text) for the button.
funcActive: Type: function
A Javascript function that should be called to determine if the button should be in an "active" state or not. It should accept one parameter (the ID for the toolbar button being checked) and should return a boolean value.
imageActive: Type: System String
This is the image for the button when it is in an "active" state.
imageActiveHot: Type: System String
This is the image for the button when it is both in an "active" and the mouse is hovered over it.
tooltipActive: Type: System String
This is the text that is displayed as a hint (tool tip/alternate text) when the button is in an "active" state.
buttonIndex: Type: System Int32
This is the location of the button within its group of toolbar buttons. (Default: 0, which means the button will be placed in the first (left-most) position in the group)
textOnlyCaption: Type: System String
The caption to use for a button that should be displayed as text-only (no image).

Return Value

Type: string
This function returns a button ID, which you can later use to invoke the button programmatically or to set the button's visibility.

Remarks

To use this function, place a call to it inside of your HDInterviewOptions.OnInit method. (This is equivalent to the PreHDRender callback function specified by past versions of HotDocs Server, which is deprecated but still works.)

The first two parameters are required; the rest are optional.

Buttons can be simple command buttons or toggle buttons. A toggle button is one that has two states (normal and "active"), and represents a mode that can be toggled on or off by the user. For example, the built-in button for showing & hiding the resource pane in the interview is a toggle button -- the resource pane can be shown (the button is in the "active" state) or hidden (the button is in the "normal" state). For simple command buttons that do not have an "on" or "off" state, all the parameters with "Active" in the name can simply be omitted or set to null.

Custom buttons are always added to the left of the existing toolbar buttons in the order in which they are added.

To avoid ambiguity, you should use a full URL for all image file parameters passed to this function.

Silverlight interviews support only .PNG and .JPG images. If you intend to use the Silverlight interview format, make sure to use a supported image type.

Examples

JavaScript

Copy

var MyButtonIsActive = true;
function ActiveButton()
{
    return MyButtonIsActive;
}
function HelloWorld()
{
    MyButtonIsActive = !MyButtonIsActive;
}
var HDInterviewOptions = {
    OnInit: function()
    {
        HDAPI.AddCustomToolbarButton(
            HelloWorld,
            "http://servername/images/btn.png",
            "http://servername/images/btnhot.png",
            "Status Message",
            "Tooltip",
            ActiveButton,
            "http://servername/images/btnActive.png",
            "http://servername/images/btnActiveHot.png",
            "Active Tooltip");
    }
};

Reference

HDAPI Object

Direct JavaScript API