Interface Field

All Superinterfaces:
Element, java.io.Serializable
All Known Subinterfaces:
TableColumn, WebFormField, WebFormTableColumn

public interface Field
extends Element
The Field interface is the base interface for a form field or workflow process attribute.

Individual fields can be accessed via the Fields interface.

Since:
V4.4
  • Method Summary

    Modifier and Type Method Description
    java.lang.String getDisplayValue()
    Returns a String representing the displayable value of the form field, with any default formatting applied.
    java.lang.String getDisplayValue​(boolean formatted)
    Returns a String representing the displayable value of the form field, optionally formatted for the user's locale.
    java.lang.String getStringValue()
    Returns a String value for the field that can be used to pass the value when calling another form, an Integration Service or opening a workflow job (see examples below).
    java.lang.String getType()
    Returns the form field type.
    java.lang.Object getValue()
    Returns an Object representing the value of the form field.
    void setDisplayValue​(java.lang.String value)
    Sets a value for the form field using the appropriate display format for the field type and the language currently in use.
    void setValue​(java.lang.Object value)
    Sets a value for the form field.

    Methods inherited from interface com.ebasetech.xi.api.Element

    getElementName, getElementType
  • Method Details

    • setValue

      void setValue​(java.lang.Object value)
      Sets a value for the form field. The object types that can be used for value vary according to the form field type as shown in the table below. In most cases, the mapping between object types and form field types is handled automatically. Date and time fields require special consideration, particularly when calculations are performed.

      Throws an FormRuntimeException if the value is not appropriate for the field type.

      Field TypeSupported Object Types
      Boolean Boolean: any value
      String: true values are "true", "Y", "Yes", "1", false values are "false", "N", "No", "0"
      Number: 1 is true, 0 is false
      Character String: any value
      Boolean: true becomes "Y", false becomes "N"
      Number: any value
      Integer
      Number
      Currency
      String: any numeric value
      Number: any value
      Date Date: both Java Date (java.util.Date) and Javascript Date objects can be used
      String: must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties
      Number: represents the number of milliseconds since 1st January 1970
      Datetime Date: both Java Date (java.util.Date) and Javascript Date objects can be used
      String: Date followed by a space then Time.
      Date must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties
      Time is in the format hh:mm:ss.ttt
      Number: represents the number of milliseconds since 1st January 1970
      Time Date: both Java Date (java.util.Date) and Javascript Date objects can be used
      String: must be in the format hh:mm:ss.ttt
      Number: represents the number of milliseconds since midnight
      Object Any object type can be used. Note that these objects become part of the form state and must therefore implement the Java Serializable interface.

      Further documentation.

      Javascript examples:

       fields.CHAR_FIELD.value = "Test";
       fields.CHAR_FIELD.setValue("Test");
       fields.NUM_FIELD.value = 123.456;
       fields.BOOL_FIELD.value = true;
       fields.DATE_FIELD.value = new Date();
       
      Parameters:
      value -
      Since:
      V4.4
      See Also:
      setDisplayValue(String)
    • getValue

      java.lang.Object getValue()
      Returns an Object representing the value of the form field. See also method getDisplayValue() which returns a String value for the form field and is the value shown to the user.

      The Java object type returned depends on the form field type:

      • Boolean - returns a Boolean (Javascript boolean)
      • Character - returns a String (Javascript string)
      • Currency - returns a BigDecimal (Javascript number)
      • Date - returns a Long representing the number of milliseconds since 1st January 1970, where the time portion is initially set to 00:00 (Javascript number)
      • Datetime - returns a Long representing the number of milliseconds since 1st January 1970 (Javascript number)
      • Integer - returns a BigInteger (Javascript number)
      • Numeric - returns a BigDecimal (Javascript number)
      • Object - returns the object set using the setValue(Object) method. Use getDisplayValue() when there is a need to pass the object across mediums that only support character data.
      • Time - returns a Long representing the number of milliseconds since midnight (Javascript number)
      Further documentation.

      Javascript example:

       var d1 = new Date(fields.DATE_FIELD.value);
       d1.setDate(d1.getDate() + 7);
       
      Returns:
      field value
      Since:
      V4.4
      See Also:
      getDisplayValue(boolean), getStringValue()
    • getDisplayValue

      java.lang.String getDisplayValue​(boolean formatted)
      Returns a String representing the displayable value of the form field, optionally formatted for the user's locale. See also method getValue() which returns a Java object value for the form field.

      When the field is associated with a list, returns the value displayed to the user. This is in contrast to method getValue() which provides the list return value as opposed to the list display value e.g. a static list entry might have a return value "M" and a display value "Male", in which case this method will return "Male" and method getValue() will return "M".

      Parameters:
      formatted - - the display value is formatted according to the formatting language configured for the current language. Formatting is applicable for date, time and numeric fields. See Tools > System Preferences > Internationalization for details of the formatting applied for each language. When false, any default formatting is applied: date fields are displayed with default formatting as specified in parameter Ufs.dateFormat in file UFSSetup.properties.
      Returns:
      String display value
      Since:
      V4.4
      See Also:
      getDisplayValue(), getValue(), getStringValue()
    • getDisplayValue

      java.lang.String getDisplayValue()
      Returns a String representing the displayable value of the form field, with any default formatting applied. See also method getValue() which returns a Java object value for the form field.

      For fields of type Object, returns a serialized value for the object which can be used to pass the object across mediums that only support character data e.g. a URL, as part of an XML document.

      The default formatting for date fields is specified in parameter Ufs.dateFormat in file UFSSetup.properties.

      When the field is associated with a list, returns the value displayed to the user. This is in contrast to method getValue() which provides the list return value as opposed to the list display value e.g. a static list entry might have a return value "M" and a display value "Male", in which case this method will return "Male" and method getValue() will return "M".

      Returns:
      String display value
      Since:
      V4.4
      See Also:
      getDisplayValue(boolean), getValue(), getStringValue()
    • setDisplayValue

      void setDisplayValue​(java.lang.String value)
      Sets a value for the form field using the appropriate display format for the field type and the language currently in use.

      Throws an FormRuntimeException if the value is not appropriate for the field type.

      Display formats can vary based on regional formatting associated with the language being used for the current form. Formatting is applicable for date, time and numeric fields. See Tools > System Preferences > Internationalization for details of the formatting applied for each language.

      • Boolean - value should be "true" or "false"
      • Character - any String value
      • Currency - any numeric String value, formatting commas/periods are supported
      • Date - should use an appropriate format for the current formatting language
      • Datetime - should use an appropriate format for the current formatting language
      • Integer - any numeric String value
      • Numeric - any numeric String value
      • Object - a serialized value for the Object
      • Time - using format hh:mm:ss.ttt
      Javascript examples:
       fields.CHAR_FIELD.displayValue = "Test";
       fields.CHAR_FIELD.setDisplayValue("Test");
       fields.NUM_FIELD.displayValue = "1,234,000.456";
       fields.BOOL_FIELD.displayValue = "true";
       fields.DATE_FIELD.displayValue = "10/24/2012";
       fields.TIME_FIELD.displayValue = "09:30";
       fields.DATETIME_FIELD.displayValue = "10/24/2012 09:30";
       
      Parameters:
      value -
      See Also:
      setValue(Object)
    • getStringValue

      java.lang.String getStringValue()
      Returns a String value for the field that can be used to pass the value when calling another form, an Integration Service or opening a workflow job (see examples below). For fields of type Object, returns a serialized value for the object. For all other field types, this method is equivalent to getDisplayValue().

      Javascript examples:

       // calling a form passing field values 
       var parms = {};
       parms.PARM1 = fields.OBJ1.stringValue;
       parms.PARM2 = fields.INT1.stringValue;
       form.callForm("FORM1", parms);
       // opening a workflow job passing field values 
       var parms = {};
       parms.PARM1 = fields.OBJ1.stringValue;
       parms.PARM2 = fields.INT1.stringValue;
       system.workflow.openJob("TEST_PROCESS", parms);
       
      Returns:
      Serialized value for fields of type Object
      Since:
      V4.4
      See Also:
      getDisplayValue(), getValue()
    • getType

      java.lang.String getType()
      Returns the form field type. This will be one of: BOOLEAN, CHAR, INTEGER, NUMBER, CURRENCY, DATE, DATETIME, TIME, OBJECT.

      Further documentation

      Returns:
      field type
      Since:
      V4.4