Package com.orchestranetworks.ui

# Interface JavaScriptCatalog

public interface JavaScriptCatalog
This interface is only used to document JavaScript functions and should not be referenced by Java code.

You can copy-paste the signature of the members of this interface in your own JavaScript code.

Since:
  5.7.1

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `JavaScriptCatalog.EBX_ValidationMessage`
  A JavaScript object that holds a list of messages with different severities.
  `static interface`
  `JavaScriptCatalog.EbxHtmlButtonElement`
  Represents an HTML button generated by EBX® using a Java `UIButtonSpec` object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `ebx_alert(String aMessage, String otherLines)`
  Pops a modal dialog box that displays a message and an OK button.
  `void`
  `ebx_buttonUtils_setButtonDisabled(JavaScriptCatalog.EbxHtmlButtonElement aButton, boolean setDisabled)`
  Disables the given button.
  `void`
  `ebx_buttonUtils_setButtonWaitingMode(JavaScriptCatalog.EbxHtmlButtonElement aButton, boolean setWaitingMode)`
  Turns the given button into the waiting mode.
  `void`
  `ebx_confirm(Object argsObj)`
  Displays a modal dialog box that displays a question, a positive and a negative answer.
  `void`
  `ebx_dialogBox_hide()`
  Hides the current modal dialog box displayed with `ebx_dialogBox_show(Object)`.
  `void`
  `ebx_dialogBox_show(Object argsObj)`
  Displays a modal dialog box that displays optionally a header, a body or a footer.
  `JavaScriptCatalog.EBX_ValidationMessage`
  `ebx_form_getNodeMessage(String aPrefixedPath)`
  Returns the list of messages currently displayed for the specified form node.
  `Object`
  `ebx_form_getValue(String aPrefixedPath)`
  Returns the current value of the specified node, as set in the form.
  `boolean`
  `ebx_form_isNodeDefined(String aPrefixedPath)`
  Returns `true` if the node is defined in the form, `false` otherwise.
  `void`
  `ebx_form_setMandatoryIndicator(String aPrefixedPath, boolean isDisplayed)`
  Adds or removes a mandatory indicator (*) next to the label of the specified node to simulate that it is mandatory.
  `void`
  `ebx_form_setNodeMessage(String aPrefixedPath, JavaScriptCatalog.EBX_ValidationMessage aMessageContainer)`
  Displays a list of messages on a node.
  `void`
  `ebx_form_setValue(String aPrefixedPath, Object aValue)`
  Sets the value of the specified node from a JavaScript variable.
  `Object`
  `ebx_getContainerWindow(Object window)`
  Returns the web component window hosting a user service, UIForm, custom widget or UIBean.
  `Object`
  `ebx_getContentWindow(Object window)`
  Returns the window directly hosting the content displayed in the workspace.
  `String`
  `ebx_getFormLostChangesWarning()`
  Checks if the native form has changes, and returns a warning message if so.
  `void`
  `ebx_getWorkspaceTitle()`
  Gets the title of the current workspace in which the component is running.
  `void`
  `ebx_setWorkspaceTitle(String workspaceTitle)`
  Sets the title of the current workspace in which the component is running.

- ## Method Details

  - ### ebx_buttonUtils_setButtonDisabled

    void ebx_buttonUtils_setButtonDisabled(JavaScriptCatalog.EbxHtmlButtonElement aButton, boolean setDisabled)
    Disables the given button.

    When a button is disabled, it is slightly transparent, and if the user clicks on it or activates it with the keyboard, nothing happens.

    Parameters:
      `aButton` - the button to enable or disable the waiting mode.
      `setDisabled` - a JavaScript boolean, `true` to set the button to disabled, `false` to set the button to enabled.
    See Also:
      - `UIJavaScriptWriter.addJS_setButtonDisabled(String, String)`

  - ### ebx_buttonUtils_setButtonWaitingMode

    void ebx_buttonUtils_setButtonWaitingMode(JavaScriptCatalog.EbxHtmlButtonElement aButton, boolean setWaitingMode)
    Turns the given button into the waiting mode.

    When a button is in waiting mode, its icon is replaced by the small waiting icon animation. If the button has no icon, the waiting mode cannot be visible.

    Parameters:
      `aButton` - the button to enable or disable the waiting mode.
      `setWaitingMode` - a JavaScript boolean, `true` to enable the waiting mode, `false` to disable the waiting mode.

  - ### ebx_getFormLostChangesWarning

    String ebx_getFormLostChangesWarning()
    Checks if the native form has changes, and returns a warning message if so. This warning message is used when the user goes to another page or closes the browser without submitting the form.

    If no changes have been performed on the native form, this function returns `undefined`.

    "Native form" stands for the main standard form of the product, which is omnipotent, and concerns the form of all pages contained in the workspace area, whether it is a record form, `UIForm`, dataset form, UIService `UIFormSpec`, dataspace form, DMA form, workflow model form, permission form, administration form etc. All except for full table view and hierarchy view (which have no main form) and specific UIServices forms that are not using `UIFormSpec`.

    Code examples:

    1. test if the form has changes in the current page

         var warningMessage = ebx_getFormLostChangesWarning();
        if (warningMessage === undefined) {
            // the native form has no change
        } else {
            // the native form has changes, it is possible to use the warningMessage to display it to have the
            alert(warningMessage);
        }

    2. check if the form has changes in an iFrame before changing the src or destroy the iframe

         var iframeEl = document.getElementById("my_sweet_iFrame_id");
        var warningMessage = undefined;
        try {
            warningMessage = iframeEl.contentWindow.ebx_getFormLostChangesWarning();
        } catch (e) {}
        if (warningMessage !== undefined) {
            // content window as been reached and its native form has been changed, ask the question to user
            if (confirm(warningMessage + "\n" + "Are you sure you want to close this iFrame?") === false) {
                return; // abandon
            }
        }
         // destroy iFrame
        iframeEl.parentNode.removeChild(iframeEl);
         // or change its src
        iframeEl.src = "http://the_next_page.i_want.to/display";

    Note: the mechanism to check if the form has changes is the standard mechanism of the product, that includes:

    - `UIFormSpec.setDetectionOfLostModificationDisabled(boolean)`
    - `UICSSClasses.IGNORE_FORM_CHECK`
    Returns:
      String the warning message of changes have been made on the native form, or `undefined` if no change has been made on the native form

  - ### ebx_form_isNodeDefined

    boolean ebx_form_isNodeDefined(String aPrefixedPath)
    Returns `true` if the node is defined in the form, `false` otherwise.
    Parameters:
      `aPrefixedPath` - path of the node, it should be obtained using the method `UIFormWriter.getPrefixedPath(Path)`; for backward compatibility, paths that are not prefixed are supported only for custom forms extending `UIForm`.
    Since:
      5.8.0

  - ### ebx_form_getValue

    Object ebx_form_getValue(String aPrefixedPath)
    Returns the current value of the specified node, as set in the form.
    Parameters:
      `aPrefixedPath` - path of the node, it should be obtained using the method `UIFormWriter.getPrefixedPath(Path)`; for backward compatibility, paths that are not prefixed are supported only for custom forms extending `UIForm`.
    See Also:
      - `UIFormWriter.addJS_getNodeValue(Path)`

  - ### ebx_form_setValue

    void ebx_form_setValue(String aPrefixedPath, Object aValue)
    Sets the value of the specified node from a JavaScript variable.
    Parameters:
      `aPrefixedPath` - path of the node, it should be obtained using the method `UIFormWriter.getPrefixedPath(Path)`; for backward compatibility, paths that are not prefixed are supported only for custom forms extending `UIForm`.
      `aValue` - the value to be set.
    See Also:
      - `UIFormWriter.addJS_setNodeValue(String, Path)`

  - ### ebx_form_setMandatoryIndicator

    void ebx_form_setMandatoryIndicator(String aPrefixedPath, boolean isDisplayed)
    Adds or removes a mandatory indicator (*) next to the label of the specified node to simulate that it is mandatory. It does not add or remove neither constraints nor validation rules applied to the node.
    Parameters:
      `aPrefixedPath` - path of the node, it should be obtained using the method `UIFormWriter.getPrefixedPath(Path)`; for backward compatibility, paths that are not prefixed are supported only for custom forms extending `UIForm`.
      `isDisplayed` - a JavaScript boolean, `true` to add a mandatory indicator, `false` to remove a mandatory indicator.
    Since:
      6.0.0
    See Also:
      - `UIFormWriter.addJS_setNodeMandatoryIndicator(boolean, Path)`

  - ### ebx_form_setNodeMessage

    void ebx_form_setNodeMessage(String aPrefixedPath, JavaScriptCatalog.EBX_ValidationMessage aMessageContainer)
    Displays a list of messages on a node.

    Please note that it will erase all previously set messages.

    `aMessageContainer` is a JavaScript object, that can be created and filled as follows:

         var msgs = new EBX_ValidationMessage();
         msgs.errors = ["An error message"];
         msgs.warnings = ['A warning message', 'A second warning message'];

    Parameters:
      `aPrefixedPath` - path of the node, it should be obtained using the method `UIFormWriter.getPrefixedPath(Path)`; for backward compatibility, paths that are not prefixed are supported only for custom forms extending `UIForm`.
      `aMessageContainer` - the JavaScript object containing the list of messages. Must not be `null`.
    Since:
      5.8.0

  - ### ebx_form_getNodeMessage

    JavaScriptCatalog.EBX_ValidationMessage ebx_form_getNodeMessage(String aPrefixedPath)
    Returns the list of messages currently displayed for the specified form node.

    If path is invalid or node is missing, will return `null`.

    If no message is displayed, will return an empty `EBX_ValidationMessage`.

    Parameters:
      `aPrefixedPath` - path of the node, it should be obtained using the method `UIFormWriter.getPrefixedPath(Path)`; for backward compatibility, paths that are not prefixed are supported only for custom forms extending `UIForm`.
    Since:
      5.8.0

  - ### ebx_alert

    void ebx_alert(String aMessage, String otherLines)
    Pops a modal dialog box that displays a message and an OK button.

    By a click on the back or a press on the escape key, the user closes the dialog.

    If the first argument message has many lines, separated by the JavaScript standard line separator "\n", only the first line will be used for the message, placed in the header part of the dialog box. The remaining lines will be separated by `<br/>`, and added to the body of the dialog box, before the optional otherLines.

    Code examples:

    Displays the message "The record has been saved"

         ebx_alert("The record has been saved");

    Displays the message "The record has been saved" and adds a precision (2 ways to do the same thing)

         ebx_alert("The record has been saved\nValues have been refreshed.");
         ebx_alert("The record has been saved", "Values have been refreshed.");

    Parameters:
      `aMessage` - String with HTML-single-line and not too long
      `otherLines` - [optional] String with HTML-free-style to put in the body of the dialog box

  - ### ebx_confirm

    void ebx_confirm(Object argsObj)
    Displays a modal dialog box that displays a question, a positive and a negative answer.

    By clicking back or pressing the Escape key, the user produces the negative answer.

    If the field question has many lines, separated by the JavaScript standard line separator "\n", only the first line will be used for the question, placed in the header part of the dialog box. The remaining lines will be separated by `<br/>`, and added to the body of the dialog box, before the optional message.

    Code examples:

    Ask a question and call a JavaScript function called "sendAJAXUpdate" if the answer is "yes" (many ways to do the same thing)

         ebx_confirm({
            question: "Do you want to refresh the value?",
            jsCommandYes: sendAJAXUpdate
        });

         ebx_confirm({
            question: "Do you want to refresh the value?",
            jsCommandYes: "sendAJAXUpdate('string_12');"
        });

         ebx_confirm({
            question: "Do you want to refresh the value?",
            jsCommandYes: function(){sendAJAXUpdate(fieldId);}
        });

    Ask a question, call a JavaScript function called "sendAJAXUpdate" if the answer is "yes", and customize button labels

         ebx_confirm({
            question: "Do you want to refresh the value?",
            jsCommandYes: sendAJAXUpdate,
            labelYes: "Yes, please :)",
            labelNo: "No, thanks :|"
        });

    Ask a question, call a JavaScript function called "sendAJAXUpdate" if the answer is "yes", customize button labels and call a JavaScript function if answer is "no"

         ebx_confirm({
            question: "Do you want to refresh the value?",
            jsCommandYes: sendAJAXUpdate,
            labelYes: "Yes, please :)",
            labelNo: "No, thanks :|",
            jsCommandNo: resetFieldDecorations
        });

    Parameters:
      `argsObj` - JSON Object that can contain these keys and values:
      question
        {mandatory} String with HTML-single-line and not too long
      message
        [optional] String with HTML-free-style to put in the body of the dialog box
      jsCommandYes
        {mandatory} a JavaScript function reference or JavaScript instructions in a String, to call if answer is positive
      labelYes
        [optional] String to overwrite the default positive label
      jsCommandNo
        [optional] a JavaScript function reference or JavaScript instructions in a String, to call if answer is negative
      labelNo
        [optional] String to overwrite the default negative label

  - ### ebx_dialogBox_show

    void ebx_dialogBox_show(Object argsObj)
    Displays a modal dialog box that displays optionally a header, a body or a footer.

    By clicking on back or pressing the Escape key, a JavaScript command can be called.

    The dialog box is not self-closing. To close it, `ebx_dialogBox_hide()` must be called.

    When the dialog box appears, its height and width is automatic (it fits the content of the 3 zones), and is centered on the screen. If the content of the dialog box is modified after the display, the height and width are stretched, but the dialog box is not automatically centered (resizing the window refreshes the centered position, but it's a workaround).

    Code examples:

    Ask for a file name before a data export

         ebx_dialogBox_show({
            header: "<h2>Export</h2>",
            body: "<div class=\"ebx_ContainerWithTextPadding\"><label for=\"inputFileNameId\">File name:</label> <input type=\"text\" id=\"inputFileNameId\" /></div>",
            footer: "<div class=\"ebx_DialogBoxFooterToolbar\"><button type=\"button\" onclick=\"readFileNameAndCloseDialog();\">OK</button></div>",
            focusId: "inputFileNameId",
            jsCommandClose: ebx_dialogBox_hide
        });

    Use the content of a prepared small form (that could be generated with standard form API: `formRows` etc.)

         ebx_dialogBox_show({
            header: "<h2>Export</h2>",
            body: document.getElementById("myPreparedSmallForm").innerHTML,
            footer: document.getElementById("myPreparedFooterToolbar").innerHTML,
            focusId: "defaultButtonIdInMyFooter",
            jsCommandClose: ebx_dialogBox_hide
        });

    Parameters:
      `argsObj` - JSON Object that can contain these keys and values:
      header
        [optional] String with HTML-free-style to put in the header of the dialog box.
        Recommended HTML wrapper: `<h2> header content here </h2>`
      body
        [optional] String with HTML-free-style to put in the body of the dialog box
        Recommended HTML wrapper: `<div class="`ebx_ContainerWithTextPadding`"> body content here </div>`
      footer
        [optional] String with HTML-free-style to put in the footer of the dialog box
        Recommended HTML wrapper: `<div class="`ebx_DialogBoxFooterToolbar`"> footer content (usually buttons) here </div>`
      focusId
        [optional] String element id to focus on display (usually the default button or an input field)
      jsCommandClose
        [optional] a JavaScript function reference or JavaScript instructions in a String, to call if the user clicks on back or presses the escape key
    See Also:
      - `ebx_dialogBox_hide()`

  - ### ebx_dialogBox_hide

    void ebx_dialogBox_hide()
    Hides the current modal dialog box displayed with `ebx_dialogBox_show(Object)`.

    The dialog box is used by `ebx_alert(String, String)` and `ebx_confirm(Object)`. So, if an alert dialog box or a confirmation dialog box is displayed, the dialog box will be hidden by calling this method.

    See Also:
      - `ebx_dialogBox_show(Object)`

  - ### ebx_setWorkspaceTitle

    void ebx_setWorkspaceTitle(String workspaceTitle)
    Sets the title of the current workspace in which the component is running. Allows to change the workspace title dynamically according to the user actions. Please note that the workspace in which the component is running can be NewUI or legacy. This function works in both cases.
    Parameters:
      `workspaceTitle` - the workspace title to be set.
    Since:
      5.9.0 fix B

  - ### ebx_getWorkspaceTitle

    void ebx_getWorkspaceTitle()
    Gets the title of the current workspace in which the component is running. Please note that the workspace in which the component is running can be NewUI or legacy. This function works in both cases.
    Since:
      5.9.0 fix B

  - ### ebx_getContainerWindow

    Object ebx_getContainerWindow(Object window)

    Returns the web component window hosting a user service, UIForm, custom widget or UIBean. This method should be used instead of `window` because EBX® may insert intermediary frames.

    If the host is on a different domain, it will return the top EBX® frame on the same domain. In that case some security restrictions apply when accessing the result window parent.

    Code example

    A user service wants to redirect the current user to another page. JavaScript code from a user service may be:

         var ebxWindow = ebx_getContainerWindow();
         var ebxWindow.location.href = "http://....";

    Parameters:
      `window` - the current window for the user service, UIForm, custom widget or UIBean. If not defined, the `this` window will be used.
    Returns:
      the window. May be the top window. It is never `undefined` or `null`.
    Since:
      5.9.0

  - ### ebx_getContentWindow

    Object ebx_getContentWindow(Object window)

    Returns the window directly hosting the content displayed in the workspace.

    Code example

    A page X displays EBX®, as a Web Component, in an iframe whose id is "MyEBX" . Page X is currently displaying a user service that displays its own iframe whose id is "MyIFrame".

    Page X needs to access the iframe "MyIframe". JavaScript code from page X that retrieves the iframe "MyIFrame" may be:

         var ebxIFrame = document.getElementById("MyEBX"); // The iframe hosting EBX® as a Web Component.
         var ebxContentWindow = ebxIFrame.contentWindow.ebx_getContentWindow(); // The window directly hosting the user
                                                                                                                                                   // service.
         var myIFrame = ebxContentWindow.document.getElementById("MyIFrame"); // The iframe created by the user service.

    Parameters:
      `window` - the EBX® Web Component window. If not defined, the `this` window will be used.
    Returns:
      the content window. Is `null` if no content is displayed or if `window` is not an EBX® Web Component.
    Since:
      5.9.0