Package com.orchestranetworks.ui

# Interface UIJavaScriptWriter

All Known Subinterfaces:
  `UIAjaxContext`, `UIComponentWriter`, `UIFormPaneWriter`, `UIFormWriter`, `UIResponseContext`, `UIServiceComponentWriter`, `UITableFilterResponseContext`, `UserServicePaneWriter`, `UserServiceRawPaneWriter`, `UserServiceWriter`, `WidgetWriter`, `WidgetWriterForList`

public interface UIJavaScriptWriter
This interface provides methods to add JavaScript in the current response context.

The JavaScript added with these methods is pure JavaScript. It is not necessary to specify the script tag (`<script>`).

For an HTML document, the JavaScript is stored in a special container at the end of the document, to be executed when required.

The JavaScript is executed once the whole page is loaded, by the proprietary JavaScript code of EBX®. There is no need to set on-load functions (such as `window.onload = myFunctionToCallOnload;`), because the execution context is after the on-load event. It is possible to instantly manage the HTML elements written with `UIBodyWriter.add(String)`.

Using the command `document.write("some HTML");` is not recommended, because the HTML will be written to the end of the document, namely before the closing BODY tag `</body>`, and not within an HTML section added with `UIBodyWriter.add(String)`.

## Other JavaScript functions

A static JavaScript Catalog `JavaScriptCatalog` is available, to use with copy-paste in `addJS(String)` or directly in JavaScript files.

Since:
  5.2.0
See Also:
  - UI Developer Guide
  - Development recomendations
  - `JavaScriptCatalog`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `UIJavaScriptWriter`
  `addJS(String aJavaScriptCode)`
  Adds some text to the JavaScript stream.
  `UIJavaScriptWriter`
  `addJS_addResizeWorkspaceListener(String aFunctionName)`
  Adds a JavaScript function to listen for workspace resizing.
  `UIJavaScriptWriter`
  `addJS_cr()`
  Adds a carriage return to the JavaScript stream.
  `UIJavaScriptWriter`
  `addJS_cr(String aJavaScriptCode)`
  Adds some text, then adds a carriage return to the JavaScript stream.
  `UIJavaScriptWriter`
  `addJS_openPreviewImage(String imageURL)`
  Opens an image preview panel for the given image URL.
  `UIJavaScriptWriter`
  `addJS_openPreviewImageFromVar(String varName)`
  Opens an image preview panel from a JavaScript `var` containing the image URL.
  `UIJavaScriptWriter`
  `addJS_setButtonDisabled(String buttonElement, String isDisabled)`
  Disables or enables a button.
  `UIJavaScriptWriter`
  `addJS_setExpandCollapseBlockExpanded(String expandCollapseBlockId, String isExpanded)`
  Expands or collapses an expand/collapse block.
  `UIJavaScriptWriter`
  `addJS_setStateToToggleButton(String buttonElement, String state)`
  Sets the state of a toggle button.
  `UIJavaScriptWriter`
  `addJS_switchToPerspective(String aPerspectiveName)`
  Changes the page of the highest EBX® frame to the specified perspective.
  `UIJavaScriptWriter`
  `addJS_switchToPerspectiveAction(String aPerspectiveName, String aPerspectiveActionName)`
  Changes the page of the highest EBX® frame to the specified perspective action.

- ## Method Details

  - ### addJS

    UIJavaScriptWriter addJS(String aJavaScriptCode)
    Adds some text to the JavaScript stream.
    Parameters:
      `aJavaScriptCode` - JavaScript code.

  - ### addJS_cr

    UIJavaScriptWriter addJS_cr()
    Adds a carriage return to the JavaScript stream. The carriage return is important to properly split the lines of JavaScript code.

  - ### addJS_cr

    UIJavaScriptWriter addJS_cr(String aJavaScriptCode)
    Adds some text, then adds a carriage return to the JavaScript stream. The carriage return is important to properly split the lines of JavaScript code.
    Parameters:
      `aJavaScriptCode` - JavaScript code.

  - ### addJS_openPreviewImage

    UIJavaScriptWriter addJS_openPreviewImage(String imageURL)
    Opens an image preview panel for the given image URL.
    Parameters:
      `imageURL` - the URL of the image. Supported extensions: BMP, GIF, JPEG, JPG, PNG, SWF.
    Since:
      5.2.4
    See Also:
      - `addJS_openPreviewImageFromVar(String)`

  - ### addJS_openPreviewImageFromVar

    UIJavaScriptWriter addJS_openPreviewImageFromVar(String varName)
    Opens an image preview panel from a JavaScript `var` containing the image URL.
    Parameters:
      `varName` - the name of the `var` containing the URL of the image. Supported extensions: BMP, GIF, JPEG, JPG, PNG, SWF.
    Since:
      5.3.1
    See Also:
      - `addJS_openPreviewImage(String)`

  - ### addJS_setButtonDisabled

    UIJavaScriptWriter addJS_setButtonDisabled(String buttonElement, String isDisabled)
    Disables or enables a button.

    Buttons can be initially disabled with the method `UIButtonSpec.setDisabled(boolean)`.

    Example to reactivate a disabled button `jsWriter.addJS("var myButton = document.getElementById(\"MyButtonId\");");
    jsWriter.addJS_setButtonDisabled("myButton", "false");`
    -- or --
    `jsWriter.addJS_setButtonDisabled("document.getElementById(\"MyButtonId\")", "false");`
    Parameters:
      `buttonElement` - a JavaScript expression evaluating to a button HTML Element.
      `isDisabled` - a JavaScript expression evaluating to a Boolean.
    Since:
      5.2.3

  - ### addJS_setExpandCollapseBlockExpanded

    UIJavaScriptWriter addJS_setExpandCollapseBlockExpanded(String expandCollapseBlockId, String isExpanded)
    Expands or collapses an expand/collapse block.

    The id of the expand/collapse block is given by the method `UIComponentWriter.startExpandCollapseBlock(UserMessage, boolean)`.

    Example to expand an expand/collapse block using its id `String expandCollapseId = componentWriter.startExpandCollapseBlock(aUserMessage, true);
    componentWriter.addJS("var expandCollapseIdVar = \"").addJS(expandCollapseId).addJS("\";");
    componentWriter.addJS_setExpandCollapseBlockExpanded("expandCollapseIdVar", "true");`
    -- or --
    `componentWriter.addJS_setExpandCollapseBlockExpanded("\"" + expandCollapseId + "\"", "true");
    `
    Parameters:
      `expandCollapseBlockId` - a JavaScript expression evaluating to an expand/collapse block id.
      `isExpanded` - a JavaScript expression evaluating to a Boolean.
    Since:
      5.2.3

  - ### addJS_setStateToToggleButton

    UIJavaScriptWriter addJS_setStateToToggleButton(String buttonElement, String state)
    Sets the state of a toggle button.

    The JavaScript commands will not be executed.

    Example to set a toggle button to "OFF" `jsWriter.addJS("var myToggleButton = document.getElementById(\"MyToggleButtonId\");");
    jsWriter.addJS_setStateToToggleButton("myToggleButton", "false");`
    -- or --
    `jsWriter.addJS_setStateToToggleButton("document.getElementById(\"MyToggleButtonId\")", "false");`
    Parameters:
      `buttonElement` - a JavaScript expression evaluating to a button HTML Element.
      `state` - a JavaScript expression evaluating to a Boolean (true for "ON" and false for "OFF").
    Since:
      5.2.3

  - ### addJS_addResizeWorkspaceListener

    UIJavaScriptWriter addJS_addResizeWorkspaceListener(String aFunctionName)
    Adds a JavaScript function to listen for workspace resizing.

    The JavaScript function will be called at the end of the page loading and each time the workspace is resized.

    Two JavaScript `Objects` parameters are given to the JavaScript function.

    The first `Object` parameter contains three fields:

    - `h`: the height of the workspace content region, not including tab titles and not including the bottom bar;
    - `w`: the width of the workspace content region;
    - `vScroll` (since 5.9.0): the width of the vertical scroll if it is present, or 0 if there is no scrollbar.

    The second `Object` parameter has been introduced in 5.9.0, since the workspace displays a translucent form bottom bar in the workspace. The goal is to let the developer choose the zone where the widget will be displayed. It contains four fields:

    - `h`: the height of the workspace content region, not including tab titles;
    - `w`: the width of the workspace content region;
    - `vScroll`: the width of the vertical scroll if it is present, or 0 if there is no scrollbar;
    - `hScroll`: the height of the horizontal scroll if it is present, or 0 if there is no scrollbar.

    Please note that `isPaddingEnabled()` from `UIFormPane`, `UserServicePane` and `UserServiceRawPane` are taken into account.

    Example to synchronize the size of an iFrame with the workspace size `String jsFnListenerName = "syncIFrameToWorkspace";
    String iFrameId = "myIFrameToSync";
    componentWriter.add("<iframe").addSafeAttribute("id", iFrameId).addSafeAttribute("src", src).addSafeAttribute("style", "border: none").add("/>");
    componentWriter.addJS("function ").addJS(jsFnListenerName).addJS("(size, sizeIncludingBottomBarHeight) {");
    componentWriter.addJS(" var iFrameEl = document.getElementById(\"" + iFrameId + "\");");
    componentWriter.addJS(" iFrameEl.style.height = size.h + \"px\";");
    componentWriter.addJS(" iFrameEl.style.width = size.w + \"px\";");
    componentWriter.addJS("}");
    componentWriter.addJS_addResizeWorkspaceListener(jsFnListenerName);`
    Parameters:
      `aFunctionName` - a JavaScript function name, which will be called when the workspace is resized.
    Since:
      5.4.2

  - ### addJS_switchToPerspective

    UIJavaScriptWriter addJS_switchToPerspective(String aPerspectiveName)
    Changes the page of the highest EBX® frame to the specified perspective.
    Parameters:
      `aPerspectiveName` - the name of the perspective, or `null` to have the advanced perspective.
    Since:
      5.7.0

  - ### addJS_switchToPerspectiveAction

    UIJavaScriptWriter addJS_switchToPerspectiveAction(String aPerspectiveName, String aPerspectiveActionName)
    Changes the page of the highest EBX® frame to the specified perspective action.
    Parameters:
      `aPerspectiveName` - the name of the perspective, or `null` to have the advanced perspective.
      `aPerspectiveActionName` - the name of the perspective action, or `null` to have the default action.
    Since:
      5.9.0 fix B