Package com.orchestranetworks.ui.form

Interface UIFormWriter

All Superinterfaces:
UIBodyWriter, UIComponentWriter, UIDependencyRegisterer, UIJavaScriptWriter, UIResourceLocator, UISessionContext
All Known Subinterfaces:
UIFormPaneWriter, UserServicePaneWriter, WidgetWriter, WidgetWriterForList
public interface UIFormWriter extends UIComponentWriter

This interface offers methods useful to create standard EBX® forms.

Before EBX® 5.7.1, most methods of this class were part of class UIFormPaneWriter.

Since:
5.7.1, 5.3.0 for methods originally part of UIFormPaneWriter

  • Method Details

    • newCustomWidget

      <T extends UIWidget> T newCustomWidget(Path aPath, UIWidgetFactory<T> aFactory)
      Returns a new instance of a widget which will be created by the given factory.
      Since:
      5.8.0

    • newBestMatching

      UIWidget newBestMatching(Path aPath)
      Returns a new widget that will be automatically selected according to the corresponding node definition in the data model.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node that is either terminal or under-terminal.
      See Also:

    • newTextBox

      UITextBox newTextBox(Path aPath)
      Returns a text input field, which can be one-line or multi-line.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type.
      See Also:

    • newTable

      UITable newTable(Path aPath)
      Returns a table widget
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node that is a association.
      See Also:

    • newDateTime

      UIDateTime newDateTime(Path aPath)
      Returns a date/time field.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type.
      See Also:

    • newColorPicker

      UIColorPicker newColorPicker(Path aPath)
      Returns a new color picker.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type.
      See Also:

    • newDataspaceSelector

      UIDataspaceSelector newDataspaceSelector(Path aPath)
      Returns a dataspace selector.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type.
      Since:
      5.8.1
      See Also:

    • newDatasetSelector

      UIDatasetSelector newDatasetSelector(Path aPath)
      Returns a new dataset selector.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type.
      Since:
      5.8.1
      See Also:

    • newComboBox

      UIComboBox newComboBox(Path aPath)
      Returns a new combo box.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type and depending on an enumeration.
      See Also:

    • newCheckBox

      UICheckBox newCheckBox(Path aPath)
      Returns a new check box widget.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a boolean or an aggregated list of a simple type and depending on an enumeration.
      Since:
      5.4.1
      See Also:

    • newCheckBoxGroup

      UICheckBoxGroup newCheckBoxGroup(Path aPath)
      Returns a new check box group widget.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to an aggregated list of a simple type and depending on an enumeration.
      See Also:

    • newDropDownList

      UIDropDownList newDropDownList(Path aPath)
      Returns a new drop-down list.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type and depending on an enumeration.
      See Also:

    • newListBox

      UIListBox newListBox(Path aPath)
      Returns a new list box.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type and depending on an enumeration.
      See Also:

    • newPassword

      UIPassword newPassword(Path aPath)
      Returns a password field.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a simple type node.
      Since:
      5.7.0
      See Also:

    • newRadioButton

      UIRadioButton newRadioButton(Path aPath)
      Returns a new radio button widget.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type and depending on an enumeration.
      See Also:

    • newRadioButtonGroup

      UIRadioButtonGroup newRadioButtonGroup(Path aPath)
      Returns a new radio button group widget.
      Parameters:
      aPath - location of the target node, relative to the record root node; it must refer to a node of a simple type and depending on an enumeration.
      See Also:

    • addWidget

      void addWidget(Path aPath)
      Adds the default widget, adapted to the data type and the facets of the specified node.

      If the node is hidden for the user, this method does nothing.

      This method is equivalent to:

      aUIFormWriter.addWidget(aUIFormWriter.newBestMatching(aPath));
      Parameters:
      aPath - location of the node, relative to the record root node.
      Throws:
      UnsupportedOperationException - if the specified path refers to a node that is neither terminal nor under-terminal.
      PathAccessException - if the specified path is incorrect.
      See Also:

    • addWidget

      void addWidget(UIWidget aWidget)
      Adds the specified widget.

      If the underlying node is hidden according to the permission rules, then this method does nothing. If the field is read-only according to the permission rules, then a read-only component is displayed. This method does not take into account the defaultView property (since its application is restricted to the default view, which is not the case here).

      Parameters:
      aWidget - the widget to be added to this pane.
      Throws:
      UnsupportedOperationException - if the specified widget refers to a node that is neither terminal nor under-terminal.
      PathAccessException - if the specified path is incorrect.
      See Also:

    • addFormRow

      void addFormRow(Path aPath)
      Adds a form row in the pane for the node at the given path.

      A form row is composed of an icon, a label and the user interface widget corresponding to the specified field or group, either in read-only or in read-write mode.

      The row is adapted to the data type and the facets of the node.

      If the field is hidden according to the permission rules, then this method does nothing. If the field is read-only according to the permission rules, then a read-only component is displayed. This method does not take into account the defaultView property (since its application is restricted to the default view, which is not the case here).

      This method is equivalent to:

      aUIFormWriter.addFormRow(aUIFormWriter.newFormRow(aPath));

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

      Parameters:
      aPath - location of the target node, relative to the record root node.
      Throws:
      UnsupportedOperationException - if the specified path refers to a node that is neither terminal nor under-terminal.
      PathAccessException - if the specified path is incorrect.

    • addFormRow

      void addFormRow(UIWidget aWidget)
      Adds a form row in the pane with the specified widget.

      A form row is composed of an icon, a label and the user interface widget corresponding to the specified field or group, either in read-only or in read-write mode.

      If the field is hidden according to the permission rules, then this method does nothing. If the field is read-only according to the permission rules, then a read-only component is displayed. This method does not take into account the defaultView property (since its application is restricted to the default view, which is not the case here).

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

      Parameters:
      aWidget - the widget to be added to this pane.
      Throws:
      UnsupportedOperationException - if the specified widget refers to a node that is neither terminal nor under-terminal.
      PathAccessException - if the specified path is incorrect.

    • newFormRow

      UIFormRow newFormRow(Path aPath)
      Builds the default model-driven form row based on the specified node. Here, "default model-driven" means the icon, label and documentation pane are computed from the data model definition.
      Parameters:
      aPath - location of the target node, relative to the record root node.
      See Also:

    • addFormRow

      void addFormRow(UIFormRow aFormRow)
      Adds a complete form row in the pane. The specified form row must be built with newFormRow(Path), the user input zone will be adapted to the data type and the facets of the underlying node.

      If the underlying node is hidden according to the permission rules, then this method does nothing. If the field is read-only according to the permission rules, then a read-only component is displayed. This method does not take into account the defaultView property (since its application is restricted to the default view, which is not the case here).

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

      Parameters:
      aFormRow - the form row, this object should be built by means of the method newFormRow(Path).
      Throws:
      IllegalArgumentException - if the specified form row has not been built with newFormRow(Path).
      UnsupportedOperationException - if the specified row's path refers to a node that is neither terminal nor under-terminal.
      PathAccessException - if the specified path is incorrect.

    • addFormRow

      void addFormRow(UIFormRow aFormRow, UIWidget aWidget)
      Adds a complete form row in the pane according to the given specification with the specified user interface widget.

      A form row is composed of an icon, a label and the user interface widget corresponding to the specified field or group, either in read-only or read-write mode.

      If the field is hidden according to the permission rules, then this method does nothing. If the field is read-only according to the permission rules, then a read-only component is displayed. This method does not take into account the defaultView property (since its application is restricted to the default view, which is not the case here).

      This method is equivalent to: 

       aUIFormWriter.startFormRow(aFormRow);
 aUIFormWriter.addWidget(aWidget);
 aUIFormWriter.endFormRow();

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

      Parameters:
      aFormRow - the form row specification with the Path of the target node
      aWidget - the widget to be added to this pane.
      Throws:
      UnsupportedOperationException - if the specified widget refers to a node that is neither terminal nor under-terminal.
      PathAccessException - if the specified path is incorrect.

    • startFormRow

      void startFormRow(Path aPath)
      Starts a row in the form for the node at the given path.

      This method displays the default icon and label of the specified node; the user input zone has to be added independently.

      This method is equivalent to:

      aUIFormWriter.startFormRow(aUIFormWriter.newFormRow(aPath));

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

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

      Parameters:
      aPath - location of the target node, relative to the record root node.
      Throws:
      PathAccessException - if the specified path is incorrect.
      See Also:

    • addFormGroup

      void addFormGroup(UIFormGroup aFormGroup)
      Adds a group which represents the given path children.

      If the underlying node is hidden according to the permission rules, then this method does nothing. If the field is read-only according to the permission rules, then a read-only component is displayed. This method does not take into account the defaultView property for the root path (since its application is restricted to the default view, which is not the case here).

      The call function should be between a UIComponentWriter.startTableFormRow() and UIComponentWriter.endTableFormRow().

      Child nodes which should be displayed in an external tab are ignored.

      Parameters:
      aFormGroup - a form group leading to a complex node
      Throws:
      PathAccessException - if the specified path included in the UIFormGroup is incorrect; for instance, it does not refer to an existing node, or it is absolute and specifies a record node, or specifies a terminal value descendant.
      Since:
      5.8.0
      See Also:

    • addFormRowOrGroup

      void addFormRowOrGroup(Path aPath)
      Adds rows to the form to represent the given path. This method is a shorthand for using addFormRow(Path) and addFormGroup(UIFormGroup). The call function should be between UIComponentWriter.startTableFormRow() and UIComponentWriter.endTableFormRow().

      If the path is equal to the root path, it will only add children of the associated SchemaNode.

      Child nodes which should be displayed in an external tab are ignored.

      Parameters:
      aPath - path of the targeted node, should be valid
      Throws:
      PathAccessException - if the specified path is incorrect; for instance, it does not refer to an existing node, or it is absolute and specifies a record node, or specifies a terminal value descendant.
      Since:
      5.8.0
      See Also:

    • newFormGroup

      UIFormGroup newFormGroup(Path aPath)
      Builds the default model-driven form group based on the specified node. Here, "default model-driven" means the label, the documentation pane and the initial state of the group (expanded or collapsed) are computed from the data model definition.
      Parameters:
      aPath - location of the target node, relative to the record root node.
      Since:
      5.7.0
      See Also:

    • startFormGroup

      void startFormGroup(Path aPath)
      Starts a form group for the node at the given path.

      This method displays the default model-driven form group based on the specified node. Here, "default model-driven" means that the label, the documentation pane and the initial state of the group (expanded or collapsed) are computed from the data model definition.

      This method is equivalent to:

      aUIFormWriter.startFormGroup(aUIFormWriter.newFormGroup(aPath));

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

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

      Parameters:
      aPath - location of the target node, relative to the record root node.
      Throws:
      PathAccessException - if the specified path is incorrect.
      IllegalStateException - if UIComponentWriter.startTableFormRow() was not called before.
      Since:
      5.7.0
      See Also:

    • addLabel

      void addLabel(Path aPath)
      Adds the label of the node at the given path.
      Parameters:
      aPath - location of the target node, relative to the record root node.

    • startBorder

      void startBorder(boolean isColored, Path aPath)
      Starts a border with a title caption. This is equivalent to an HTML <fieldset> with a <legend>.

      Note: The border must be terminated with UIComponentWriter.endBorder().

      Parameters:
      isColored - true to have a border color, false to have a gray border.
      aPath - required, location of the target, relative to the record root node (for better reusability, it is advised to use a relative path)
      Throws:
      PathAccessException - if the specified path is incorrect.
      See Also:

    • addJS_getNodeValue

      UIJavaScriptWriter addJS_getNodeValue(Path aPath)
      Adds JavaScript code to get the current value of a node, as set in the form.
      Example of getting a variable 
       jsWriter.addJS_cr();
 jsWriter.addJS("var myValue = ");
 jsWriter.addJS_getNodeValue(myPath).addJS(";");
      Example of calling a function with the value as the argument 
       jsWriter.addJS_cr();
 jsWriter.addJS("myFunction(");
 jsWriter.addJS_getNodeValue(myPath).addJS(", anotherArgument);");

      Note: If the node is read-only, the JavaScript type is automatic (the UIWidget set for this node is not applied).

      Known limitation: If the node can be inherited, the value is the overwritten value in the input field.

      Parameters:
      aPath - location of the target node, relative to the record root node.
      Since:
      5.3.1

    • addJS_setNodeValue

      UIJavaScriptWriter addJS_setNodeValue(String aVarName, Path aPath)
      Adds JavaScript code to set the value of a node from a JavaScript variable.
      Example of setting a value from a variable 
       jsWriter.addJS_cr();
 jsWriter.addJS("var myValue = myFunctionComputingTheValue(withArgument);");
 jsWriter.addJS_setNodeValue("myValue", myPath);
      Mapping to JavaScript types

      The mapping to a JavaScript type depends on the widget that is associated with the specified path. For more information, see 'JavaScript type' in the JavaDoc of each widget.

      Action on "after value changed"

      If an afterValueChanged action is defined on the widget, it will trigger if the value is valid (for example, setting 'true' for a date widget is not valid).

      Known limitation: If the node can be inherited, the value is the overwritten value in the input field.

      Parameters:
      aVarName - the name of a JavaScript variable containing the value, or the raw value.
      aPath - location of the target node, relative to the record root node.
      Since:
      5.3.1
      See Also:

    • addJS_setNodeMandatoryIndicator

      void addJS_setNodeMandatoryIndicator(boolean isDisplayed, Path aPath)
      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:
      isDisplayed - true to add a mandatory indicator, false to remove a mandatory indicator.
      aPath - location of the target node, relative to the record root node.
      Since:
      6.0.0
      See Also:

    • getPrefixedPath

      Path getPrefixedPath(Path aPath)
      Gets the prefixed path for the specified path, taking into account the potential current ObjectKey.

      This method is useful for instance when using JavaScript methods JavaScriptCatalog.ebx_form_getValue(String) and JavaScriptCatalog.ebx_form_setValue(String, Object).

      Since:
      5.8.0
      See Also:

    • addJS_hideTab

      UIJavaScriptWriter addJS_hideTab(String tabId)
      Hides the UIFormPaneWithTabs.Tab having the specified identifier.
      Since:
      5.7.0
      See Also:

    • addJS_showTab

      UIJavaScriptWriter addJS_showTab(String tabId)
      Shows the UIFormPaneWithTabs.Tab having the specified identifier.
      Since:
      5.7.0
      See Also:

    • getDisplayMode

      UIFormNode.DisplayMode getDisplayMode(Path aPath)
      Returns the display mode used in the model driven form.

      If the underlying node is a table, will return UIForm.DisplayMode.NONE.

      Parameters:
      aPath - the path, must be relative.
      Throws:
      PathAccessException - if the specified path is incorrect.
      Since:
      5.8.0