Package com.orchestranetworks.ui

# Class UIButtonSpecJSActionToggle

java.lang.Object
com.orchestranetworks.ui.UIButtonSpec
com.orchestranetworks.ui.UIButtonSpecJSActionToggle

public class UIButtonSpecJSActionToggle extends UIButtonSpec
Standard toggle button that calls a JavaScript command for each change of state. A command can be a function or a piece of JavaScript code.

The toggle button has two states:

- When the button is deactivated: OFF
- When the button is activated: ON

When 'OFF', the user can click the button and it stays in the 'ON' state. When 'ON', the user can click the button and it stays in the 'OFF' state.

Two JavaScript actions are associated with this button:

- when the button is activated, the 'ON' confirmation message is displayed if it has been set (see `UIButtonSpec.setConfirmationMessage(UserMessage)`), then `JSCmdOn` is called
- when the button is deactivated, the 'OFF' confirmation message is displayed if it has been set (see `setConfirmationMessageOff(UserMessage)`), then `JSCmdOff` is called

The toggle button can be used in a `<form>` and acts like a checkbox. To enable this feature, the input name must be set. If the state of the button is 'ON', the name will be sent with the value `ON_PARAMETER_VALUE`, if the state of the button is 'OFF', nothing will be sent.

The state of the button can also be managed in JavaScript with the function `UIJavaScriptWriter.addJS_setStateToToggleButton(String, String)`.

Since:
  5.2.3

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final boolean`
  `OFF`
  Use this constant with `setInitialState(boolean)` to set the button to 'OFF'.
  `static final boolean`
  `ON`
  Use this constant with `setInitialState(boolean)` to set the button to 'ON'.
  `static final String`
  `ON_PARAMETER_VALUE`
  HTTP request parameter value sent if the checkbox behavior is enabled and the form is submitted with the button set to 'ON'.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UIButtonSpecJSActionToggle(UserMessage aLabel, String aJSCmdOn, String aJSCmdOff)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final UserMessage`
  `getConfirmationMessageOff()`
  `final boolean`
  `getInitialState()`
  `final String`
  `getInputName()`
  `final String`
  `getJSCmdOff()`
  `final String`
  `getJSCmdOn()`
  `final void`
  `setConfirmationMessageOff(UserMessage confirmationMessageOff)`
  Sets a message to confirm the action performed when the button is deactivated.
  `final void`
  `setInitialState(boolean initialState)`
  Sets the initial state of this button.
  `final void`
  `setInputName(String inputName)`
  Enables checkbox behavior by setting its input name in the current form.

  ### Methods inherited from class com.orchestranetworks.ui.UIButtonSpec

  `getButtonIcon, getButtonLayout, getConfirmationMessage, getIconURL, getId, getLabel, getRelief, getTooltip, hasConfirmationMessage, isDefaultButton, isDisabled, isExcludedFromTabFocus, setButtonIcon, setButtonLayout, setConfirmationMessage, setCssClass, setDefaultButton, setDisabled, setExcludedFromTabFocus, setIconURL, setId, setLabel, setRelief, setTooltip`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### ON

    public static final boolean ON
    Use this constant with `setInitialState(boolean)` to set the button to 'ON'.
    See Also:
      - Constant Field Values

  - ### OFF

    public static final boolean OFF
    Use this constant with `setInitialState(boolean)` to set the button to 'OFF'.
    See Also:
      - Constant Field Values

  - ### ON_PARAMETER_VALUE

    public static final String ON_PARAMETER_VALUE
    HTTP request parameter value sent if the checkbox behavior is enabled and the form is submitted with the button set to 'ON'.
    See Also:
      - `setInputName(String)`
      - Constant Field Values

- ## Constructor Details

  - ### UIButtonSpecJSActionToggle

    public UIButtonSpecJSActionToggle(UserMessage aLabel, String aJSCmdOn, String aJSCmdOff)
    Parameters:
      `aLabel` - the label of the button.
      `aJSCmdOn` - the JavaScript command to call when the button is set to 'ON'.
      `aJSCmdOff` - the JavaScript command to call when the button is set to 'OFF'.

- ## Method Details

  - ### getJSCmdOn

    public final String getJSCmdOn()
    Returns:
      the JavaScript command invoked when this button is set to 'ON'.

  - ### getJSCmdOff

    public final String getJSCmdOff()
    Returns:
      the JavaScript command invoked when this button is set to 'OFF'.

  - ### getInitialState

    public final boolean getInitialState()
    Returns:
      the initial state to which this button is set (`ON` or `OFF`).

  - ### setInitialState

    public final void setInitialState(boolean initialState)
    Sets the initial state of this button. By default, the button is initially deactivated (`OFF`).

    The state of the button can also be managed in JavaScript with the function `UIJavaScriptWriter.addJS_setStateToToggleButton(String, String)`.

    Parameters:
      `initialState` - the value must be `ON` or `OFF`.

  - ### setConfirmationMessageOff

    public final void setConfirmationMessageOff(UserMessage confirmationMessageOff)
    Sets a message to confirm the action performed when the button is deactivated. A "Yes"/"Cancel" dialog will open when the button is deactivated.

    If the user clicks "Cancel" in the dialog, the action will not be called.

    To set a message to confirm the action when the button is activated, use `UIButtonSpec.setConfirmationMessage(UserMessage)`.

    Parameters:
      `confirmationMessageOff` - the confirmation message to set to the button when it turns OFF.

  - ### getConfirmationMessageOff

    public final UserMessage getConfirmationMessageOff()
    Returns:
      the confirmation message of the button when it is deactivated, `null` if it is not set.

      To get the confirmation message of the button when it is activated, call `UIButtonSpec.getConfirmationMessage()`.

  - ### getInputName

    public final String getInputName()
    See Also:
      - `setInputName(String)`

  - ### setInputName

    public final void setInputName(String inputName)
    Enables checkbox behavior by setting its input name in the current form.

    The toggle button can be used in a `<form>`, to act like a checkbox. If the state of the button is 'ON' upon form submission, the value sent will be `ON_PARAMETER_VALUE`, if the state of the button is 'OFF', no value will be sent.

    By default, the checkbox feature is not enabled and input name is `null`.

    Parameters:
      `inputName` - the value of the attribute `name` of the input checkbox, namely the name of the HTTP request parameter sent when the form is submitted.
    See Also:
      - https://www.w3.org/TR/REC-html40/interact/forms.html#adef-name-INPUT