Keyword Index

Object: SPHTMLDialog

This class implements a dialog box that allows information to be displayed or the user to be prompted for information using HTML formatted pages. If only a single HTML page is specified, a simple dialog box is displayed. If multiple pages are specified, then a tabbed "property sheet" box is displayed. Methods are provided to allow controls embedded in the pages to be initialized and their final values read back after the dialog is closed.

Instances of this class are created using the SPHTMLDialog top-level function.

  • doDialog - This displays the dialog box and waits until the user clicks OK or Cancel.
  • getRadioValue - Gets the value of a named radio button group on the HTML pages.
  • getValue - Gets the value of a named control on the HTML pages.
  • setTabTitles - Sets the titles for the tabs corresponding to each property page.
  • setValue - Sets an initial value for a named control on the HTML pages.
  • Method: doDialog

    This displays the dialog box and waits until the user clicks OK or Cancel.

    bool doDialog(urls);

    bool doDialog(urls, title);

    bool doDialog(urls, title, sizeX, sizeY);

    bool doDialog(urls, title, sizeX, sizeY, showButtons);

    Parameters
    Name Expected Type Description
    showButtons bool true to show the standard OK & Cancel buttons, false shows only the HTML window and a close box, all other controls must be provided in the HTML
    title String The title for the dialog box
    sizeX int The width in pixels for the displayed box. If not specified, defaults are used.
    sizeY int The height in pixels for the displayed box
    urls String The URL(s) or file name(s) of the HTML page(s) to display. If this is a string, then a simple dialog box is displayed showing that page. If this is an SPArray of strings, then a tabbed property sheet box is displayed with one tab per URL.

    Returns:

    Returns true if the user clicks OK, false for Cancel.

    Method: getRadioValue

    Gets the value of a named radio button group on the HTML pages.

    String getRadioValue(name);

    Parameters
    Name Expected Type Description
    name String The name of the control group. This must exactly match the NAME= parameter specified in the HTML.

    Returns:

    Returns the string value of the radio control that was active (checked) at the time the user clicked OK, or null if there was no control with the given name.

    Remarks:

    It is the caller's responsibility to ensure the controls all have unique names assigned across all the pages displayed in one box. If multple controls have the same name, this function will return the value of the last one encountered during the closing process.

    NOTE: This method must be used for radio controls as "getValue" returns incorrect values for come controls, but a body of scripts exists that relies on the incorrect behaviour

    Method: getValue

    Gets the value of a named control on the HTML pages.

    String getValue(name);

    Parameters
    Name Expected Type Description
    name String The name of the control. This must exactly match the NAME= parameter specified in the HTML.

    Returns:

    Returns the string value of the control at the time the user clicked OK, or null if there was no control with the given name.

    Remarks:

    It is the caller's responsibility to ensure the controls all have unique names assigned across all the pages displayed in one box. If multple controls have the same name, this function will return the value of the last one encountered during the closing process.

    Method: setTabTitles

    Sets the titles for the tabs corresponding to each property page.

    void setTabTitles(tab1, tab2, ...);

    void setTabTitles(titles);

    Parameters
    Name Expected Type Description
    tab1 String The title for the first tab
    titles SPArray An array containing titles for the tabs corresponding to the URLs used to display the box
    tab2 String The title for the second tab

    Remarks:

    If this method is not called, or for any tab whose title is not specified, the doDialog method will search in the HTML source to find a <TITLE> section and use that as the tab title.

    Method: setValue

    Sets an initial value for a named control on the HTML pages.

    void setValue(name, value);

    Parameters
    Name Expected Type Description
    value String The value to assign to the control.
    name String The name of the control. This must exactly match the NAME= parameter specified in the HTML.

    Remarks:

    It is the caller's responsibility to ensure the controls all have unique names assigned across all the pages displayed in one box. If multple controls have the same name, all same-named controls will get the same value.