Package com.orchestranetworks.ui

# Interface UIComponentWriter

All Superinterfaces:
  `UIBodyWriter`, `UIDependencyRegisterer`, `UIJavaScriptWriter`, `UIResourceLocator`, `UISessionContext`

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

public interface UIComponentWriter extends UIBodyWriter, UIJavaScriptWriter, UIResourceLocator, UIDependencyRegisterer, UISessionContext
This interface offers common user interface methods to create standard EBX® components.

Since:
  5.2.0
See Also:
  - UI Developer Guide

- ## Method Summary

  Modifier and Type
  Method
  Description
  `UIComponentWriter`
  `addButtonHelp(String aURL)`
  Displays a button with the help icon.
  `UIComponentWriter`
  `addButtonJavaScript(UIButtonSpecJSAction aJavaScriptButtonSpec)`
  Adds a button for a JavaScript command.
  `UIComponentWriter`
  `addButtonJavaScriptToggle(UIButtonSpecJSActionToggle aJavaScriptToggleButtonSpec)`
  Adds a toggle button for two JavaScript commands (toggle ON and toggle OFF).
  `void`
  `addUILabel(UIFormLabelSpec aLabelSpec)`
  Adds the specified label.
  `void`
  `addUserAvatar(UserReference aUserReference)`
  Displays the standard user avatar (a circle of 26px diameter with initials or image).
  `UIButtonSpecJSAction`
  `buildButtonPreview(UIHttpManagerComponent aWebComponent)`
  Builds a preview button using the standard "preview" label.
  `UIButtonSpecJSAction`
  `buildButtonPreview(String aURL)`
  Builds a preview button, using the standard "preview" label.
  `UIButtonSpecJSAction`
  `buildButtonPreview(String aURL, UserMessage aLabel)`
  Builds a preview button with the specified label.
  `void`
  `endBorder()`
  Ends the border previously started by a `startBorder`.
  `void`
  `endExpandCollapseBlock()`
  Ends the expand/collapse block started by `startExpandCollapseBlock(UserMessage, boolean)` or `startExpandCollapseBlock(UIExpandCollapseBlock)`.
  `void`
  `endFormGroup()`
  Ends the form group previously started and stops the indentation.
  `void`
  `endFormRow()`
  Ends the form row previously started.
  `void`
  `endTableFormRow()`
  Ends a table of form rows and form groups previously started.
  `UIExpandCollapseBlock`
  `newExpandCollapseBlock()`
  Returns a new expand/collapse block specification which, by default, would be rendered collapsed with an empty label.
  `UIFormGroup`
  `newFormGroup(UIFormLabelSpec aLabelSpec)`
  Returns a new form group with the specified label.
  `UIFormRow`
  `newFormRow()`
  Returns a new form row, set with an empty icon and an empty label.
  `void`
  `startBorder(boolean isColored)`
  Starts a border.
  `void`
  `startBorder(boolean isColored, UserMessage aCaption)`
  Starts a border with a caption.
  `void`
  `startBorder(boolean isColored, UIFormLabelSpec aLabelSpec)`
  Starts a border with a caption.
  `String`
  `startExpandCollapseBlock(UserMessage aCaption, boolean collapsed)`
  Starts an expand/collapse block with a caption.
  `String`
  `startExpandCollapseBlock(UIExpandCollapseBlock aBlock)`
  Starts an expand/collapse block from the given specification.
  `void`
  `startFormGroup(UIFormGroup aFormGroup)`
  Starts a form group by writing its label according to the specified argument, an expand/collapse button, and a form indentation.
  `void`
  `startFormGroup(UIFormLabelSpec aLabelSpec)`
  Starts a form group by writing its specified label, an expand/collapse button, and a form indentation.
  `void`
  `startFormRow(UIFormRow aFormRow)`
  Starts a form row by writing its icon and label according to the specified argument.
  `void`
  `startFormRow(UIFormLabelSpec aLabelSpec)`
  Starts a form row containing a label and some plain HTML content.
  `void`
  `startFormRow(UIFormLabelSpec aLabelSpec, UIFormRowIcon aFormRowIcon)`
  Starts a form row containing an icon, a label and some plain HTML content.
  `void`
  `startFormRow(UIFormLabelSpec aLabelSpec, String anIconURL)`
  Starts a form row containing an icon, a label and some plain HTML content.
  `void`
  `startTableFormRow()`
  Starts a table layout of form rows and form groups.

  ### Methods inherited from interface com.orchestranetworks.ui.UIBodyWriter

  `add, add, add, add_cr, add_cr, addSafeAttribute, addSafeAttribute, addSafeInnerHTML, addSafeInnerHTML`

  ### Methods inherited from interface com.orchestranetworks.ui.UIDependencyRegisterer

  `addJavaScriptDependency`

  ### Methods inherited from interface com.orchestranetworks.ui.UIJavaScriptWriter

  `addJS, addJS_addResizeWorkspaceListener, addJS_cr, addJS_cr, addJS_openPreviewImage, addJS_openPreviewImageFromVar, addJS_setButtonDisabled, addJS_setExpandCollapseBlockExpanded, addJS_setStateToToggleButton, addJS_switchToPerspective, addJS_switchToPerspectiveAction`

  ### Methods inherited from interface com.orchestranetworks.ui.UIResourceLocator

  `createWebComponentForRootSession, createWebComponentForSubSession, getURLForAjaxComponent, getURLForAjaxComponent, getURLForPerspectiveSelection, getURLForPerspectiveSelection, getURLForResource, getURLForResource, getURLForResource, getURLForResource, getURLForResource, getURLForRest, getURLForSelection, getURLForSelection, getURLForSelection, getURLForSelection, getURLForSelection, getURLForSelection, getURLForViewSelection`

  ### Methods inherited from interface com.orchestranetworks.ui.UISessionContext

  `getLocale, getSession`

- ## Method Details

  - ### addButtonHelp

    UIComponentWriter addButtonHelp(String aURL)
    Displays a button with the help icon.

    Clicking on the button displays a help pop-up that opens the target URL.

    In a user service, the context-sensitive help button can be enabled using `ServiceContext.setContextSensitiveHelpURL(String)`.

    Parameters:
      `aURL` - the URL for the content of the pop-up.

  - ### addButtonJavaScript

    UIComponentWriter addButtonJavaScript(UIButtonSpecJSAction aJavaScriptButtonSpec)
    Adds a button for a JavaScript command.
    Parameters:
      `aJavaScriptButtonSpec` - a JavaScript button specification.

  - ### addButtonJavaScriptToggle

    UIComponentWriter addButtonJavaScriptToggle(UIButtonSpecJSActionToggle aJavaScriptToggleButtonSpec)
    Adds a toggle button for two JavaScript commands (toggle ON and toggle OFF).
    Parameters:
      `aJavaScriptToggleButtonSpec` - a JavaScript toggle button specification.
    Since:
      5.2.3

  - ### addUILabel

    void addUILabel(UIFormLabelSpec aLabelSpec)
    Adds the specified label. It can include additional documentation available in a pop-up.

  - ### addUserAvatar

    void addUserAvatar(UserReference aUserReference)
    Displays the standard user avatar (a circle of 26px diameter with initials or image). It is approximately the same width as a standard icon button.
    Since:
      5.7.0
    See Also:
      - `Directory.getUserAvatarURI(UserReference)`

  - ### buildButtonPreview

    UIButtonSpecJSAction buildButtonPreview(String aURL)
    Builds a preview button, using the standard "preview" label.
    Parameters:
      `aURL` - the URL for the content of the inner pop-up.
    See Also:
      - `buildButtonPreview(String, UserMessage)`

  - ### buildButtonPreview

    UIButtonSpecJSAction buildButtonPreview(String aURL, UserMessage aLabel)
    Builds a preview button with the specified label.

    Clicking on the button opens the standard modal inner pop-up with the specified URL. The returned object can be modified and added to the page using the method `addButtonJavaScript(UIButtonSpecJSAction)`.

    The button can be modified in different ways, such as setting the button to display only an icon using `UIButtonSpec#setButtonLayout` (`UIButtonLayout.ICON_ONLY`).

    Recommendations concerning the specified URL:

    - The inner pop-up works with an iFrame, so an external URL may not work.
    - The methods `getURLForSelection` from the `UIResourceLocator` should not be used, because the returned URLs change the state of the current session. They must be invoked in the current window only, not in pop-ups.
    Parameters:
      `aURL` - the URL of the inner pop-up content.
      `aLabel` - the label of the button.
    See Also:
      - `buildButtonPreview(UIHttpManagerComponent)`

  - ### buildButtonPreview

    UIButtonSpecJSAction buildButtonPreview(UIHttpManagerComponent aWebComponent)
    Builds a preview button using the standard "preview" label.

    Clicking the button opens the standard modal inner pop-up with the specified `Web component`. The returned object can be modified and added to the page using the method `addButtonJavaScript(UIButtonSpecJSAction)`.

    The button can be modified in different ways, such as setting the button to display only an icon using `UIButtonSpec#setButtonLayout` (`UIButtonLayout.ICON_ONLY`).

    If the `UIHttpManagerComponent` has no `CloseButtonSpec` defined, it will be set as default to `UIHttpManagerComponent.CloseButtonSpec.CROSS`. If the `UIHttpManagerComponent` has no `RedirectionURI`, the preview pop-up will close when the user click on the close/logout button.

    Parameters:
      `aWebComponent` - the `web component` of the inner pop-up content.
    Since:
      5.4.2

  - ### startBorder

    void startBorder(boolean isColored)
    Starts a border. This is equivalent to HTML `<fieldset>`.

    Note: The border must be terminated using endBorder().

    Parameters:
      `isColored` - `true` to have a colored border, `false` to have a grey border.

  - ### startBorder

    void startBorder(boolean isColored, UIFormLabelSpec aLabelSpec)
    Starts a border with a caption. This is equivalent to an HTML `<fieldset>` with a `<legend>`.

    Note: The border must be terminated using endBorder().

    Parameters:
      `isColored` - `true` to have a colored border, `false` to have a grey border.
      `aLabelSpec` - the border label.

  - ### startBorder

    void startBorder(boolean isColored, UserMessage aCaption)
    Starts a border with a caption. This is equivalent to an HTML `<fieldset>` with a `<legend>`.

    Note: The border must be terminated using endBorder().

    Parameters:
      `isColored` - `true` to have a colored border, `false` to have a gray border.
      `aCaption` - a `UserMessage` to enable caption.

  - ### endBorder

    void endBorder()
    Ends the border previously started by a `startBorder`.

  - ### newExpandCollapseBlock

    UIExpandCollapseBlock newExpandCollapseBlock()
    Returns a new expand/collapse block specification which, by default, would be rendered collapsed with an empty label.

    After having fully configured it, write it into a form thanks to `startExpandCollapseBlock(UIExpandCollapseBlock)`.

    When components ordering is dynamic over pages refresh (that is, their order depends on the record state, or any other parameter), it is recommended to set a stable identifier with `UIExpandCollapseBlock.setId(String)` to ensure the block state remains the same if the page is redisplayed after a page submit.

    Since:
      5.8.0

  - ### startExpandCollapseBlock

    String startExpandCollapseBlock(UIExpandCollapseBlock aBlock)
    Starts an expand/collapse block from the given specification.

    Note: The expand/collapse block must be terminated using endExpandCollapseBlock().

    The returned `id` is the one previously set by `UIExpandCollapseBlock.setId(String)`, or a randomly generated one. This id can be used with `UIJavaScriptWriter.addJS_setExpandCollapseBlockExpanded(String, String)`.

    Parameters:
      `aBlock` - the expand/collapse block specification
    Since:
      5.8.0

  - ### startExpandCollapseBlock

    String startExpandCollapseBlock(UserMessage aCaption, boolean collapsed)
    Starts an expand/collapse block with a caption.

    Note: The expand/collapse block must be terminated using endExpandCollapseBlock().

    When components ordering is dynamic over pages refresh (that is, their order depends on the record state, or any other parameter), please prefer `startExpandCollapseBlock(UIExpandCollapseBlock)` and set a stable identifier with `UIExpandCollapseBlock.setId(String)` to ensure the block state remains the same if the page is redisplayed after a page submit.

    Parameters:
      `aCaption` - the caption of the block (always displayed).
      `collapsed` - `true` to have the block initially collapsed, `false` to have the block initially expanded.
    Returns:
      the unique id of this expand/collapse block, to be used with `UIJavaScriptWriter.addJS_setExpandCollapseBlockExpanded(String, String)`.
    Since:
      5.2.3

  - ### endExpandCollapseBlock

    void endExpandCollapseBlock()
    Ends the expand/collapse block started by `startExpandCollapseBlock(UserMessage, boolean)` or `startExpandCollapseBlock(UIExpandCollapseBlock)`.
    Since:
      5.2.3

  - ### newFormRow

    UIFormRow newFormRow()
    Returns a new form row, set with an empty icon and an empty label.
    See Also:
      - `UIFormWriter.newFormRow(Path)`

  - ### startFormRow

    void startFormRow(UIFormLabelSpec aLabelSpec)
    Starts a form row containing a label and some plain HTML content. It can contain another form row.

    It is strongly recommended to surround form rows with `startTableFormRow()` and `endTableFormRow()` to have an automatic width for labels and benefit from the latest rendering innovations.

    Note: The form row must be ended with endFormRow() after creating its HTML content.

    Parameters:
      `aLabelSpec` - the row label.
    See Also:
      - `startFormRow(UIFormRow)`
      - `UIResponseContext.startFormRow(Path)`
      - `UIFormWriter.startFormRow(Path)`

  - ### startFormRow

    void startFormRow(UIFormLabelSpec aLabelSpec, String anIconURL)
    Starts a form row containing an icon, a label and some plain HTML content. Its content can be another form row.

    It is strongly recommended to surround form rows with `startTableFormRow()` and `endTableFormRow()` to have an automatic width for labels and benefit from the latest rendering innovations.

    Note: The form row must be ended with endFormRow() after creating its HTML content.

    Parameters:
      `aLabelSpec` - the row label.
      `anIconURL` - a custom icon URL.
    Since:
      5.2.3

  - ### startFormRow

    void startFormRow(UIFormLabelSpec aLabelSpec, UIFormRowIcon aFormRowIcon)
    Starts a form row containing an icon, a label and some plain HTML content. Its content can be another form row.

    It is strongly recommended to surround form rows with `startTableFormRow()` and `endTableFormRow()` to have an automatic width for labels and benefit from the latest rendering innovations.

    Note: The form row must be ended with endFormRow() after creating its HTML content.

    Parameters:
      `aLabelSpec` - the row label.
      `aFormRowIcon` - a form row icon.
    Since:
      5.2.3

  - ### startFormRow

    void startFormRow(UIFormRow aFormRow)
    Starts a form row by writing its icon and label according to the specified argument. The user input/display zone must be completed independently, it can be raw HTML content, a built-in component, or other form rows.

    It is strongly recommended to surround form rows with `startTableFormRow()` and `endTableFormRow()` to have an automatic width for labels and benefit from the latest rendering innovations.

    Note: The form row must be ended with endFormRow() after creating its HTML content.

    Parameters:
      `aFormRow` - the form row to be started.
    Throws:
      `PathAccessException` - if the specified row is based on an incorrect path.
    Since:
      5.3.0
    See Also:
      - `newFormRow()`
      - `startFormRow(UIFormLabelSpec)`
      - `UIResponseContext.startFormRow(Path)`
      - `UIFormWriter.startFormRow(Path)`

  - ### endFormRow

    void endFormRow()
    Ends the form row previously started.
    See Also:
      - `startFormRow(UIFormLabelSpec)`
      - `startFormRow(UIFormRow)`

  - ### newFormGroup

    UIFormGroup newFormGroup(UIFormLabelSpec aLabelSpec)
    Returns a new form group with the specified label.
    Parameters:
      `aLabelSpec` - the group label
    Since:
      5.7.0
    See Also:
      - `startFormGroup(UIFormGroup)`
      - `UIFormWriter.newFormGroup(Path)`
      - `UIResponseContext.newFormGroup(Path)`

  - ### startFormGroup

    void startFormGroup(UIFormLabelSpec aLabelSpec)
    Starts a form group by writing its specified label, an expand/collapse button, and a form indentation.

    The next form rows or form groups will be indented, until endFormGroup() is not called. The indentation is stackable. The maximum depth is 5.

    It is mandatory to surround a form group with `startTableFormRow()` and `endTableFormRow()` to have an automatic width for labels and benefit from the latest rendering innovations.

    Note: The form group must be ended with endFormGroup() to stop the indentation.

    Parameters:
      `aLabelSpec` - the group label.
    Throws:
      `IllegalStateException` - if `startTableFormRow()` was not called before.
    Since:
      5.7.0
    See Also:
      - `startFormGroup(UIFormGroup)`
      - `UIResponseContext.startFormGroup(Path)`
      - `UIFormWriter.startFormGroup(Path)`

  - ### startFormGroup

    void startFormGroup(UIFormGroup aFormGroup)
    Starts a form group by writing its label according to the specified argument, an expand/collapse button, and a form indentation.

    The next form rows or form groups will be indented, until endFormGroup() is not called. The indentation is stackable. The maximum depth is 5.

    It is mandatory to surround a form group with `startTableFormRow()` and `endTableFormRow()` to have an automatic width for labels and benefit from the latest rendering innovations.

    Note: The form group must be ended with endFormGroup() to stop the indentation.

    Parameters:
      `aFormGroup` - the form group to be started.
    Throws:
      `IllegalStateException` - if `startTableFormRow()` was not called before.
      `PathAccessException` - if the specified group is based on an incorrect path.
    Since:
      5.7.0
    See Also:
      - `newFormGroup(UIFormLabelSpec)`
      - `startFormGroup(UIFormLabelSpec)`
      - `UIResponseContext.startFormGroup(Path)`
      - `UIFormWriter.startFormGroup(Path)`

  - ### endFormGroup

    void endFormGroup()
    Ends the form group previously started and stops the indentation.
    Since:
      5.7.0
    See Also:
      - `startFormGroup(UIFormLabelSpec)`
      - `startFormGroup(UIFormGroup)`

  - ### startTableFormRow

    void startTableFormRow()
    Starts a table layout of form rows and form groups. A table layout of form rows and groups is composed of a first column displaying row labels with optional icons and a second column containing the input components. The main benefit is the optimization of the automatic label column width and the latest rendering innovations.

    A table layout of form rows and groups contains only form rows and form groups added with `startFormRow(...)`, `startFormGroup(...)` and `addFormRow(...)` in some subtype APIs. Adding anything else to the table can break the whole UI, and is thus not permitted.

    Note: The table must be ended with endTableFormRow() after adding the form rows and groups.

    Since:
      5.2.2
    See Also:
      - `startFormRow(UIFormLabelSpec)`
      - `startFormRow(UIFormRow)`
      - `startFormGroup(UIFormLabelSpec)`
      - `startFormGroup(UIFormGroup)`

  - ### endTableFormRow

    void endTableFormRow()
    Ends a table of form rows and form groups previously started.
    Since:
      5.2.2
    See Also:
      - `startTableFormRow()`