Class FormItem

All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasShowContextMenuHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers
Direct Known Subclasses:
BlurbItem, CanvasItem, CheckboxItem, DateItem, HeaderItem, HiddenItem, NativeCheckboxItem, RadioGroupItem, SelectItem, SpacerItem, StaticTextItem, TextAreaItem, TextItem, TimeItem

A UI component that can participate in a DynamicForm, allowing editing or display of one of the values tracked by the form.

FormItems do not render themselves, instead, they are provided to a DynamicForm via DynamicForm.setItems()

See the DynamicForm documentation for details and sample code.

  • Field Details

    • scClassName

      protected String scClassName
    • configOnly

      protected boolean configOnly
    • warnOnEditorTypeConversionDefault

      protected static boolean warnOnEditorTypeConversionDefault
    • warnOnEditorTypeConversion

      protected boolean warnOnEditorTypeConversion
  • Constructor Details

    • FormItem

      public FormItem()
    • FormItem

      public FormItem(JavaScriptObject jsObj)
    • FormItem

      public FormItem(String name)
  • Method Details

    • getOrCreateRef

      public static FormItem getOrCreateRef(JavaScriptObject jsObj)
    • getPaletteDefaults

      public Map getPaletteDefaults()
      This method returns a Map of config properties suitable for use as the "defaults" attribute of a PaletteNode. Use it when you need to work with PaletteNodes indirectly, such when setting up TileRecords that will be used in a TilePalette. See the dev tools overview for examples of how to assemble and acquire a suitable defaults object when you are creating a PaletteNode indirectly
    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:
    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:
    • changePickerIconDefaults

      public static void changePickerIconDefaults(FormItemIcon defaults)
    • setAccessKey

      public FormItem setAccessKey(String accessKey)
      If specified this governs the HTML accessKey for the item.

      This should be set to a character - when a user hits the html accessKey modifier for the browser, plus this character, focus will be given to the item. The accessKey modifier can vary by browser and platform.

      The following list of default behavior is for reference only, developers should also consult browser documentation for additional information.

      • Internet Explorer (all platforms): Alt + accessKey
      • Mozilla Firefox (Windows, Unix): Alt+Shift + accessKey
      • Mozilla Firefox (Mac): Ctrl+Opt + accessKey
      • Chrome and Safari (Windows, Unix): Alt + accessKey
      • Chrome and Safari (Mac): Ctrl+Opt + accessKey
      Parameters:
      accessKey - New accessKey value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getAccessKey

      public String getAccessKey()
      If specified this governs the HTML accessKey for the item.

      This should be set to a character - when a user hits the html accessKey modifier for the browser, plus this character, focus will be given to the item. The accessKey modifier can vary by browser and platform.

      The following list of default behavior is for reference only, developers should also consult browser documentation for additional information.

      • Internet Explorer (all platforms): Alt + accessKey
      • Mozilla Firefox (Windows, Unix): Alt+Shift + accessKey
      • Mozilla Firefox (Mac): Ctrl+Opt + accessKey
      • Chrome and Safari (Windows, Unix): Alt + accessKey
      • Chrome and Safari (Mac): Ctrl+Opt + accessKey
      Returns:
      Current accessKey value. Default value is null
      See Also:
    • setAlign

      public FormItem setAlign(Alignment align)
      Alignment of this item in its cell. Note that the alignment of text / content within this item is controlled separately via textAlign (typically textAlign applies to items showing a "textBox", such as a TextItem or SelectItem, as well as text-only form item types such as StaticTextItem and HeaderItem). If applyAlignToText is true, then the textAlign setting, if unset, will default to the align setting if set.
      Parameters:
      align - New align value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getAlign

      public Alignment getAlign()
      Alignment of this item in its cell. Note that the alignment of text / content within this item is controlled separately via textAlign (typically textAlign applies to items showing a "textBox", such as a TextItem or SelectItem, as well as text-only form item types such as StaticTextItem and HeaderItem). If applyAlignToText is true, then the textAlign setting, if unset, will default to the align setting if set.
      Returns:
      Current align value. Default value is null
      See Also:
    • setAllowExpressions

      public FormItem setAllowExpressions(Boolean allowExpressions)
      For a form that produces filter criteria (see form.getValuesAsCriteria()), allows the user to type in simple expressions to cause filtering with that operator. For example, entering ">5" means values greater than 5, and ">0 and <5" means values between 0 and 5.

      The following table lists character sequences that can be entered as a prefix to a value, and the corresponding operator that will be used.

      PrefixOperator
      <lessThan
      >greaterThan
      <=lessThanOrEqual
      >=greaterThanOrEqual
      someValue...someValuebetweenInclusive
      !notEqual
      ^startsWith
      |endsWith
      !^notStartsWith plus logical not
      !@notEndsWith plus logical not
      ~contains
      !~notContains
      $isBlank
      !$notBlank
      #isNull
      !#isNotNull
      ==exact match (for fields where 'contains' is the default)

      Two further special notations are allowed:

      • /regex/ means the value is taken as a regular expression and applied via the "regexp" operator
      • =.fieldName means the value should match the value of another field. Either the user-visible title of the field (field.title) or the field's name (field.name) may be used.

      In all cases, if an operator is disallowed for the field (via field.validOperators at either the dataSource or field level), the operator character is ignored (treated as part of a literal value).

      By default, the case-insensitive version of the operator is used (eg, startsWith will actually use "iStartsWith"). To avoid this, explicitly set item.operator (the default operator) to any case sensitive operator (eg "equals" or "contains") and case sensitive operators will be used for user-entered expressions.

      Compound expressions (including "and" and "or") are allowed only for numeric or date/time types.

      Note that if the user does not type a prefix or use other special notation as described above, the operator specified via operator is used, or if formItem.operator is unspecified, a default operator chosen as described under operator.

      Also note that whatever you enter will be used literally, including any whitespace characters. For example if you input '== China ' then ' China ' will be the value.

      The allowExpression behavior can be enabled for every field in a form via DynamicForm.allowExpressions.

      Finally, note that, like operator, enabling allowExpressions:true causes form.getValuesAsCriteria()) to return AdvancedCriteria.

      Parameters:
      allowExpressions - New allowExpressions value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getAllowExpressions

      public Boolean getAllowExpressions()
      For a form that produces filter criteria (see form.getValuesAsCriteria()), allows the user to type in simple expressions to cause filtering with that operator. For example, entering ">5" means values greater than 5, and ">0 and <5" means values between 0 and 5.

      The following table lists character sequences that can be entered as a prefix to a value, and the corresponding operator that will be used.

      PrefixOperator
      <lessThan
      >greaterThan
      <=lessThanOrEqual
      >=greaterThanOrEqual
      someValue...someValuebetweenInclusive
      !notEqual
      ^startsWith
      |endsWith
      !^notStartsWith plus logical not
      !@notEndsWith plus logical not
      ~contains
      !~notContains
      $isBlank
      !$notBlank
      #isNull
      !#isNotNull
      ==exact match (for fields where 'contains' is the default)

      Two further special notations are allowed:

      • /regex/ means the value is taken as a regular expression and applied via the "regexp" operator
      • =.fieldName means the value should match the value of another field. Either the user-visible title of the field (field.title) or the field's name (field.name) may be used.

      In all cases, if an operator is disallowed for the field (via field.validOperators at either the dataSource or field level), the operator character is ignored (treated as part of a literal value).

      By default, the case-insensitive version of the operator is used (eg, startsWith will actually use "iStartsWith"). To avoid this, explicitly set item.operator (the default operator) to any case sensitive operator (eg "equals" or "contains") and case sensitive operators will be used for user-entered expressions.

      Compound expressions (including "and" and "or") are allowed only for numeric or date/time types.

      Note that if the user does not type a prefix or use other special notation as described above, the operator specified via operator is used, or if formItem.operator is unspecified, a default operator chosen as described under operator.

      Also note that whatever you enter will be used literally, including any whitespace characters. For example if you input '== China ' then ' China ' will be the value.

      The allowExpression behavior can be enabled for every field in a form via DynamicForm.allowExpressions.

      Finally, note that, like operator, enabling allowExpressions:true causes form.getValuesAsCriteria()) to return AdvancedCriteria.

      Returns:
      Current allowExpressions value. Default value is null
      See Also:
    • setAlwaysFetchMissingValues

      public FormItem setAlwaysFetchMissingValues(Boolean alwaysFetchMissingValues)
      If this form item has a specified optionDataSource and fetchMissingValues is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related record if displayField is specified and the new item value is not present in any valueMap explicitly specified on the item.

      Setting this property to true means that a fetch will occur against the optionDataSource to retrieve the related record even if displayField is unset, or the item has a valueMap which explicitly contains this field's value.

      An example of a use case where this might be set would be if formatValue() or formatEditorValue() were written to display properties from the selected record.

      Note - for efficiency we cache the associated record once a fetch has been performed, meaning if the value changes, then reverts to a previously seen value, we do not kick off an additional fetch even if this property is true. If necessary this cache may be explicitly invalidated via a call to invalidateDisplayValueCache()

      Note : This is an advanced setting

      Parameters:
      alwaysFetchMissingValues - New alwaysFetchMissingValues value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getAlwaysFetchMissingValues

      public Boolean getAlwaysFetchMissingValues()
      If this form item has a specified optionDataSource and fetchMissingValues is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related record if displayField is specified and the new item value is not present in any valueMap explicitly specified on the item.

      Setting this property to true means that a fetch will occur against the optionDataSource to retrieve the related record even if displayField is unset, or the item has a valueMap which explicitly contains this field's value.

      An example of a use case where this might be set would be if formatValue() or formatEditorValue() were written to display properties from the selected record.

      Note - for efficiency we cache the associated record once a fetch has been performed, meaning if the value changes, then reverts to a previously seen value, we do not kick off an additional fetch even if this property is true. If necessary this cache may be explicitly invalidated via a call to invalidateDisplayValueCache()

      Returns:
      Current alwaysFetchMissingValues value. Default value is false
    • setAlwaysShowControlBox

      public FormItem setAlwaysShowControlBox(Boolean alwaysShowControlBox)
      A formItem showing a pickerIcon will always write out a "control box" around the text box and picker icon. This is an HTML element styled using the specified controlStyle.

      This attribute controls whether the control box should be written out even if the picker icon is not being shown. If unset, default behavior will write out a control table if showPickerIcon is true and the icon is not suppressed via FormItemIcon.showIf(). This means the control table can be written out with no visible picker if showPickerIconOnFocus is true and the item does not have focus.

      This attribute is useful for developers who wish to rely on styling specified via the controlStyle even while the picker icon is not visible.

      See the form item styling overview for details of the control table and other styling options.

      Note : This is an advanced setting

      Parameters:
      alwaysShowControlBox - New alwaysShowControlBox value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getAlwaysShowControlBox

      public Boolean getAlwaysShowControlBox()
      A formItem showing a pickerIcon will always write out a "control box" around the text box and picker icon. This is an HTML element styled using the specified controlStyle.

      This attribute controls whether the control box should be written out even if the picker icon is not being shown. If unset, default behavior will write out a control table if showPickerIcon is true and the icon is not suppressed via FormItemIcon.showIf(). This means the control table can be written out with no visible picker if showPickerIconOnFocus is true and the item does not have focus.

      This attribute is useful for developers who wish to rely on styling specified via the controlStyle even while the picker icon is not visible.

      See the form item styling overview for details of the control table and other styling options.

      Returns:
      Current alwaysShowControlBox value. Default value is null
    • setApplyAlignToText

      public FormItem setApplyAlignToText(boolean applyAlignToText)
      If the textAlign is unset, should the align setting, if set, be used for this item's textAlign?

      applyAlignToText defaults to false for most form item types. It defaults to true for StaticTextItem and HeaderItem, which are text-based form item types that do not have a natural distinction between the item and its cell.

      Note : This is an advanced setting

      Parameters:
      applyAlignToText - New applyAlignToText value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getApplyAlignToText

      public boolean getApplyAlignToText()
      If the textAlign is unset, should the align setting, if set, be used for this item's textAlign?

      applyAlignToText defaults to false for most form item types. It defaults to true for StaticTextItem and HeaderItem, which are text-based form item types that do not have a natural distinction between the item and its cell.

      Returns:
      Current applyAlignToText value. Default value is false
      See Also:
    • setApplyHeightToTextBox

      public FormItem setApplyHeightToTextBox(Boolean applyHeightToTextBox)
      If height is specified, should it be applied to the item's text box element?

      If unset, behavior is determined as described in shouldApplyHeightToTextBox()

      Note : This is an advanced setting

      Parameters:
      applyHeightToTextBox - New applyHeightToTextBox value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getApplyHeightToTextBox

      public Boolean getApplyHeightToTextBox()
      If height is specified, should it be applied to the item's text box element?

      If unset, behavior is determined as described in shouldApplyHeightToTextBox()

      Returns:
      Current applyHeightToTextBox value. Default value is null
    • setAriaRole

      public FormItem setAriaRole(String ariaRole)
      ARIA role of this formItem. Usually does not need to be manually set - see Accessibility.

      Note : This is an advanced setting

      Parameters:
      ariaRole - New ariaRole value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getAriaRole

      public String getAriaRole()
      ARIA role of this formItem. Usually does not need to be manually set - see Accessibility.
      Returns:
      Current ariaRole value. Default value is null
      See Also:
    • setAutoComplete

      public FormItem setAutoComplete(AutoComplete autoComplete)
      Should this item allow browser auto-completion of its value? Applies only to items based on native HTML form elements (TextItem, PasswordItem, etc), and will only have a user-visible impact for browsers where native autoComplete behavior is actually supported and enabled via user settings.

      Alternatively, autoCompleteKeywords can be specified, in which case this setting is ignored. If autoCompleteKeywords are not provided, and autoComplete is not set on this FormItem, the value of DynamicForm.autoComplete is used.

      Note that even with this value set to "none", native browser auto-completion may occur for log in forms (forms containing username and password fields). This behavior varies by browser, and is a result of an intentional change by some browser developers to disregard the HTML setting autocomplete=off for password items or log-in forms.

      In some browsers any form redraw (including a redraw from a call to DynamicForm.setValues()) will re-populate the form with the natively remembered login credentials. This can make it very difficult to control the values displayed to the user, as a call to 'setValues()' may appear to be ignored. While behavior varies by browser we have specifically observed this behavior in Safari. Moreover in this browser, if the user asks the browser to remember login credentials for a URL, any form with a password item and a text item may be auto-filled with the remembered login credentials, even if the form's configuration and field names differ from those on the login form.

      If an application has both an initial log in form, and a separate form within the application which makes contains a Password item (a use case might be an interface for a user with manager privileges for modifying other users' passwords), this will cause the second form to autofill with unexpected values.

      Should this arise, developers can avoid this by making the initial log in interface into a separate log in page from the main application page. This is often good practice in any case for reasons outlined in the "Authentication" section of the Quick Start guide.

      Parameters:
      autoComplete - New autoComplete value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getAutoComplete

      public AutoComplete getAutoComplete()
      Should this item allow browser auto-completion of its value? Applies only to items based on native HTML form elements (TextItem, PasswordItem, etc), and will only have a user-visible impact for browsers where native autoComplete behavior is actually supported and enabled via user settings.

      Alternatively, autoCompleteKeywords can be specified, in which case this setting is ignored. If autoCompleteKeywords are not provided, and autoComplete is not set on this FormItem, the value of DynamicForm.autoComplete is used.

      Note that even with this value set to "none", native browser auto-completion may occur for log in forms (forms containing username and password fields). This behavior varies by browser, and is a result of an intentional change by some browser developers to disregard the HTML setting autocomplete=off for password items or log-in forms.

      In some browsers any form redraw (including a redraw from a call to DynamicForm.setValues()) will re-populate the form with the natively remembered login credentials. This can make it very difficult to control the values displayed to the user, as a call to 'setValues()' may appear to be ignored. While behavior varies by browser we have specifically observed this behavior in Safari. Moreover in this browser, if the user asks the browser to remember login credentials for a URL, any form with a password item and a text item may be auto-filled with the remembered login credentials, even if the form's configuration and field names differ from those on the login form.

      If an application has both an initial log in form, and a separate form within the application which makes contains a Password item (a use case might be an interface for a user with manager privileges for modifying other users' passwords), this will cause the second form to autofill with unexpected values.

      Should this arise, developers can avoid this by making the initial log in interface into a separate log in page from the main application page. This is often good practice in any case for reasons outlined in the "Authentication" section of the Quick Start guide.

      Returns:
      Current autoComplete value. Default value is null
      See Also:
    • setAutoCompleteKeywords

      public FormItem setAutoCompleteKeywords(String... autoCompleteKeywords)
      Set of autocompletion keywords to be used with the native "autocomplete" attribute, in accordance with the HTML5 Autofill specification.

      When autoCompleteKeywords are provided, the autoComplete setting is ignored.

      Parameters:
      autoCompleteKeywords - New autoCompleteKeywords value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getAutoCompleteKeywords

      public String[] getAutoCompleteKeywords()
      Set of autocompletion keywords to be used with the native "autocomplete" attribute, in accordance with the HTML5 Autofill specification.

      When autoCompleteKeywords are provided, the autoComplete setting is ignored.

      Returns:
      Current autoCompleteKeywords value. Default value is null
    • setBrowserInputType

      public FormItem setBrowserInputType(String browserInputType)
      Form item input type - governs which keyboard should be displayed for mobile devices (supported on iPhone / iPad)

      Note : This is an advanced setting

      Parameters:
      browserInputType - New browserInputType value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getBrowserInputType

      public String getBrowserInputType()
      Form item input type - governs which keyboard should be displayed for mobile devices (supported on iPhone / iPad)
      Returns:
      Current browserInputType value. Default value is null
    • setBrowserSpellCheck

      public FormItem setBrowserSpellCheck(Boolean browserSpellCheck)
      If this browser supports spell-checking of text editing elements, do we want this enabled for this item? If unset the property will be inherited from the containing form.

      Notes:
      - this property only applies to text based items such as TextItem and TextAreaItem.
      - this property is not supported on all browsers.

      Note : This is an advanced setting

      Parameters:
      browserSpellCheck - New browserSpellCheck value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getBrowserSpellCheck

      public Boolean getBrowserSpellCheck()
      If this browser supports spell-checking of text editing elements, do we want this enabled for this item? If unset the property will be inherited from the containing form.

      Notes:
      - this property only applies to text based items such as TextItem and TextAreaItem.
      - this property is not supported on all browsers.

      Returns:
      Current browserSpellCheck value. Default value is null
      See Also:
    • setCanEdit

      public FormItem setCanEdit(Boolean canEdit)
      Is this form item editable (canEdit:true) or read-only (canEdit:false)? Setting the form item to non-editable causes it to render as read-only. Can be updated at runtime via the setCanEdit() method.

      Read-only appearance may be specified via readOnlyDisplay. The default setting for this value ("readOnly") differs from the disabled state in that the form item is not rendered with disabled styling and most form items will allow copying of the contents while read-only but do not while disabled.

      Note that for forms bound to a DataSource, if this property is not explicitly set at the item level, its default value will match the DynamicForm.canEditFieldAttribute on the associated dataSource field.

      Developers should also be aware that the readOnlyDisplay attribute is unrelated to the DataSourceField.readOnlyEditorType attribute. When a DynamicForm is first bound to a dataSource, for canEdit:false DataSourceFields, DataSourceField.readOnlyEditorType will determine what FormItemType should be created for the field. Once created, a FormItem's type can not be changed. Setting canEdit at runtime will simply change the appearance of the item to allow or disallow editing of the item.

      Note that this property may validly be null as a distinct state from false. See DynamicForm.fieldIsEditable() for an API that will always return true or false and give a definitive answer as to whether editing is possible.

      If this method is called after the component has been drawn/initialized: Is this form item editable (canEdit:true) or read-only (canEdit:false)? Setting the form item to non-editable causes it to render as read-only, using the appearance specified via readOnlyDisplay.

      The default appearance for canEdit:false items (readOnlyDisplay:"readOnly") differs from the disabled state in that the form item is not rendered with disabled styling and most form items will allow copying of the contents while read-only but do not while disabled.

      Overrides:
      setCanEdit in class Field
      Parameters:
      canEdit - Can this form item be edited?. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getCanEdit

      public Boolean getCanEdit()
      Is this form item editable (canEdit:true) or read-only (canEdit:false)? Setting the form item to non-editable causes it to render as read-only. Can be updated at runtime via the setCanEdit() method.

      Read-only appearance may be specified via readOnlyDisplay. The default setting for this value ("readOnly") differs from the disabled state in that the form item is not rendered with disabled styling and most form items will allow copying of the contents while read-only but do not while disabled.

      Note that for forms bound to a DataSource, if this property is not explicitly set at the item level, its default value will match the DynamicForm.canEditFieldAttribute on the associated dataSource field.

      Developers should also be aware that the readOnlyDisplay attribute is unrelated to the DataSourceField.readOnlyEditorType attribute. When a DynamicForm is first bound to a dataSource, for canEdit:false DataSourceFields, DataSourceField.readOnlyEditorType will determine what FormItemType should be created for the field. Once created, a FormItem's type can not be changed. Setting canEdit at runtime will simply change the appearance of the item to allow or disallow editing of the item.

      Note that this property may validly be null as a distinct state from false. See DynamicForm.fieldIsEditable() for an API that will always return true or false and give a definitive answer as to whether editing is possible.

      Overrides:
      getCanEdit in class Field
      Returns:
      Is this form item editable or read-only?

      This setting differs from the enabled/disabled state in that most form items will allow copying of the contents while read-only but do not while disabled.

      Important note: this method is not intended as an override point to make an item conditionally read-only. It is not called at the appropriate times to serve as a dynamic control over editability. Developers may instead use readOnlyWhen rules to dynamically control editability of items. Default value is null

      See Also:
    • setCanEditOpaqueValues

      public FormItem setCanEditOpaqueValues(Boolean canEditOpaqueValues)
      If true, indicates that this FormItem is capable of editing "opaque" values, ie, objects that are more complex than simple primitive types like numbers, strings and dates. Ordinarily, you use the SimpleType system to convert these opaque values into "atomic" values that can be edited by the built-in editors like TextItem. However, sometimes you to create a custom editor that knows how to edit a particular opaque type in a domain-specific way - for example, a composite custom FormItem that allows the user to edit both a number and a currency code, both of which are needed to make a proper monetary amount (for that particular application). When this value is set, the FormItem will manage the opaque value directly, rather than it being filtered through calls to getAtomicValue() and updateAtomicValue(). Note, if you set this flag on a FormItem that does not have the ability to edit an opaque value (which is something that must be custom-coded) then you will get garbage in your editor, if not an outright crash.

      Note : This is an advanced setting

      Parameters:
      canEditOpaqueValues - New canEditOpaqueValues value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getCanEditOpaqueValues

      public Boolean getCanEditOpaqueValues()
      If true, indicates that this FormItem is capable of editing "opaque" values, ie, objects that are more complex than simple primitive types like numbers, strings and dates. Ordinarily, you use the SimpleType system to convert these opaque values into "atomic" values that can be edited by the built-in editors like TextItem. However, sometimes you to create a custom editor that knows how to edit a particular opaque type in a domain-specific way - for example, a composite custom FormItem that allows the user to edit both a number and a currency code, both of which are needed to make a proper monetary amount (for that particular application). When this value is set, the FormItem will manage the opaque value directly, rather than it being filtered through calls to getAtomicValue() and updateAtomicValue(). Note, if you set this flag on a FormItem that does not have the ability to edit an opaque value (which is something that must be custom-coded) then you will get garbage in your editor, if not an outright crash.
      Returns:
      Current canEditOpaqueValues value. Default value is null
    • setCanFocus

      public FormItem setCanFocus(Boolean canFocus)
      Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as a StaticTextItem will cause the item to be included in the page's tab order and respond to keyboard events.

      Note : This is an advanced setting

      Parameters:
      canFocus - New canFocus value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getCanFocus

      public Boolean getCanFocus()
      Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as a StaticTextItem will cause the item to be included in the page's tab order and respond to keyboard events.
      Returns:
      Returns true for items that can accept keyboard focus such as data items (TextItems, TextAreaItems, etc), CanvasItems with a focusable canvas, or items where canFocus was explicitly set to true. Default value is null
      See Also:
    • setCanHover

      public FormItem setCanHover(Boolean canHover)
      Indicates whether hovers can be shown for this item. When set to false, suppresses all hovers, including those for the item in general, or for its value or title.

      For finer control over suppressing hovers, see itemHover, titleHover and valueHover.

      Parameters:
      canHover - New canHover value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getCanHover

      public Boolean getCanHover()
      Indicates whether hovers can be shown for this item. When set to false, suppresses all hovers, including those for the item in general, or for its value or title.

      For finer control over suppressing hovers, see itemHover, titleHover and valueHover.

      Returns:
      Current canHover value. Default value is null
      See Also:
    • setCanSelectText

      public FormItem setCanSelectText(boolean canSelectText)
      For items showing a text value, should the user be able to select the text in this item?

      For canEdit:false items, see readOnlyCanSelectText

      Parameters:
      canSelectText - New canSelectText value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
    • getCanSelectText

      public boolean getCanSelectText()
      For items showing a text value, should the user be able to select the text in this item?

      For canEdit:false items, see readOnlyCanSelectText

      Returns:
      Current canSelectText value. Default value is true
    • setCanTabToIcons

      public FormItem setCanTabToIcons(Boolean canTabToIcons)
      Should this item's icons and picker icon be included in the page's tab order by default? If not explicitly set, this property will be derived from DynamicForm.canTabToIcons.

      Developers may also suppress tabbing to individual icons by setting FormItemIcon.tabIndex to -1.

      Note that if this form item has tabIndex -1, neither the form item nor the icons will be included in the page's tab order.

      Note : This is an advanced setting

      Parameters:
      canTabToIcons - New canTabToIcons value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getCanTabToIcons

      public Boolean getCanTabToIcons()
      Should this item's icons and picker icon be included in the page's tab order by default? If not explicitly set, this property will be derived from DynamicForm.canTabToIcons.

      Developers may also suppress tabbing to individual icons by setting FormItemIcon.tabIndex to -1.

      Note that if this form item has tabIndex -1, neither the form item nor the icons will be included in the page's tab order.

      Returns:
      Current canTabToIcons value. Default value is null
    • setCellHeight

      public FormItem setCellHeight(Integer cellHeight)
      If specified, this property will govern the height of the cell in which this form item is rendered. Will not apply when the containing DynamicForm sets itemLayout:"absolute".
      Parameters:
      cellHeight - New cellHeight value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getCellHeight

      public Integer getCellHeight()
      If specified, this property will govern the height of the cell in which this form item is rendered. Will not apply when the containing DynamicForm sets itemLayout:"absolute".
      Returns:
      Current cellHeight value. Default value is null
      See Also:
    • setCellStyle

      public FormItem setCellStyle(String cellStyle)
      CSS style applied to the form item as a whole, including the text element, any icons, and any hint text for the item. Applied to the cell containing the form item.

      See FormItemStyling for an overview of formItem styling, and the CompoundFormItem_skinning discussion for special skinning considerations.

      If this method is called after the component has been drawn/initialized: Setter for cellStyle.

      Parameters:
      cellStyle - the new cellStyle value. Default value is "formCell"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getCellStyle

      public String getCellStyle()
      CSS style applied to the form item as a whole, including the text element, any icons, and any hint text for the item. Applied to the cell containing the form item.

      See FormItemStyling for an overview of formItem styling, and the CompoundFormItem_skinning discussion for special skinning considerations.

      Returns:
      Current cellStyle value. Default value is "formCell"
      See Also:
    • setChangeOnKeypress

      public FormItem setChangeOnKeypress(Boolean changeOnKeypress)
      Should this form item fire its change handler (and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing (and the value stored) on every keypress.

      Note: If false, the value returned by getValue will not reflect the value displayed in the form item element as long as focus is in the form item element.

      Parameters:
      changeOnKeypress - New changeOnKeypress value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
    • getChangeOnKeypress

      public Boolean getChangeOnKeypress()
      Should this form item fire its change handler (and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing (and the value stored) on every keypress.

      Note: If false, the value returned by getValue will not reflect the value displayed in the form item element as long as focus is in the form item element.

      Returns:
      Current changeOnKeypress value. Default value is true
    • setClipStaticValue

      public FormItem setClipStaticValue(Boolean clipStaticValue)
      If this item is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC, should the item value be clipped if it overflows the specified size of the item? If set, overrides the form-level DynamicForm.clipStaticValue default.
      Parameters:
      clipStaticValue - New clipStaticValue value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getClipStaticValue

      public Boolean getClipStaticValue()
      If this item is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC, should the item value be clipped if it overflows the specified size of the item? If set, overrides the form-level DynamicForm.clipStaticValue default.
      Returns:
      Current clipStaticValue value. Default value is null
      See Also:
    • setClipTitle

      public FormItem setClipTitle(Boolean clipTitle)
      If the title for this form item is showing, and is too large for the available space should the title be clipped?

      Null by default - if set to true or false, overrides DynamicForm.clipItemTitles.

      Parameters:
      clipTitle - New clipTitle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getClipTitle

      public Boolean getClipTitle()
      If the title for this form item is showing, and is too large for the available space should the title be clipped?

      Null by default - if set to true or false, overrides DynamicForm.clipItemTitles.

      Returns:
      Current clipTitle value. Default value is null
    • getContainerWidget

      public Canvas getContainerWidget()
      A Read-Only pointer to the Smart GWT canvas that holds this form item. In most cases this will be the DynamicForm containing the item but in some cases editable components handle writing out form items directly. An example of this is Grid Editing - when a listGrid shows per-field editors, the containerWidget for each item will be the listGrid body.

      Note that even if the containerWidget is not a DynamicForm, a DynamicForm will still exist for the item (available as form), allowing access to standard APIs such as DynamicForm.getValues()

      Returns:
      Current containerWidget value. Default value is null
    • setControlStyle

      public FormItem setControlStyle(String controlStyle)
      Base CSS class name for a form item's "control box". This is an HTML element which contains the text box and picker icon for the item.

      See alwaysShowControlBox for details on when the control box is written out.

      See FormItemStyling for an overview of formItem styling, and the CompoundFormItem_skinning discussion for special skinning considerations.

      Parameters:
      controlStyle - New controlStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getControlStyle

      public String getControlStyle()
      Base CSS class name for a form item's "control box". This is an HTML element which contains the text box and picker icon for the item.

      See alwaysShowControlBox for details on when the control box is written out.

      See FormItemStyling for an overview of formItem styling, and the CompoundFormItem_skinning discussion for special skinning considerations.

      Returns:
      Current controlStyle value. Default value is null
      See Also:
    • setCriteriaField

      public FormItem setCriteriaField(String criteriaField)
      When using operator, the name of the DataSource field for the Criterion this FormItem generates. If not specified, defaults to name.

      Generally, because criteriaField defaults to item.name, you don't need to specify it. However, if more than one FormItem specifies criteria for the same DataSource field, they will need unique values for name but should set criteriaField to the name of DataSource field they both target.

      For example, if two DateItems are used to provide a min and max date for a single field called "joinDate", set criteriaField to "joinDate" on both fields but give the fields distinct names (eg "minDate" and "maxDate") and use those names for any programmatic access, such as DynamicForm.setValue().

      Parameters:
      criteriaField - New criteriaField value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getCriteriaField

      public String getCriteriaField()
      When using operator, the name of the DataSource field for the Criterion this FormItem generates. If not specified, defaults to name.

      Generally, because criteriaField defaults to item.name, you don't need to specify it. However, if more than one FormItem specifies criteria for the same DataSource field, they will need unique values for name but should set criteriaField to the name of DataSource field they both target.

      For example, if two DateItems are used to provide a min and max date for a single field called "joinDate", set criteriaField to "joinDate" on both fields but give the fields distinct names (eg "minDate" and "maxDate") and use those names for any programmatic access, such as DynamicForm.setValue().

      Returns:
      Current criteriaField value. Default value is null
      See Also:
    • setDataPath

      public FormItem setDataPath(String dataPath)
      dataPath for this item. Allows the user to edit details nested data structures in a flat set of form fields

      NOTE: the dataPath feature is intended to help certain legacy architectures, such as systems that work in terms of exchanging large messages with several different entity types in one message, and are incapable of providing separate access to each entity type.
      See the DataPath overview for more information.

      Note that an item must have a valid dataPath or name in order for its value to be validated and/or saved.

      Parameters:
      dataPath - New dataPath value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDataPath

      public String getDataPath()
      dataPath for this item. Allows the user to edit details nested data structures in a flat set of form fields

      NOTE: the dataPath feature is intended to help certain legacy architectures, such as systems that work in terms of exchanging large messages with several different entity types in one message, and are incapable of providing separate access to each entity type.
      See the DataPath overview for more information.

      Note that an item must have a valid dataPath or name in order for its value to be validated and/or saved.

      Returns:
      Return the dataPath for the this formItem. Default value is null
      See Also:
    • setDateFormatter

      public FormItem setDateFormatter(DateDisplayFormat dateFormatter)
      Display format to use for date type values within this formItem.

      Note that Fields of type "date", "datetime" or "time" will be edited using a DateItem or TimeItem by default, but this can be overridden - for canEdit:false fields, a StaticTextItem is used by default, and the developer can always specify a custom editorType as well as data type.

      The timeFormatter may also be used to format underlying Date values as times (ommitting the date part entirely). If both dateFormatter and timeFormatter are specified on an item, for fields specified as type "time" the timeFormatter will be used, otherwise the dateFormatter

      If item.dateFormatter and item.timeFormatter is unspecified, date display format may be defined at the component level via DynamicForm.dateFormatter, or for fields of type "datetime" DynamicForm.datetimeFormatter. Otherwise the default is to use the system-wide default short date format, configured via DateUtil.setShortDisplayFormat(). Specify any valid DateDisplayFormat to change the format used by this item.

      Note that if this is a freeform editable field, such a TextItem, with type specified as "date" or "datetime" the system will automatically attempt to parse user entered values back to a Date value, assuming the entered string matches the date format for the field. Developers may further customize this via an explicit inputFormat or via entirely custom setEditorValueFormatter and setEditorValueParser methods.

      Note : This is an advanced setting

      Parameters:
      dateFormatter - New dateFormatter value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDateFormatter

      public DateDisplayFormat getDateFormatter()
      Display format to use for date type values within this formItem.

      Note that Fields of type "date", "datetime" or "time" will be edited using a DateItem or TimeItem by default, but this can be overridden - for canEdit:false fields, a StaticTextItem is used by default, and the developer can always specify a custom editorType as well as data type.

      The timeFormatter may also be used to format underlying Date values as times (ommitting the date part entirely). If both dateFormatter and timeFormatter are specified on an item, for fields specified as type "time" the timeFormatter will be used, otherwise the dateFormatter

      If item.dateFormatter and item.timeFormatter is unspecified, date display format may be defined at the component level via DynamicForm.dateFormatter, or for fields of type "datetime" DynamicForm.datetimeFormatter. Otherwise the default is to use the system-wide default short date format, configured via DateUtil.setShortDisplayFormat(). Specify any valid DateDisplayFormat to change the format used by this item.

      Note that if this is a freeform editable field, such a TextItem, with type specified as "date" or "datetime" the system will automatically attempt to parse user entered values back to a Date value, assuming the entered string matches the date format for the field. Developers may further customize this via an explicit inputFormat or via entirely custom setEditorValueFormatter and setEditorValueParser methods.

      Returns:
      Current dateFormatter value. Default value is null
      See Also:
    • setDecimalPad

      public FormItem setDecimalPad(Integer decimalPad)
      Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.

      For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if decimalPad is 2.

      The original unpadded value is always shown when the value is edited.

      Parameters:
      decimalPad - New decimalPad value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDecimalPad

      public Integer getDecimalPad()
      Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.

      For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if decimalPad is 2.

      The original unpadded value is always shown when the value is edited.

      Returns:
      Current decimalPad value. Default value is null
      See Also:
    • setDecimalPrecision

      public FormItem setDecimalPrecision(Integer decimalPrecision)
      Applies only to fields of type "float" and affects how many significant digits are shown.

      For example, with decimalPrecision 3, if the field value is 343.672677, 343.673 is shown.

      If the value is 125.2, 125.2 is shown - decimalPrecision will not cause extra zeros to be added. Use DataSourceField.decimalPad for this.

      A number is always shown with its original precision when edited.

      Parameters:
      decimalPrecision - New decimalPrecision value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDecimalPrecision

      public Integer getDecimalPrecision()
      Applies only to fields of type "float" and affects how many significant digits are shown.

      For example, with decimalPrecision 3, if the field value is 343.672677, 343.673 is shown.

      If the value is 125.2, 125.2 is shown - decimalPrecision will not cause extra zeros to be added. Use DataSourceField.decimalPad for this.

      A number is always shown with its original precision when edited.

      Returns:
      Current decimalPrecision value. Default value is null
      See Also:
    • setDefaultIconSrc

      public FormItem setDefaultIconSrc(String defaultIconSrc)
      Default icon image source. Specify as the partial URL to an image, relative to the imgDir of this component. To specify image source for a specific icon use the icon.src property.
      If this item is drawn in the disabled state, the url will be modified by adding "_Disabled" to get a disabled state image for the icon. If icon.showOver is true, this url will be modified by adding "_Over" to get an over state image for the icon.

      Spriting can be used for this image, by setting this property to a SCSpriteConfig formatted string.

      Note : This is an advanced setting

      Parameters:
      defaultIconSrc - New defaultIconSrc value. Default value is "[SKIN]/DynamicForm/default_formItem_icon.gif"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDefaultIconSrc

      public String getDefaultIconSrc()
      Default icon image source. Specify as the partial URL to an image, relative to the imgDir of this component. To specify image source for a specific icon use the icon.src property.
      If this item is drawn in the disabled state, the url will be modified by adding "_Disabled" to get a disabled state image for the icon. If icon.showOver is true, this url will be modified by adding "_Over" to get an over state image for the icon.

      Spriting can be used for this image, by setting this property to a SCSpriteConfig formatted string.

      Returns:
      Current defaultIconSrc value. Default value is "[SKIN]/DynamicForm/default_formItem_icon.gif"
      See Also:
    • setDefaultOperator

      public FormItem setDefaultOperator(OperatorId defaultOperator)
      The default search-operator for this item when it or its form allow filter-expressions.
      Parameters:
      defaultOperator - New defaultOperator value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDefaultOperator

      public OperatorId getDefaultOperator()
      The default search-operator for this item when it or its form allow filter-expressions.
      Returns:
      Current defaultOperator value. Default value is null
      See Also:
    • getDefaultValue

      public Object getDefaultValue()
      Value used when no value is provided for this item. Note that whenever this item's value is cleared programmatically (for example via item.clearValue() or item.setValue(null)), it will be reverted to the defaultValue.

      Developers should use the DynamicForm.values object if their intention is to provide an initial value for a field in a form rather than a value to use in place of null.

      Developers looking to provide a 'hint' or placeholder value for an empty item may wish to use hint (possibly in conjunction with TextItem.showHintInField), or prompt.

      Note: Some items provide a user interface allowing the user to explicitly clear them - for example a standard TextItem. If such an item has a defaultValue specified, and the user explicitly clears that value, the value of the item will be (correctly) reported as null, and will remain null over form item redraw()s. However any programmatic call to set the value to null (including, but not limited to item.clearValue(), item.setValue(null), dynamicForm.setValues(...) with a null value for this field, etc) will reset the item value to its default.

      Returns:
      Current defaultValue value. Default value is null
      See Also:
    • getDestroyed

      public Boolean getDestroyed()
      The destroyed attribute will be set to true if this item has been destroyed() Note that FormItem lifecycle is managed by the DynamicForm itself. FormItem instances are created and destroyed automatically when new fields are added to the form.
      Returns:
      Current destroyed value. Default value is null
    • setDisabled

      public FormItem setDisabled(Boolean disabled)
      Whether this item is disabled. Can be updated at runtime via the setDisabled() method. Note that if the widget containing this formItem is disabled, the formItem will behave in a disabled manner regardless of the setting of the item.disabled property.

      Note that not all items can be disabled, and not all browsers show an obvious disabled style for native form elements.

      If this method is called after the component has been drawn/initialized: Set this item to be enabled or disabled at runtime.

      Parameters:
      disabled - true if this item should be disabled. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • setDisabledHover

      public FormItem setDisabledHover(String disabledHover)
      This text is shown as a tooltip prompt when the cursor hovers over this item and the item is disabled or read-only with readOnlyDisplay:disabled.

      You can also override itemHoverHTML on the item to show a custom hover, whether or not the item is disabled.

      Note that when the form is disabled, or when this item suppresses hovers, nothing will be shown.

      Parameters:
      disabledHover - New disabledHover value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDisabledHover

      public String getDisabledHover()
      This text is shown as a tooltip prompt when the cursor hovers over this item and the item is disabled or read-only with readOnlyDisplay:disabled.

      You can also override itemHoverHTML on the item to show a custom hover, whether or not the item is disabled.

      Note that when the form is disabled, or when this item suppresses hovers, nothing will be shown.

      Returns:
      Current disabledHover value. Default value is null
      See Also:
    • setDisableIconsOnReadOnly

      public FormItem setDisableIconsOnReadOnly(Boolean disableIconsOnReadOnly)
      If canEdit is set to false, should icons be disabled by default?

      This may also be specified at the icon level. See FormItemIcon.disableOnReadOnly.

      Parameters:
      disableIconsOnReadOnly - New disableIconsOnReadOnly value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
    • getDisableIconsOnReadOnly

      public Boolean getDisableIconsOnReadOnly()
      If canEdit is set to false, should icons be disabled by default?

      This may also be specified at the icon level. See FormItemIcon.disableOnReadOnly.

      Returns:
      Current disableIconsOnReadOnly value. Default value is true
    • setDisplayField

      public FormItem setDisplayField(String displayField)
      If set, this item will display a value from another field to the user instead of showing the underlying data value for the field name.

      This property is used in two ways:

      The item will display the displayField value from the record currently being edited if useLocalDisplayFieldValue is true, (or if unset and the conditions outlined in the documentation for that property are met).

      If this field has an optionDataSource, this property is used by default to identify which value to use as a display value in records from this related dataSource. In this usage the specified displayField must be explicitly defined in the optionDataSource to be used - see getDisplayFieldName() for more on this behavior.
      If not using local display values, the display value for this item will be derived by performing a fetch against the option dataSource to find a record where the value field matches this item's value, and use the displayField value from that record.
      In addition to this, PickList-based form items that provide a list of possible options such as the SelectItem or ComboBoxItem will show the displayField values to the user by default, allowing them to choose a new data value (see valueField) from a list of user-friendly display values.

      This essentially allows the specified optionDataSource to be used as a server based valueMap.

      If local display values are being used and storeDisplayValues is true, selecting a new value will update both the value for this field and the associated display-field value on the record being edited.

      Note: Developers may specify the foreignDisplayField property in addition to displayField. This is useful for cases where the display field name in the local dataSource differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField for more on this.
      If a foreignDisplayField is specified, as with just displayField, if local display values are being used and storeDisplayValues is true, when the user chooses a value the associated display-field value on the record being edited will be updated. In this case it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always expected to be set to the equivalent field in the related dataSources.
      Developers looking to display some other arbitrary field(s) from the related dataSource during editing should consider using custom PickList.pickListFields instead of setting a foreignDisplayField.

      Note that if optionDataSource is set and no valid display field is specified, getDisplayFieldName() will return the dataSource title field by default.

      If a displayField is specified for a freeform text based item (such as a ComboBoxItem), any user-entered value will be treated as a display value. In this scenario, items will derive the data value for the item from the first record where the displayField value matches the user-entered value. To avoid ambiguity, developers may wish to avoid this usage if display values are not unique.

      Parameters:
      displayField - New displayField value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getDisplayField

      public String getDisplayField()
      If set, this item will display a value from another field to the user instead of showing the underlying data value for the field name.

      This property is used in two ways:

      The item will display the displayField value from the record currently being edited if useLocalDisplayFieldValue is true, (or if unset and the conditions outlined in the documentation for that property are met).

      If this field has an optionDataSource, this property is used by default to identify which value to use as a display value in records from this related dataSource. In this usage the specified displayField must be explicitly defined in the optionDataSource to be used - see getDisplayFieldName() for more on this behavior.
      If not using local display values, the display value for this item will be derived by performing a fetch against the option dataSource to find a record where the value field matches this item's value, and use the displayField value from that record.
      In addition to this, PickList-based form items that provide a list of possible options such as the SelectItem or ComboBoxItem will show the displayField values to the user by default, allowing them to choose a new data value (see valueField) from a list of user-friendly display values.

      This essentially allows the specified optionDataSource to be used as a server based valueMap.

      If local display values are being used and storeDisplayValues is true, selecting a new value will update both the value for this field and the associated display-field value on the record being edited.

      Note: Developers may specify the foreignDisplayField property in addition to displayField. This is useful for cases where the display field name in the local dataSource differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField for more on this.
      If a foreignDisplayField is specified, as with just displayField, if local display values are being used and storeDisplayValues is true, when the user chooses a value the associated display-field value on the record being edited will be updated. In this case it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always expected to be set to the equivalent field in the related dataSources.
      Developers looking to display some other arbitrary field(s) from the related dataSource during editing should consider using custom PickList.pickListFields instead of setting a foreignDisplayField.

      Note that if optionDataSource is set and no valid display field is specified, getDisplayFieldName() will return the dataSource title field by default.

      If a displayField is specified for a freeform text based item (such as a ComboBoxItem), any user-entered value will be treated as a display value. In this scenario, items will derive the data value for the item from the first record where the displayField value matches the user-entered value. To avoid ambiguity, developers may wish to avoid this usage if display values are not unique.

      Returns:
      Returns the displayField for this item.

      Behavior varies based on the configuration of this item, as follows:

      • If this item has an optionDataSource and an explicit foreignDisplayField is specified, this will be returned.
      • Otherwise if an explicit displayField is specified it will be returned by default. If the displayField was specified on the underlying dataSource field, and no matching field is present in the optionDataSource for the item, we avoid returning the specified displayField value and instead return the title field of the option DataSource. We do this to avoid confusion for the case where the displayField is intended as a display-field value for showing another field value within the same record in the underlying dataSource only.
      • If no explicit foreignDisplay or displayField specification was found, and the valueField for this item is hidden in the optionDataSource, this method will return the title field for the optionDataSource.
      . Default value is null
      See Also:
    • setEditPendingCSSText

      public FormItem setEditPendingCSSText(String editPendingCSSText)
      Custom CSS text to be applied to cells with pending edits that have not yet been submitted.

      Note : This is an advanced setting

      Parameters:
      editPendingCSSText - New editPendingCSSText value. Default value is "color:#0066CC;"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getEditPendingCSSText

      public String getEditPendingCSSText()
      Custom CSS text to be applied to cells with pending edits that have not yet been submitted.
      Returns:
      Current editPendingCSSText value. Default value is "color:#0066CC;"
      See Also:
    • setEditProxyConstructor

      public FormItem setEditProxyConstructor(String editProxyConstructor)
      Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
      Parameters:
      editProxyConstructor - New editProxyConstructor value. Default value is "FormItemEditProxy"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getEditProxyConstructor

      public String getEditProxyConstructor()
      Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
      Returns:
      Current editProxyConstructor value. Default value is "FormItemEditProxy"
      See Also:
    • setEmptyDisplayValue

      public FormItem setEmptyDisplayValue(String emptyDisplayValue)
      Text to display when this form item has a null or undefined value.

      If the formItem has a databound pickList, and its displayField or valueField (if the former isn't set) has an undefined emptyCellValue setting, that field's emptyCellValue will automatically be set to the emptyDisplayValue.

      Parameters:
      emptyDisplayValue - New emptyDisplayValue value. Default value is ""
      Returns:
      FormItem instance, for chaining setter calls
    • getEmptyDisplayValue

      public String getEmptyDisplayValue()
      Text to display when this form item has a null or undefined value.

      If the formItem has a databound pickList, and its displayField or valueField (if the former isn't set) has an undefined emptyCellValue setting, that field's emptyCellValue will automatically be set to the emptyDisplayValue.

      Returns:
      Current emptyDisplayValue value. Default value is ""
    • setEmptyValueIcon

      public FormItem setEmptyValueIcon(String emptyValueIcon)
      This property allows the developer to specify an icon to display when this item has no value. It is configured in the same way as any other valueIcon (see valueIcons)
      Parameters:
      emptyValueIcon - New emptyValueIcon value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getEmptyValueIcon

      public String getEmptyValueIcon()
      This property allows the developer to specify an icon to display when this item has no value. It is configured in the same way as any other valueIcon (see valueIcons)
      Returns:
      Current emptyValueIcon value. Default value is null
    • setEndRow

      public FormItem setEndRow(Boolean endRow)
      Whether this item should end the row it's in in the form layout
      Parameters:
      endRow - New endRow value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getEndRow

      public Boolean getEndRow()
      Whether this item should end the row it's in in the form layout
      Returns:
      Current endRow value. Default value is false
      See Also:
    • setErrorIconHeight

      public FormItem setErrorIconHeight(int errorIconHeight)
      Height of the error icon, if we're showing icons when validation errors occur.
      Parameters:
      errorIconHeight - New errorIconHeight value. Default value is 16
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getErrorIconHeight

      public int getErrorIconHeight()
      Height of the error icon, if we're showing icons when validation errors occur.
      Returns:
      Current errorIconHeight value. Default value is 16
      See Also:
    • setErrorIconProperties

      public FormItem setErrorIconProperties(FormItemIcon errorIconProperties)
      Icon-properties to apply to the error-icon when showErrorIconInline is true.

      Note : This is an advanced setting

      Parameters:
      errorIconProperties - New errorIconProperties value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getErrorIconProperties

      public FormItemIcon getErrorIconProperties()
      Icon-properties to apply to the error-icon when showErrorIconInline is true.
      Returns:
      Current errorIconProperties value. Default value is null
    • setErrorIconSrc

      public FormItem setErrorIconSrc(String errorIconSrc)
      URL of the image to show as an error icon, if we're showing icons when validation errors occur.
      Parameters:
      errorIconSrc - New errorIconSrc value. Default value is "[SKIN]/DynamicForm/validation_error_icon.png"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getErrorIconSrc

      public String getErrorIconSrc()
      URL of the image to show as an error icon, if we're showing icons when validation errors occur.
      Returns:
      Current errorIconSrc value. Default value is "[SKIN]/DynamicForm/validation_error_icon.png"
      See Also:
    • setErrorIconWidth

      public FormItem setErrorIconWidth(int errorIconWidth)
      Height of the error icon, if we're showing icons when validation errors occur.
      Parameters:
      errorIconWidth - New errorIconWidth value. Default value is 16
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getErrorIconWidth

      public int getErrorIconWidth()
      Height of the error icon, if we're showing icons when validation errors occur.
      Returns:
      Current errorIconWidth value. Default value is 16
      See Also:
    • setErrorMessageWidth

      public FormItem setErrorMessageWidth(int errorMessageWidth)
      When DynamicForm.showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon.
      Parameters:
      errorMessageWidth - New errorMessageWidth value. Default value is 80
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getErrorMessageWidth

      public int getErrorMessageWidth()
      When DynamicForm.showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon.
      Returns:
      Current errorMessageWidth value. Default value is 80
      See Also:
    • setEscapeHTML

      public FormItem setEscapeHTML(Boolean escapeHTML)
      Controls whether HTML item value(s) should be rendered or shown as HTML source.

      This property is supported by specific formItem sub-types (e.g. TextItem), and has no effect in others. To understand the effects, look at the documentation for the specific formItem sub-type in question.

      Overrides:
      setEscapeHTML in class Field
      Parameters:
      escapeHTML - New escapeHTML value. Default value is varies
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getEscapeHTML

      public Boolean getEscapeHTML()
      Controls whether HTML item value(s) should be rendered or shown as HTML source.

      This property is supported by specific formItem sub-types (e.g. TextItem), and has no effect in others. To understand the effects, look at the documentation for the specific formItem sub-type in question.

      Overrides:
      getEscapeHTML in class Field
      Returns:
      Current escapeHTML value. Default value is varies
      See Also:
    • setExportFormat

      public FormItem setExportFormat(String exportFormat)
      FormatString used during exports for numeric or date formatting. See DataSourceField.exportFormat.
      Parameters:
      exportFormat - New exportFormat value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getExportFormat

      public String getExportFormat()
      FormatString used during exports for numeric or date formatting. See DataSourceField.exportFormat.
      Returns:
      Current exportFormat value. Default value is null
      See Also:
    • setFetchMissingValues

      public FormItem setFetchMissingValues(Boolean fetchMissingValues)
      If this form item has a specified optionDataSource, should the item ever perform a fetch against this dataSource to retrieve the related record.

      The fetch occurs if the item value is non null on initial draw of the form or whenever setValue() is called. Once the fetch completes, the returned record is available via the getSelectedRecord() api.

      By default, a fetch will only occur if displayField is specified, and the item does not have an explicit valueMap containing the data value as a key.
      However you can also set alwaysFetchMissingValues to have a fetch occur even if no displayField is specified. This ensures getSelectedRecord() will return a record if possible - useful for custom formatter functions, etc.

      Note - for efficiency we cache the associated record once a fetch has been performed, meaning if the value changes, then reverts to a previously seen value, we do not kick off an additional fetch to pick up the display value for the previously seen data value. If necessary this cache may be explicitly invalidated via a call to invalidateDisplayValueCache()

      Note : This is an advanced setting

      Parameters:
      fetchMissingValues - New fetchMissingValues value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getFetchMissingValues

      public Boolean getFetchMissingValues()
      If this form item has a specified optionDataSource, should the item ever perform a fetch against this dataSource to retrieve the related record.

      The fetch occurs if the item value is non null on initial draw of the form or whenever setValue() is called. Once the fetch completes, the returned record is available via the getSelectedRecord() api.

      By default, a fetch will only occur if displayField is specified, and the item does not have an explicit valueMap containing the data value as a key.
      However you can also set alwaysFetchMissingValues to have a fetch occur even if no displayField is specified. This ensures getSelectedRecord() will return a record if possible - useful for custom formatter functions, etc.

      Note - for efficiency we cache the associated record once a fetch has been performed, meaning if the value changes, then reverts to a previously seen value, we do not kick off an additional fetch to pick up the display value for the previously seen data value. If necessary this cache may be explicitly invalidated via a call to invalidateDisplayValueCache()

      Returns:
      Current fetchMissingValues value. Default value is true
      See Also:
    • setFilterLocally

      public FormItem setFilterLocally(Boolean filterLocally)
      If this form item is mapping data values to a display value by fetching records from a dataSource (see optionDataSource, displayField and fetchMissingValues), setting this property to true ensures that when the form item value is set, entire data-set from the dataSource is loaded at once and used as a valueMap, rather than just loading the display value for the current value. This avoids the need to perform fetches each time setValue() is called with a new value.

      See also PickList.filterLocally for behavior on form items such as SelectItems that show pick-lists.

      Note : This is an advanced setting

      Parameters:
      filterLocally - New filterLocally value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getFilterLocally

      public Boolean getFilterLocally()
      If this form item is mapping data values to a display value by fetching records from a dataSource (see optionDataSource, displayField and fetchMissingValues), setting this property to true ensures that when the form item value is set, entire data-set from the dataSource is loaded at once and used as a valueMap, rather than just loading the display value for the current value. This avoids the need to perform fetches each time setValue() is called with a new value.

      See also PickList.filterLocally for behavior on form items such as SelectItems that show pick-lists.

      Returns:
      Current filterLocally value. Default value is null
    • setForeignDisplayField

      public FormItem setForeignDisplayField(String foreignDisplayField)
      For items with an optionDataSource, this property specifies an explicit display field for records within the option dataSource. Typically this property will be set in conjunction with displayField in the case where the name of the displayField within the record being edited differs from the displayField in the optionDataSource.

      See DataSourceField.foreignDisplayField for additional details.

      Parameters:
      foreignDisplayField - New foreignDisplayField value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getForeignDisplayField

      public String getForeignDisplayField()
      For items with an optionDataSource, this property specifies an explicit display field for records within the option dataSource. Typically this property will be set in conjunction with displayField in the case where the name of the displayField within the record being edited differs from the displayField in the optionDataSource.

      See DataSourceField.foreignDisplayField for additional details.

      Returns:
      Current foreignDisplayField value. Default value is null
      See Also:
    • setFormat

      public FormItem setFormat(String format)
      FormatString for numeric or date formatting. See DataSourceField.format.
      Parameters:
      format - New format value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getFormat

      public String getFormat()
      FormatString for numeric or date formatting. See DataSourceField.format.
      Returns:
      Current format value. Default value is null
      See Also:
    • setFormula

      public FormItem setFormula(UserFormula formula)
      Formula to be used to calculate the numeric value of this FormItem. For a field of type "text" (or subtypes) textFormula is used instead.

      Available fields for use in the formula are the current rule context. The formula is re-evaluated every time the rule context changes.

      Values calculated by the formula will always replace the current value of a non-editable field. For an editable field, the current value will be replaced if the end user has not changed the value since the last time it was computed by the formula, or if the value of the field is invalid according to declared validators.

      Note: A FormItem using a formula must have a name defined. shouldSaveValue can be set to false to prevent the formula field from storing the calculated value into the form's values.

      Parameters:
      formula - New formula value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getFormula

      public UserFormula getFormula()
      Formula to be used to calculate the numeric value of this FormItem. For a field of type "text" (or subtypes) textFormula is used instead.

      Available fields for use in the formula are the current rule context. The formula is re-evaluated every time the rule context changes.

      Values calculated by the formula will always replace the current value of a non-editable field. For an editable field, the current value will be replaced if the end user has not changed the value since the last time it was computed by the formula, or if the value of the field is invalid according to declared validators.

      Note: A FormItem using a formula must have a name defined. shouldSaveValue can be set to false to prevent the formula field from storing the calculated value into the form's values.

      Returns:
      Current formula value. Default value is null
      See Also:
    • setGlobalTabIndex

      public FormItem setGlobalTabIndex(Integer globalTabIndex)
      TabIndex for the form item within the page. Takes precedence over any local tab index specified as item.tabIndex.

      Use of this API is extremely advanced and essentially implies taking over management of tab index assignment for all components on the page.

      Note : This is an advanced setting

      Parameters:
      globalTabIndex - New globalTabIndex value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getGlobalTabIndex

      public Integer getGlobalTabIndex()
      TabIndex for the form item within the page. Takes precedence over any local tab index specified as item.tabIndex.

      Use of this API is extremely advanced and essentially implies taking over management of tab index assignment for all components on the page.

      Returns:
      Current globalTabIndex value. Default value is null
      See Also:
    • setHeight

      public FormItem setHeight(int height)
      Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

      If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

      For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
      Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
      Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

      Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property staticHeight is used instead.

      Parameters:
      height - New height value. Default value is 20
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHeight

      public int getHeight()
      Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

      If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

      For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
      Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
      Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

      Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property staticHeight is used instead.

      Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

      Returns:
      Current height value. Default value is 20
      See Also:
    • setHeight

      public FormItem setHeight(String height)
      Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

      If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

      For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
      Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
      Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

      Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property staticHeight is used instead.

      Parameters:
      height - New height value. Default value is 20
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHeightAsString

      public String getHeightAsString()
      Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

      If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

      For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
      Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
      Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

      Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property staticHeight is used instead.

      Returns:
      Current height value. Default value is 20
      See Also:
    • setHidden

      public FormItem setHidden(Boolean hidden)
      Should this form item be hidden? Setting this property to true on an item configuration will have the same effect as having a showIf() implementation which returns false.

      Note this differs slightly from DataSourceField.hidden. That property will cause the field in question to be omitted entirely from databound components by default. A dataSourceField with hidden set to true can still be displayed in a DynamicForm either by being explicitly included in the specified items array, or by having DataBoundComponent.showHiddenFields set to true. In this case, this property will not be inherited onto the FormItem instance, meaning the item will be visible in the form even though the hidden property was set to true on the dataSourceField configuration object.

      Parameters:
      hidden - New hidden value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getHidden

      public Boolean getHidden()
      Should this form item be hidden? Setting this property to true on an item configuration will have the same effect as having a showIf() implementation which returns false.

      Note this differs slightly from DataSourceField.hidden. That property will cause the field in question to be omitted entirely from databound components by default. A dataSourceField with hidden set to true can still be displayed in a DynamicForm either by being explicitly included in the specified items array, or by having DataBoundComponent.showHiddenFields set to true. In this case, this property will not be inherited onto the FormItem instance, meaning the item will be visible in the form even though the hidden property was set to true on the dataSourceField configuration object.

      Returns:
      Current hidden value. Default value is null
    • setHint

      public FormItem setHint(String hint)
      Specifies "hint" string to show next to the form item to indicate something to the user. This string generally appears to the right of the form item.

      If this method is called after the component has been drawn/initialized: Sets the hint for this item.
      Parameters:
      hint - new hint for the item. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHint

      public String getHint()
      Specifies "hint" string to show next to the form item to indicate something to the user. This string generally appears to the right of the form item.
      Returns:
      Current hint value. Default value is null
      See Also:
    • setHintStyle

      public FormItem setHintStyle(String hintStyle)
      CSS class for the "hint" string. For items that support TextItem.showHintInField, this only applies when showHintInField is false.

      If this method is called after the component has been drawn/initialized: Set the hintStyle for this item
      Parameters:
      hintStyle - new style for hint text. Default value is "formHint"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHintStyle

      public String getHintStyle()
      CSS class for the "hint" string. For items that support TextItem.showHintInField, this only applies when showHintInField is false.
      Returns:
      Current hintStyle value. Default value is "formHint"
      See Also:
    • setHoverAlign

      public FormItem setHoverAlign(Alignment hoverAlign)
      Text alignment for text displayed in this item's hover canvas, if shown.
      Parameters:
      hoverAlign - New hoverAlign value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverAlign

      public Alignment getHoverAlign()
      Text alignment for text displayed in this item's hover canvas, if shown.
      Returns:
      Current hoverAlign value. Default value is null
      See Also:
    • setHoverDelay

      public FormItem setHoverDelay(Integer hoverDelay)
      If specified, this is the number of milliseconds to wait between the user rolling over this form item, and triggering any hover action for it.
      If not specified this.form.itemHoverDelay will be used instead.

      Note : This is an advanced setting

      Parameters:
      hoverDelay - New hoverDelay value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getHoverDelay

      public Integer getHoverDelay()
      If specified, this is the number of milliseconds to wait between the user rolling over this form item, and triggering any hover action for it.
      If not specified this.form.itemHoverDelay will be used instead.
      Returns:
      Current hoverDelay value. Default value is null
    • setHoverFocusKey

      public FormItem setHoverFocusKey(String hoverFocusKey)
      This attribute gives users a way to pin this item's hover in place so they can interact with it (scroll it, click embedded links, etc).

      Overrides the same attribute on the parent form.

      Parameters:
      hoverFocusKey - New hoverFocusKey value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverFocusKey

      public String getHoverFocusKey()
      This attribute gives users a way to pin this item's hover in place so they can interact with it (scroll it, click embedded links, etc).

      Overrides the same attribute on the parent form.

      Returns:
      Current hoverFocusKey value. Default value is null
      See Also:
    • setHoverHeight

      public FormItem setHoverHeight(Integer hoverHeight)
      Option to specify a height for any hover shown for this item.
      Parameters:
      hoverHeight - New hoverHeight value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverHeight

      public Integer getHoverHeight()
      Option to specify a height for any hover shown for this item.
      Returns:
      Current hoverHeight value. Default value is null
      See Also:
    • setHoverHeight

      public FormItem setHoverHeight(String hoverHeight)
      Option to specify a height for any hover shown for this item.
      Parameters:
      hoverHeight - New hoverHeight value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverHeightAsString

      public String getHoverHeightAsString()
      Option to specify a height for any hover shown for this item.
      Returns:
      Current hoverHeight value. Default value is null
      See Also:
    • setHoverOpacity

      public FormItem setHoverOpacity(Integer hoverOpacity)
      Opacity for any hover shown for this item
      Parameters:
      hoverOpacity - New hoverOpacity value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverOpacity

      public Integer getHoverOpacity()
      Opacity for any hover shown for this item
      Returns:
      Current hoverOpacity value. Default value is null
      See Also:
    • setHoverPersist

      public FormItem setHoverPersist(HoverPersistMode hoverPersist)
      Allows interaction with hovers when the cursor is positioned over them.

      Overrides the same attribute on the parent form.

      Parameters:
      hoverPersist - New hoverPersist value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverPersist

      public HoverPersistMode getHoverPersist()
      Allows interaction with hovers when the cursor is positioned over them.

      Overrides the same attribute on the parent form.

      Returns:
      Current hoverPersist value. Default value is null
      See Also:
    • setHoverStyle

      public FormItem setHoverStyle(String hoverStyle)
      Explicit CSS Style for any hover shown for this item.
      Parameters:
      hoverStyle - New hoverStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverStyle

      public String getHoverStyle()
      Explicit CSS Style for any hover shown for this item.
      Returns:
      Current hoverStyle value. Default value is null
      See Also:
    • setHoverVAlign

      public FormItem setHoverVAlign(VerticalAlignment hoverVAlign)
      Vertical text alignment for text displayed in this item's hover canvas, if shown.
      Parameters:
      hoverVAlign - New hoverVAlign value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverVAlign

      public VerticalAlignment getHoverVAlign()
      Vertical text alignment for text displayed in this item's hover canvas, if shown.
      Returns:
      Current hoverVAlign value. Default value is null
      See Also:
    • setHoverWidth

      public FormItem setHoverWidth(Integer hoverWidth)
      Option to specify a width for any hover shown for this item.
      Parameters:
      hoverWidth - New hoverWidth value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverWidth

      public Integer getHoverWidth()
      Option to specify a width for any hover shown for this item.
      Returns:
      Current hoverWidth value. Default value is null
      See Also:
    • setHoverWidth

      public FormItem setHoverWidth(String hoverWidth)
      Option to specify a width for any hover shown for this item.
      Parameters:
      hoverWidth - New hoverWidth value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getHoverWidthAsString

      public String getHoverWidthAsString()
      Option to specify a width for any hover shown for this item.
      Returns:
      Current hoverWidth value. Default value is null
      See Also:
    • setIconBaseStyle

      public FormItem setIconBaseStyle(String iconBaseStyle)
      Fallback base CSS class to apply to this item's icons if they don't specify a baseStyle or provide a sprite-based src string that specifies a cssClass.
      Parameters:
      iconBaseStyle - New iconBaseStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getIconBaseStyle

      public String getIconBaseStyle()
      Fallback base CSS class to apply to this item's icons if they don't specify a baseStyle or provide a sprite-based src string that specifies a cssClass.
      Returns:
      Current iconBaseStyle value. Default value is null
      See Also:
    • setIconHeight

      public FormItem setIconHeight(int iconHeight)
      Default height for form item icons. May be overridden at the icon level by FormItemIcon.height.

      Note : This is an advanced setting

      Parameters:
      iconHeight - New iconHeight value. Default value is 20
      Returns:
      FormItem instance, for chaining setter calls
    • getIconHeight

      public int getIconHeight()
      Default height for form item icons. May be overridden at the icon level by FormItemIcon.height.
      Returns:
      Takes an icon definition object, and returns the height for that icon in px. Default value is 20
    • setIconHSpace

      public FormItem setIconHSpace(int iconHSpace)
      Horizontal space (in px) to leave between form item icons. The space appears either on the left or right of each icon. May be overridden at the icon level via FormItemIcon.hspace. Must be non-negative.
      Parameters:
      iconHSpace - New iconHSpace value. Default value is 3
      Returns:
      FormItem instance, for chaining setter calls
    • getIconHSpace

      public int getIconHSpace()
      Horizontal space (in px) to leave between form item icons. The space appears either on the left or right of each icon. May be overridden at the icon level via FormItemIcon.hspace. Must be non-negative.
      Returns:
      Current iconHSpace value. Default value is 3
    • setIconPrompt

      public FormItem setIconPrompt(String iconPrompt)
      Default prompt (and tooltip-text) for icons.

      If canHover is set to false, this prompt will not be shown.

      Note : This is an advanced setting

      Parameters:
      iconPrompt - New iconPrompt value. Default value is ""
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getIconPrompt

      public String getIconPrompt()
      Default prompt (and tooltip-text) for icons.

      If canHover is set to false, this prompt will not be shown.

      Returns:
      Current iconPrompt value. Default value is ""
      See Also:
    • setIcons

      public FormItem setIcons(FormItemIcon... icons)
      An array of descriptor objects for icons to display in a line after this form item. These icons are clickable images, often used to display some kind of helper for populating a form item.
      Parameters:
      icons - New icons value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getIcons

      public FormItemIcon[] getIcons()
      An array of descriptor objects for icons to display in a line after this form item. These icons are clickable images, often used to display some kind of helper for populating a form item.
      Returns:
      Current icons value. Default value is null
      See Also:
    • setIconVAlign

      public FormItem setIconVAlign(VerticalAlignment iconVAlign)
      How should icons be aligned vertically for this form item.

      Note : This is an advanced setting

      Parameters:
      iconVAlign - New iconVAlign value. Default value is "bottom"
      Returns:
      FormItem instance, for chaining setter calls
    • getIconVAlign

      public VerticalAlignment getIconVAlign()
      How should icons be aligned vertically for this form item.
      Returns:
      Current iconVAlign value. Default value is "bottom"
    • setIconWidth

      public FormItem setIconWidth(int iconWidth)
      Default width for form item icons. May be overridden at the icon level by FormItemIcon.width.

      Note : This is an advanced setting

      Parameters:
      iconWidth - New iconWidth value. Default value is 20
      Returns:
      FormItem instance, for chaining setter calls
    • getIconWidth

      public int getIconWidth()
      Default width for form item icons. May be overridden at the icon level by FormItemIcon.width.
      Returns:
      Takes an icon definition object, and returns the width for that icon in px. Default value is 20
    • setID

      public FormItem setID(String ID)
      Global identifier for referring to the formItem in JavaScript. The ID property is optional if you do not need to refer to the widget from JavaScript, or can refer to it indirectly (for example, via form.getItem("itemName")).

      An internal, unique ID will automatically be created upon instantiation for any formItem where one is not provided.

      Parameters:
      ID - New ID value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getID

      public String getID()
      Global identifier for referring to the formItem in JavaScript. The ID property is optional if you do not need to refer to the widget from JavaScript, or can refer to it indirectly (for example, via form.getItem("itemName")).

      An internal, unique ID will automatically be created upon instantiation for any formItem where one is not provided.

      Returns:
      Current ID value. Default value is null
      See Also:
    • setImageURLPrefix

      public FormItem setImageURLPrefix(String imageURLPrefix)
      Prefix to apply to the beginning of any valueIcons when determining the URL for the image. Will not be applied if the valueIcon URL is absolute.

      Note : This is an advanced setting

      Parameters:
      imageURLPrefix - New imageURLPrefix value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getImageURLPrefix

      public String getImageURLPrefix()
      Prefix to apply to the beginning of any valueIcons when determining the URL for the image. Will not be applied if the valueIcon URL is absolute.
      Returns:
      Current imageURLPrefix value. Default value is null
    • setImageURLSuffix

      public FormItem setImageURLSuffix(String imageURLSuffix)
      Suffix to apply to the end of any valueIcons when determining the URL for the image. A common usage would be to specify a suffix of ".gif" in which case the valueIcons property would map values to the names of images without the ".gif" extension.

      Note : This is an advanced setting

      Parameters:
      imageURLSuffix - New imageURLSuffix value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getImageURLSuffix

      public String getImageURLSuffix()
      Suffix to apply to the end of any valueIcons when determining the URL for the image. A common usage would be to specify a suffix of ".gif" in which case the valueIcons property would map values to the names of images without the ".gif" extension.
      Returns:
      Current imageURLSuffix value. Default value is null
    • setImplicitSave

      public FormItem setImplicitSave(Boolean implicitSave)
      When true, indicates that changes to this item will cause an automatic save on a delay, as well as when the entire form is submitted. If implicitSaveOnBlur is set to true on either this formItem or it's form, changes will also be automatically saved immediately on editorExit.
      Parameters:
      implicitSave - New implicitSave value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getImplicitSave

      public Boolean getImplicitSave()
      When true, indicates that changes to this item will cause an automatic save on a delay, as well as when the entire form is submitted. If implicitSaveOnBlur is set to true on either this formItem or it's form, changes will also be automatically saved immediately on editorExit.
      Returns:
      Current implicitSave value. Default value is false
    • setImplicitSaveOnBlur

      public FormItem setImplicitSaveOnBlur(Boolean implicitSaveOnBlur)
      If set to true, this item's value will be saved immediately when its "editorExit" handler is fired. This attribute works separately from implicitSave, which causes saves during editing, after a short delay, and when the entire form is submitted.
      Parameters:
      implicitSaveOnBlur - New implicitSaveOnBlur value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getImplicitSaveOnBlur

      public Boolean getImplicitSaveOnBlur()
      If set to true, this item's value will be saved immediately when its "editorExit" handler is fired. This attribute works separately from implicitSave, which causes saves during editing, after a short delay, and when the entire form is submitted.
      Returns:
      Current implicitSaveOnBlur value. Default value is false
    • setInputFormat

      public FormItem setInputFormat(String inputFormat)
      For fields of type "date", if this is an editable field such as a TextItem, this property allows you to specify the inputFormat applied to the item.

      Note : This is an advanced setting

      Parameters:
      inputFormat - New inputFormat value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getInputFormat

      public String getInputFormat()
      For fields of type "date", if this is an editable field such as a TextItem, this property allows you to specify the inputFormat applied to the item.
      Returns:
      Current inputFormat value. Default value is null
      See Also:
    • setLeft

      public FormItem setLeft(int left)
      Left coordinate of this item in pixels. Applies only when the containing DynamicForm sets itemLayout:"absolute".

      If this method is called after the component has been drawn/initialized: For a form with itemLayout:"absolute" only, set the left coordinate of this form item.

      Causes the form to redraw.

      Note : This is an advanced setting

      Parameters:
      left - New left value. Default value is 0
      Returns:
      FormItem instance, for chaining setter calls
    • getLeft

      public int getLeft()
      Left coordinate of this item in pixels. Applies only when the containing DynamicForm sets itemLayout:"absolute".
      Returns:
      Returns the left coordinate of this form item in pixels. Note that this method is only reliable after the item has been drawn. Default value is 0
    • setLinearColSpan

      public FormItem setLinearColSpan(int linearColSpan)
      Specifies a column span for an item in linearMode, overriding the default value of "*" in that mode.
      Parameters:
      linearColSpan - New linearColSpan value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearColSpan

      public int getLinearColSpan()
      Specifies a column span for an item in linearMode, overriding the default value of "*" in that mode.

      Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

      Returns:
      Current linearColSpan value. Default value is null
      See Also:
      • com.smartgwt.client.widgets.form.fields.FormItem#getColSpan
      • Form Layout
    • setLinearColSpan

      public FormItem setLinearColSpan(String linearColSpan)
      Specifies a column span for an item in linearMode, overriding the default value of "*" in that mode.
      Parameters:
      linearColSpan - New linearColSpan value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearColSpanAsString

      public String getLinearColSpanAsString()
      Specifies a column span for an item in linearMode, overriding the default value of "*" in that mode.
      Returns:
      Current linearColSpan value. Default value is null
      See Also:
      • com.smartgwt.client.widgets.form.fields.FormItem#getColSpan
      • Form Layout
    • setLinearEndRow

      public FormItem setLinearEndRow(int linearEndRow)
      Specifies endRow for an item in linearMode, overriding the default of true in that mode.
      Parameters:
      linearEndRow - New linearEndRow value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearEndRow

      public int getLinearEndRow()
      Specifies endRow for an item in linearMode, overriding the default of true in that mode.

      Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

      Returns:
      Current linearEndRow value. Default value is null
      See Also:
    • setLinearEndRow

      public FormItem setLinearEndRow(String linearEndRow)
      Specifies endRow for an item in linearMode, overriding the default of true in that mode.
      Parameters:
      linearEndRow - New linearEndRow value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearEndRowAsString

      public String getLinearEndRowAsString()
      Specifies endRow for an item in linearMode, overriding the default of true in that mode.
      Returns:
      Current linearEndRow value. Default value is null
      See Also:
    • setLinearStartRow

      public FormItem setLinearStartRow(int linearStartRow)
      Specifies startRow for an item in linearMode, overriding the default of false in that mode.
      Parameters:
      linearStartRow - New linearStartRow value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearStartRow

      public int getLinearStartRow()
      Specifies startRow for an item in linearMode, overriding the default of false in that mode.

      Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

      Returns:
      Current linearStartRow value. Default value is null
      See Also:
    • setLinearStartRow

      public FormItem setLinearStartRow(String linearStartRow)
      Specifies startRow for an item in linearMode, overriding the default of false in that mode.
      Parameters:
      linearStartRow - New linearStartRow value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearStartRowAsString

      public String getLinearStartRowAsString()
      Specifies startRow for an item in linearMode, overriding the default of false in that mode.
      Returns:
      Current linearStartRow value. Default value is null
      See Also:
    • setLinearWidth

      public FormItem setLinearWidth(int linearWidth)
      Specifies a width for an item in linearMode, overriding the default width of "*" in that mode.
      Parameters:
      linearWidth - New linearWidth value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearWidth

      public int getLinearWidth()
      Specifies a width for an item in linearMode, overriding the default width of "*" in that mode.

      Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

      Returns:
      Current linearWidth value. Default value is null
      See Also:
    • setLinearWidth

      public FormItem setLinearWidth(String linearWidth)
      Specifies a width for an item in linearMode, overriding the default width of "*" in that mode.
      Parameters:
      linearWidth - New linearWidth value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLinearWidthAsString

      public String getLinearWidthAsString()
      Specifies a width for an item in linearMode, overriding the default width of "*" in that mode.
      Returns:
      Current linearWidth value. Default value is null
      See Also:
    • setLoadingDisplayValue

      public FormItem setLoadingDisplayValue(String loadingDisplayValue)
      Value shown in field when fetchMissingValues is active and a fetch is pending. The field is read-only while a fetch is pending.

      Set to null to show actual value until display value is loaded.

      Parameters:
      loadingDisplayValue - New loadingDisplayValue value. Default value is "Loading..."
      Returns:
      FormItem instance, for chaining setter calls
    • getLoadingDisplayValue

      public String getLoadingDisplayValue()
      Value shown in field when fetchMissingValues is active and a fetch is pending. The field is read-only while a fetch is pending.

      Set to null to show actual value until display value is loaded.

      Returns:
      Current loadingDisplayValue value. Default value is "Loading..."
    • setLocateItemBy

      public FormItem setLocateItemBy(String locateItemBy)
      When AutoTest.getElement() is used to parse locator strings generated by AutoTest.getLocator() for this form item, should the item be identified? If the locator has a specified name, it is considered to definitely locate the item and no fallback approach will be used.

      Otherwise, the following options are available:

      • "title" use the title as an identifier within this form
      • "value" use the value of the item to identify it (often used for items with a static defaultValue such as HeaderItems
      • "index" use the index within the form's items array.

      If unset, and the locator has no specified name, default behavior is to identify by title (if available), then value (if available), otherwise by index.

      Note : This is an advanced setting

      Parameters:
      locateItemBy - New locateItemBy value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getLocateItemBy

      public String getLocateItemBy()
      When AutoTest.getElement() is used to parse locator strings generated by AutoTest.getLocator() for this form item, should the item be identified? If the locator has a specified name, it is considered to definitely locate the item and no fallback approach will be used.

      Otherwise, the following options are available:

      • "title" use the title as an identifier within this form
      • "value" use the value of the item to identify it (often used for items with a static defaultValue such as HeaderItems
      • "index" use the index within the form's items array.

      If unset, and the locator has no specified name, default behavior is to identify by title (if available), then value (if available), otherwise by index.

      Returns:
      Current locateItemBy value. Default value is null
      See Also:
    • setMinHintWidth

      public FormItem setMinHintWidth(Integer minHintWidth)
      If this item is showing a hint, this setting specifies how much horizontal space is made available for rendering the hint text by default. Typically this reflects how much space the hint text takes up before it wraps.

      Note that the presence of a hint may cause a form item to expand horizontally past its specified width. This property value acts as a minimum - if the hint text can not wrap within this width (either due to wrapHintText being set to false, or due to it containing long, un-wrappable content), it will further expand to take up the space it needs.

      If unset this property will be picked up from the DynamicForm.minHintWidth setting.

      This setting does not apply to hints that are shown in field.

      Parameters:
      minHintWidth - New minHintWidth value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getMinHintWidth

      public Integer getMinHintWidth()
      If this item is showing a hint, this setting specifies how much horizontal space is made available for rendering the hint text by default. Typically this reflects how much space the hint text takes up before it wraps.

      Note that the presence of a hint may cause a form item to expand horizontally past its specified width. This property value acts as a minimum - if the hint text can not wrap within this width (either due to wrapHintText being set to false, or due to it containing long, un-wrappable content), it will further expand to take up the space it needs.

      If unset this property will be picked up from the DynamicForm.minHintWidth setting.

      This setting does not apply to hints that are shown in field.

      Returns:
      Current minHintWidth value. Default value is null
      See Also:
    • setMultiple

      public FormItem setMultiple(Boolean multiple)
      If true, multiple values may be selected.

      Only certain FormItems that support both singular and multiple values actually use this setting, such as SelectItem. Other FormItems such as MultiComboBoxItem are always effectively multiple:true, even if multiple:true is not set.

      Overrides:
      setMultiple in class Field
      Parameters:
      multiple - New multiple value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getMultiple

      public Boolean getMultiple()
      If true, multiple values may be selected.

      Only certain FormItems that support both singular and multiple values actually use this setting, such as SelectItem. Other FormItems such as MultiComboBoxItem are always effectively multiple:true, even if multiple:true is not set.

      Overrides:
      getMultiple in class Field
      Returns:
      Current multiple value. Default value is false
      See Also:
    • setMultipleValueSeparator

      public FormItem setMultipleValueSeparator(String multipleValueSeparator)
      If this item is displaying multiple values, this property will be the string that separates those values for display purposes.
      Parameters:
      multipleValueSeparator - New multipleValueSeparator value. Default value is ', '
      Returns:
      FormItem instance, for chaining setter calls
    • getMultipleValueSeparator

      public String getMultipleValueSeparator()
      If this item is displaying multiple values, this property will be the string that separates those values for display purposes.
      Returns:
      Current multipleValueSeparator value. Default value is ', '
    • getName

      public String getName()
      Name for this form field. Must be unique within the form as well as a valid JavaScript identifier - see FieldName for details and how to check for validity.

      The FormItem's name determines the name of the property it edits within the form.

      Note that an item must have a valid name or dataPath in order for its value to be validated and/or saved.

      Overrides:
      getName in class Field
      Returns:
      Current name value. Default value is null
      See Also:
    • setNullOriginalValueText

      public FormItem setNullOriginalValueText(String nullOriginalValueText)
      Text shown as the value in the originalValueMessage when showOldValueInHover is enabled, and when the value has been modified but was originally unset.

      Note : This is an advanced setting

      Parameters:
      nullOriginalValueText - New nullOriginalValueText value. Default value is "None"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getNullOriginalValueText

      public String getNullOriginalValueText()
      Text shown as the value in the originalValueMessage when showOldValueInHover is enabled, and when the value has been modified but was originally unset.
      Returns:
      Current nullOriginalValueText value. Default value is "None"
      See Also:
    • setOperator

      public FormItem setOperator(OperatorId operator)
      OperatorId to be used when DynamicForm.getValuesAsCriteria() is called.

      item.operator can be used to create a form that offers search functions such as numeric range filtering, without the more advanced user interface of the FilterBuilder. For example, two SpinnerItems could be created with formItem.operator set to "greaterThan" and "lessThan" respectively to enable filtering by a numeric range.

      When item.operator is set for any FormItem in a form, form.getValuesAsCriteria() will return an AdvancedCriteria object instead of a normal Criteria object. Each FormItem will produce one Criterion affecting the DataSource field specified by criteriaField. The criteria produced by the FormItems will be grouped under the logical operator provided by DynamicForm.operator.

      If operator is set for some fields but not others, the default operator is "equals" for fields with a valueMap or an optionDataSource, and for fields of type "enum" (or of a type that inherits from "enum"). The default operator for all other fields is controlled by DynamicForm.defaultSearchOperator.

      Note: formItem.operator is only supported for a form that has a dataSource. In a form with no DataSource, setting formItem.operator will have no effect.

      Parameters:
      operator - New operator value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getOperator

      public OperatorId getOperator()
      OperatorId to be used when DynamicForm.getValuesAsCriteria() is called.

      item.operator can be used to create a form that offers search functions such as numeric range filtering, without the more advanced user interface of the FilterBuilder. For example, two SpinnerItems could be created with formItem.operator set to "greaterThan" and "lessThan" respectively to enable filtering by a numeric range.

      When item.operator is set for any FormItem in a form, form.getValuesAsCriteria() will return an AdvancedCriteria object instead of a normal Criteria object. Each FormItem will produce one Criterion affecting the DataSource field specified by criteriaField. The criteria produced by the FormItems will be grouped under the logical operator provided by DynamicForm.operator.

      If operator is set for some fields but not others, the default operator is "equals" for fields with a valueMap or an optionDataSource, and for fields of type "enum" (or of a type that inherits from "enum"). The default operator for all other fields is controlled by DynamicForm.defaultSearchOperator.

      Note: formItem.operator is only supported for a form that has a dataSource. In a form with no DataSource, setting formItem.operator will have no effect.

      Returns:
      Current operator value. Default value is null
      See Also:
    • setOptionDataSource

      public FormItem setOptionDataSource(DataSource optionDataSource)
      If set, this FormItem will map stored values to display values as though a com.smartgwt.client.types.ValueMap were specified, by fetching records from the specified optionDataSource and extracting the valueField and displayField in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.

      With the default setting of fetchMissingValues, fetches will be initiated against the optionDataSource any time the FormItem has a non-null value and no corresponding display value is available. This includes when the form is first initialized, as well as any subsequent calls to setValue(), such as may happen when DynamicForm.editRecord() is called. Retrieved values are automatically cached by the FormItem.

      Note that if a normal, static valueMap is also specified for the field (either directly in the form item or as part of the field definition in the dataSource), it will be preferred to the data derived from the optionDataSource for whatever mappings are present.

      In a databound form, if displayField is specified for a FormItem and optionDataSource is unset, optionDataSource will default to the form's current DataSource

      If this method is called after the component has been drawn/initialized: Method to set the optionDataSource at runtime

      Parameters:
      optionDataSource - new optionDatasource. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getOptionDataSource

      public DataSource getOptionDataSource()
      If set, this FormItem will map stored values to display values as though a com.smartgwt.client.types.ValueMap were specified, by fetching records from the specified optionDataSource and extracting the valueField and displayField in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.

      With the default setting of fetchMissingValues, fetches will be initiated against the optionDataSource any time the FormItem has a non-null value and no corresponding display value is available. This includes when the form is first initialized, as well as any subsequent calls to setValue(), such as may happen when DynamicForm.editRecord() is called. Retrieved values are automatically cached by the FormItem.

      Note that if a normal, static valueMap is also specified for the field (either directly in the form item or as part of the field definition in the dataSource), it will be preferred to the data derived from the optionDataSource for whatever mappings are present.

      In a databound form, if displayField is specified for a FormItem and optionDataSource is unset, optionDataSource will default to the form's current DataSource

      Returns:
      Returns the optionDataSource for this item.

      Always uses item.optionDataSource if specified. Otherwise, if DataSourceField.foreignKey was specified, uses the target DataSource. Otherwise, uses the DataSource of this item's form (if one is configured). Default value is null

      See Also:
    • setOptionDataSource

      public FormItem setOptionDataSource(String optionDataSource)
      If set, this FormItem will map stored values to display values as though a com.smartgwt.client.types.ValueMap were specified, by fetching records from the specified optionDataSource and extracting the valueField and displayField in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.

      With the default setting of fetchMissingValues, fetches will be initiated against the optionDataSource any time the FormItem has a non-null value and no corresponding display value is available. This includes when the form is first initialized, as well as any subsequent calls to setValue(), such as may happen when DynamicForm.editRecord() is called. Retrieved values are automatically cached by the FormItem.

      Note that if a normal, static valueMap is also specified for the field (either directly in the form item or as part of the field definition in the dataSource), it will be preferred to the data derived from the optionDataSource for whatever mappings are present.

      In a databound form, if displayField is specified for a FormItem and optionDataSource is unset, optionDataSource will default to the form's current DataSource

      If this method is called after the component has been drawn/initialized: Method to set the optionDataSource at runtime

      Parameters:
      optionDataSource - new optionDatasource. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getOptionDataSourceAsString

      public String getOptionDataSourceAsString()
      If set, this FormItem will map stored values to display values as though a com.smartgwt.client.types.ValueMap were specified, by fetching records from the specified optionDataSource and extracting the valueField and displayField in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.

      With the default setting of fetchMissingValues, fetches will be initiated against the optionDataSource any time the FormItem has a non-null value and no corresponding display value is available. This includes when the form is first initialized, as well as any subsequent calls to setValue(), such as may happen when DynamicForm.editRecord() is called. Retrieved values are automatically cached by the FormItem.

      Note that if a normal, static valueMap is also specified for the field (either directly in the form item or as part of the field definition in the dataSource), it will be preferred to the data derived from the optionDataSource for whatever mappings are present.

      In a databound form, if displayField is specified for a FormItem and optionDataSource is unset, optionDataSource will default to the form's current DataSource

      Returns:
      Returns the optionDataSource for this item.

      Always uses item.optionDataSource if specified. Otherwise, if DataSourceField.foreignKey was specified, uses the target DataSource. Otherwise, uses the DataSource of this item's form (if one is configured). Default value is null

      See Also:
    • setOptionOperationId

      public FormItem setOptionOperationId(String optionOperationId)
      If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option dataSource to pick up display value mapping.

      Note : This is an advanced setting

      Parameters:
      optionOperationId - New optionOperationId value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getOptionOperationId

      public String getOptionOperationId()
      If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option dataSource to pick up display value mapping.
      Returns:
      Current optionOperationId value. Default value is null
      See Also:
    • setOptionTextMatchStyle

      public FormItem setOptionTextMatchStyle(TextMatchStyle optionTextMatchStyle)
      If this item has a specified optionDataSource, this property determines the textMatchStyle to use when interpretating any optionCriteria during the fetch to map valueField values to displayField values.

      Note : This is an advanced setting

      Parameters:
      optionTextMatchStyle - New optionTextMatchStyle value. Default value is "exact"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getOptionTextMatchStyle

      public TextMatchStyle getOptionTextMatchStyle()
      If this item has a specified optionDataSource, this property determines the textMatchStyle to use when interpretating any optionCriteria during the fetch to map valueField values to displayField values.
      Returns:
      Current optionTextMatchStyle value. Default value is "exact"
      See Also:
    • setOriginalValueMessage

      public FormItem setOriginalValueMessage(String originalValueMessage)
      Message shown when showOldValueInHover is enabled and the value has been modified.

      If unset, defaults to the form's DynamicForm.originalValueMessage. Otherwise, overrides the form-default originalValueMessage for this item.

      Note : This is an advanced setting

      Parameters:
      originalValueMessage - New originalValueMessage value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getOriginalValueMessage

      public String getOriginalValueMessage()
      Message shown when showOldValueInHover is enabled and the value has been modified.

      If unset, defaults to the form's DynamicForm.originalValueMessage. Otherwise, overrides the form-default originalValueMessage for this item.

      Returns:
      Current originalValueMessage value. Default value is null
      See Also:
    • getPicker

      public Canvas getPicker()
      The component that will be displayed when showPicker() is called due to a click on the picker icon.

      Can be specified directly as a Canvas, or created automatically via the com.smartgwt.client.types.AutoChild pattern. The default autoChild configuration for the picker is a Canvas with backgroundColor set and no other modifications.

      Note that the picker is not automatically destroyed with the FormItem that uses it, in order to allow recycling of picker components. To destroy a single-use picker, override Canvas.destroy().

      This component is an AutoChild named "picker". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current picker value. Default value is null
    • setPickerIconHeight

      public FormItem setPickerIconHeight(Integer pickerIconHeight)
      If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

      Note that if spriting is being used, and the image to be displayed is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.

      Note : This is an advanced setting

      Parameters:
      pickerIconHeight - New pickerIconHeight value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getPickerIconHeight

      public Integer getPickerIconHeight()
      If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

      Note that if spriting is being used, and the image to be displayed is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.

      Returns:
      Current pickerIconHeight value. Default value is null
    • setPickerIconName

      public FormItem setPickerIconName(String pickerIconName)
      If showPickerIcon is true, this attribute specifies the FormItemIcon.name applied to the picker icon

      Note : This is an advanced setting

      Parameters:
      pickerIconName - New pickerIconName value. Default value is "picker"
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPickerIconName

      public String getPickerIconName()
      If showPickerIcon is true, this attribute specifies the FormItemIcon.name applied to the picker icon
      Returns:
      Current pickerIconName value. Default value is "picker"
      See Also:
    • setPickerIconPrompt

      public FormItem setPickerIconPrompt(String pickerIconPrompt)
      Prompt to show when the user hovers the mouse over the picker icon.
      Parameters:
      pickerIconPrompt - New pickerIconPrompt value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPickerIconPrompt

      public String getPickerIconPrompt()
      Prompt to show when the user hovers the mouse over the picker icon.
      Returns:
      Current pickerIconPrompt value. Default value is null
      See Also:
    • setPickerIconProperties

      public FormItem setPickerIconProperties(FormItemIcon pickerIconProperties)
      If showPickerIcon is true for this item, this block of properties will be applied to the pickerIcon. Allows for advanced customization of this icon.

      Note : This is an advanced setting

      Parameters:
      pickerIconProperties - New pickerIconProperties value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getPickerIconProperties

      public FormItemIcon getPickerIconProperties()
      If showPickerIcon is true for this item, this block of properties will be applied to the pickerIcon. Allows for advanced customization of this icon.
      Returns:
      Current pickerIconProperties value. Default value is null
    • setPickerIconSrc

      public FormItem setPickerIconSrc(String pickerIconSrc)
      If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.

      Spriting can be used for this image, by setting this property to a SCSpriteConfig formatted string.

      Note : This is an advanced setting

      Parameters:
      pickerIconSrc - New pickerIconSrc value. Default value is ""
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPickerIconSrc

      public String getPickerIconSrc()
      If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.

      Spriting can be used for this image, by setting this property to a SCSpriteConfig formatted string.

      Returns:
      Current pickerIconSrc value. Default value is ""
      See Also:
    • setPickerIconStyle

      public FormItem setPickerIconStyle(String pickerIconStyle)
      Base CSS class name for a form item's picker icon cell. If unset, inherits from this item's controlStyle.
      Parameters:
      pickerIconStyle - New pickerIconStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPickerIconStyle

      public String getPickerIconStyle()
      Base CSS class name for a form item's picker icon cell. If unset, inherits from this item's controlStyle.
      Returns:
      Current pickerIconStyle value. Default value is null
      See Also:
    • setPickerIconWidth

      public FormItem setPickerIconWidth(Integer pickerIconWidth)
      If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

      Note that if spriting is being used, and the image to be displayed is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.

      Note : This is an advanced setting

      Parameters:
      pickerIconWidth - New pickerIconWidth value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getPickerIconWidth

      public Integer getPickerIconWidth()
      If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

      Note that if spriting is being used, and the image to be displayed is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
      Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.

      Returns:
      Current pickerIconWidth value. Default value is null
    • setPrintReadOnlyTextBoxStyle

      public FormItem setPrintReadOnlyTextBoxStyle(String printReadOnlyTextBoxStyle)
      CSS class name to apply to the print view of an item's text box if the item is canEdit:false, with readOnlyDisplay:static.

      If specified this will take precedence over printTextBoxStyle for static readonly items.

      Parameters:
      printReadOnlyTextBoxStyle - New printReadOnlyTextBoxStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPrintReadOnlyTextBoxStyle

      public String getPrintReadOnlyTextBoxStyle()
      CSS class name to apply to the print view of an item's text box if the item is canEdit:false, with readOnlyDisplay:static.

      If specified this will take precedence over printTextBoxStyle for static readonly items.

      Returns:
      Current printReadOnlyTextBoxStyle value. Default value is null
      See Also:
    • setPrintTextBoxStyle

      public FormItem setPrintTextBoxStyle(String printTextBoxStyle)
      Base CSS class name for a form item's text box element when getting printable HTML for the form. If unset textBoxStyle will be used instead. Note that focused styling will never be displayed while printing, though error and disabled styling will.

      By default this style will be used for printHTML for the item even if the item is canEdit:false with readOnlyDisplay:static.
      To override this behavior, developers may also specify a custom print style for this state via the printReadOnlyTextBoxStyle.

      Parameters:
      printTextBoxStyle - New printTextBoxStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPrintTextBoxStyle

      public String getPrintTextBoxStyle()
      Base CSS class name for a form item's text box element when getting printable HTML for the form. If unset textBoxStyle will be used instead. Note that focused styling will never be displayed while printing, though error and disabled styling will.

      By default this style will be used for printHTML for the item even if the item is canEdit:false with readOnlyDisplay:static.
      To override this behavior, developers may also specify a custom print style for this state via the printReadOnlyTextBoxStyle.

      Returns:
      Current printTextBoxStyle value. Default value is null
      See Also:
    • setPrintTitleStyle

      public FormItem setPrintTitleStyle(String printTitleStyle)
      Base CSS stylename for a form item's title when generating print HTML for the item. If unset titleStyle will be used instead.
      Parameters:
      printTitleStyle - New printTitleStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPrintTitleStyle

      public String getPrintTitleStyle()
      Base CSS stylename for a form item's title when generating print HTML for the item. If unset titleStyle will be used instead.
      Returns:
      Current printTitleStyle value. Default value is null
      See Also:
    • setPrompt

      public FormItem setPrompt(String prompt)
      This text is shown as a tooltip prompt when the cursor hovers over this item.

      When the item is read-only a different hover can be shown with readOnlyHover. Or, when the item is disabled or read-only with readOnlyDisplay:disabled a different hover can be shown with disabledHover.

      Note that when the form is disabled, or when this item suppresses hovers, this prompt will not be shown.

      If this method is called after the component has been drawn/initialized: Sets the prompt for this item.

      Parameters:
      prompt - new prompt for the item. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getPrompt

      public String getPrompt()
      This text is shown as a tooltip prompt when the cursor hovers over this item.

      When the item is read-only a different hover can be shown with readOnlyHover. Or, when the item is disabled or read-only with readOnlyDisplay:disabled a different hover can be shown with disabledHover.

      Note that when the form is disabled, or when this item suppresses hovers, this prompt will not be shown.

      Returns:
      Current prompt value. Default value is null
      See Also:
    • setReadOnlyCanSelectText

      public FormItem setReadOnlyCanSelectText(ReadOnlyDisplayAppearance... readOnlyCanSelectText)
      For items showing a text value with canEdit set to false, should the user be able to select the text in the item?

      Default behavior allows selection if readOnlyDisplay is "static" or "readOnly" [but not "disabled"]. Developers may add or remove ReadOnlyDisplayAppearance values to change this behavior.

      Note that this does not apply to disabled items, where text selection is never enabled

      Parameters:
      readOnlyCanSelectText - New readOnlyCanSelectText value. Default value is ["static", "readOnly"]
      Returns:
      FormItem instance, for chaining setter calls
    • getReadOnlyCanSelectText

      public ReadOnlyDisplayAppearance[] getReadOnlyCanSelectText()
      For items showing a text value with canEdit set to false, should the user be able to select the text in the item?

      Default behavior allows selection if readOnlyDisplay is "static" or "readOnly" [but not "disabled"]. Developers may add or remove ReadOnlyDisplayAppearance values to change this behavior.

      Note that this does not apply to disabled items, where text selection is never enabled

      Returns:
      Current readOnlyCanSelectText value. Default value is ["static", "readOnly"]
    • setReadOnlyControlStyle

      public FormItem setReadOnlyControlStyle(String readOnlyControlStyle)
      Modified control style to apply when this item is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC.
      Parameters:
      readOnlyControlStyle - New readOnlyControlStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getReadOnlyControlStyle

      public String getReadOnlyControlStyle()
      Modified control style to apply when this item is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC.
      Returns:
      Current readOnlyControlStyle value. Default value is null
      See Also:
    • setReadOnlyDisplay

      public FormItem setReadOnlyDisplay(ReadOnlyDisplayAppearance readOnlyDisplay)
      If this item is read-only, how should this item be displayed to the user? If set, overrides the form-level DynamicForm.readOnlyDisplay default.

      If this method is called after the component has been drawn/initialized: Setter for readOnlyDisplay.

      Note that calling this method for a ButtonItem with ButtonItem.enableWhen set is an error, since readOnlyDisplay is then considered to always be "disabled".

      Parameters:
      readOnlyDisplay - new readOnlyDisplay value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getReadOnlyDisplay

      public ReadOnlyDisplayAppearance getReadOnlyDisplay()
      If this item is read-only, how should this item be displayed to the user? If set, overrides the form-level DynamicForm.readOnlyDisplay default.
      Returns:
      Current readOnlyDisplay value. Default value is null
      See Also:
    • setReadOnlyHover

      public FormItem setReadOnlyHover(String readOnlyHover)
      This text is shown as a tooltip prompt when the cursor hovers over this item and the item is read-only.

      Note that when the form is disabled, or when this item suppresses hovers, nothing will be shown.

      Parameters:
      readOnlyHover - New readOnlyHover value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getReadOnlyHover

      public String getReadOnlyHover()
      This text is shown as a tooltip prompt when the cursor hovers over this item and the item is read-only.

      Note that when the form is disabled, or when this item suppresses hovers, nothing will be shown.

      Returns:
      Current readOnlyHover value. Default value is null
      See Also:
    • setReadOnlyTextBoxStyle

      public FormItem setReadOnlyTextBoxStyle(String readOnlyTextBoxStyle)
      Base text box style to apply when this item is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC. If set, overrides the form-level DynamicForm.readOnlyTextBoxStyle default.
      Parameters:
      readOnlyTextBoxStyle - New readOnlyTextBoxStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getReadOnlyTextBoxStyle

      public String getReadOnlyTextBoxStyle()
      Base text box style to apply when this item is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC. If set, overrides the form-level DynamicForm.readOnlyTextBoxStyle default.
      Returns:
      Current readOnlyTextBoxStyle value. Default value is null
      See Also:
    • setReadOnlyWhen

      public FormItem setReadOnlyWhen(AdvancedCriteria readOnlyWhen)
      Criteria to be evaluated to determine whether this FormItem should be made read-only. Appearance when read-only is determined by readOnlyDisplay.

      Criteria are evaluated against the form's current values as well as the current rule context. Criteria are re-evaluated every time form values or the rule context changes, whether by end user action or by programmatic calls.

      A basic criteria uses textMatchStyle:"exact". When specified in Component XML this property allows shorthand formats for defining criteria.

      Note: A FormItem using readOnlyWhen must have a name defined. shouldSaveValue can be set to false to prevent the field from storing its value into the form's values.

      Parameters:
      readOnlyWhen - New readOnlyWhen value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getReadOnlyWhen

      public AdvancedCriteria getReadOnlyWhen()
      Criteria to be evaluated to determine whether this FormItem should be made read-only. Appearance when read-only is determined by readOnlyDisplay.

      Criteria are evaluated against the form's current values as well as the current rule context. Criteria are re-evaluated every time form values or the rule context changes, whether by end user action or by programmatic calls.

      A basic criteria uses textMatchStyle:"exact". When specified in Component XML this property allows shorthand formats for defining criteria.

      Note: A FormItem using readOnlyWhen must have a name defined. shouldSaveValue can be set to false to prevent the field from storing its value into the form's values.

      Returns:
      Current readOnlyWhen value. Default value is null
      See Also:
    • setRedrawOnChange

      public FormItem setRedrawOnChange(Boolean redrawOnChange)
      If true, this item will cause the entire form to be redrawn when the item's "elementChanged" event is done firing
      Parameters:
      redrawOnChange - New redrawOnChange value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getRedrawOnChange

      public Boolean getRedrawOnChange()
      If true, this item will cause the entire form to be redrawn when the item's "elementChanged" event is done firing
      Returns:
      Current redrawOnChange value. Default value is false
    • setRejectInvalidValueOnChange

      public FormItem setRejectInvalidValueOnChange(Boolean rejectInvalidValueOnChange)
      If validateOnChange is true, and validation fails for this item on change, with no suggested value, should we revert to the previous value, or continue to display the bad value entered by the user. May be set at the item or form level.

      Note : This is an advanced setting

      Parameters:
      rejectInvalidValueOnChange - New rejectInvalidValueOnChange value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getRejectInvalidValueOnChange

      public Boolean getRejectInvalidValueOnChange()
      If validateOnChange is true, and validation fails for this item on change, with no suggested value, should we revert to the previous value, or continue to display the bad value entered by the user. May be set at the item or form level.
      Returns:
      Current rejectInvalidValueOnChange value. Default value is false
    • setRequired

      public FormItem setRequired(Boolean required)
      Whether a non-empty value is required for this field to pass validation.

      If the user does not fill in the required field, the error message to be shown will be taken from these properties in the following order: requiredMessage, DynamicForm.requiredMessage, DataSource.requiredMessage, requiredField.

      Note: if specified on a FormItem, required is only enforced on the client. required should generally be specified on a DataSourceField.

      If this method is called after the component has been drawn/initialized: Setter to mark this formItem as required, or not required at runtime. Note that an alternative approach to updating the required flag directly would be to simply use a requiredIf type validator.

      Note that this method will not re-validate this item by default or clear any existing validation errors. If desired, this may be achieved by calling validate() or DynamicForm.clearErrors().

      Overrides:
      setRequired in class Field
      Parameters:
      required - new required value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getRequired

      public Boolean getRequired()
      Whether a non-empty value is required for this field to pass validation.

      If the user does not fill in the required field, the error message to be shown will be taken from these properties in the following order: requiredMessage, DynamicForm.requiredMessage, DataSource.requiredMessage, requiredField.

      Note: if specified on a FormItem, required is only enforced on the client. required should generally be specified on a DataSourceField.

      Returns:
      Current required value. Default value is false
      See Also:
    • setRequiredMessage

      public FormItem setRequiredMessage(String requiredMessage)
      The required message for required field errors.
      Parameters:
      requiredMessage - New requiredMessage value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getRequiredMessage

      public String getRequiredMessage()
      The required message for required field errors.
      Returns:
      Current requiredMessage value. Default value is null
      See Also:
    • setRequiredWhen

      public FormItem setRequiredWhen(Criteria requiredWhen)
      Criteria to be evaluated to determine whether this FormItem should be required.

      Criteria are evaluated against the form's current values as well as the current rule context. Criteria are re-evaluated every time form values or the rule context changes, whether by end user action or by programmatic calls.

      A basic criteria uses textMatchStyle:"exact". When specified in Component XML this property allows shorthand formats for defining criteria.

      Note: A FormItem using requiredWhen must have a name defined.

      Parameters:
      requiredWhen - New requiredWhen value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getRequiredWhen

      public Criteria getRequiredWhen()
      Criteria to be evaluated to determine whether this FormItem should be required.

      Criteria are evaluated against the form's current values as well as the current rule context. Criteria are re-evaluated every time form values or the rule context changes, whether by end user action or by programmatic calls.

      A basic criteria uses textMatchStyle:"exact". When specified in Component XML this property allows shorthand formats for defining criteria.

      Note: A FormItem using requiredWhen must have a name defined.

      Returns:
      Current requiredWhen value. Default value is null
      See Also:
    • setRowSpan

      public FormItem setRowSpan(int rowSpan)
      Number of rows that this item spans
      Parameters:
      rowSpan - New rowSpan value. Default value is 1
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getRowSpan

      public int getRowSpan()
      Number of rows that this item spans
      Returns:
      Current rowSpan value. Default value is 1
      See Also:
    • setSaveOnEnter

      public FormItem setSaveOnEnter(Boolean saveOnEnter)
      Set this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem and saveOnEnter is true on the parent form.
      Parameters:
      saveOnEnter - New saveOnEnter value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getSaveOnEnter

      public Boolean getSaveOnEnter()
      Set this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem and saveOnEnter is true on the parent form.
      Returns:
      Current saveOnEnter value. Default value is null
    • setSelectOnClick

      public FormItem setSelectOnClick(Boolean selectOnClick)
      Allows the selectOnClick behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnClick.
      Parameters:
      selectOnClick - New selectOnClick value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getSelectOnClick

      public Boolean getSelectOnClick()
      Allows the selectOnClick behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnClick.
      Returns:
      Current selectOnClick value. Default value is null
      See Also:
    • setSelectOnFocus

      public FormItem setSelectOnFocus(Boolean selectOnFocus)
      Allows the selectOnFocus behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnFocus.
      Parameters:
      selectOnFocus - New selectOnFocus value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getSelectOnFocus

      public Boolean getSelectOnFocus()
      Allows the selectOnFocus behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnFocus.
      Returns:
      Current selectOnFocus value. Default value is null
      See Also:
    • setShouldSaveValue

      public FormItem setShouldSaveValue(Boolean shouldSaveValue)
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Parameters:
      shouldSaveValue - New shouldSaveValue value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
    • getShouldSaveValue

      public Boolean getShouldSaveValue()
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Returns:
      Current shouldSaveValue value. Default value is true
    • setShowClippedTitleOnHover

      public FormItem setShowClippedTitleOnHover(boolean showClippedTitleOnHover)
      If true and the title is clipped, then a hover containing the full title of this item is enabled.

      A TitleHoverEvent is fired before the hover is displayed, allowing the hover to be canceled if desired. The HTML shown in the hover can be customized by setting a FormItemHoverFormatter on either this FormItem or the DynamicForm. See setItemTitleHoverFormatter().

      If the item suppresses hovers, nothing will be shown.

      Parameters:
      showClippedTitleOnHover - New showClippedTitleOnHover value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
    • getShowClippedTitleOnHover

      public boolean getShowClippedTitleOnHover()
      If true and the title is clipped, then a hover containing the full title of this item is enabled.

      A TitleHoverEvent is fired before the hover is displayed, allowing the hover to be canceled if desired. The HTML shown in the hover can be customized by setting a FormItemHoverFormatter on either this FormItem or the DynamicForm. See setItemTitleHoverFormatter().

      If the item suppresses hovers, nothing will be shown.

      Returns:
      Current showClippedTitleOnHover value. Default value is true
    • setShowClippedValueOnHover

      public FormItem setShowClippedValueOnHover(Boolean showClippedValueOnHover)
      If true and the value is clipped, then a hover containing the full value of this item is enabled.

      A ValueHoverEvent is fired before the hover is displayed, allowing the hover to be canceled if desired. The HTML shown in the hover can be customized by setting a FormItemHoverFormatter on either this FormItem or the DynamicForm. See setItemValueHoverFormatter().

      If the item suppresses hovers, nothing will be shown.

      Parameters:
      showClippedValueOnHover - New showClippedValueOnHover value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
    • getShowClippedValueOnHover

      public Boolean getShowClippedValueOnHover()
      If true and the value is clipped, then a hover containing the full value of this item is enabled.

      A ValueHoverEvent is fired before the hover is displayed, allowing the hover to be canceled if desired. The HTML shown in the hover can be customized by setting a FormItemHoverFormatter on either this FormItem or the DynamicForm. See setItemValueHoverFormatter().

      If the item suppresses hovers, nothing will be shown.

      Returns:
      Current showClippedValueOnHover value. Default value is true
    • setShowDeletions

      public FormItem setShowDeletions(Boolean showDeletions)
      For items that support multiple values, this causes distinct CSS styling to be applied to values that the user has unselected.

      Only allowed when showPending is true. Defaults to the form-level DynamicForm.showDeletions setting if set; otherwise, to the value of showPending.

      Only supported for MultiComboBoxItem and for SelectItem when multiple:true is set. The specific default behaviors are:

      NOTE: When a value is shown as deleted, this is not reflected to screen readers, and screen readers are instructed to ignore the deleted value. Therefore, it is not advisable to design a UI where it is necessary for the user to know whether a value is shown as deleted in order to work with the form.

      Note : This is an advanced setting

      Parameters:
      showDeletions - New showDeletions value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowDeletions

      public Boolean getShowDeletions()
      For items that support multiple values, this causes distinct CSS styling to be applied to values that the user has unselected.

      Only allowed when showPending is true. Defaults to the form-level DynamicForm.showDeletions setting if set; otherwise, to the value of showPending.

      Only supported for MultiComboBoxItem and for SelectItem when multiple:true is set. The specific default behaviors are:

      NOTE: When a value is shown as deleted, this is not reflected to screen readers, and screen readers are instructed to ignore the deleted value. Therefore, it is not advisable to design a UI where it is necessary for the user to know whether a value is shown as deleted in order to work with the form.

      Returns:
      Current showDeletions value. Default value is null
      See Also:
    • setShowDisabled

      public FormItem setShowDisabled(Boolean showDisabled)
      When this item is disabled, should it be re-styled to indicate its disabled state?

      See FormItemStyling for more details on formItem styling.

      If this method is called after the component has been drawn/initialized: Setter method for showDisabled

      Note : This is an advanced setting

      Parameters:
      showDisabled - new showDisabled setting. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowDisabled

      public Boolean getShowDisabled()
      When this item is disabled, should it be re-styled to indicate its disabled state?

      See FormItemStyling for more details on formItem styling.

      Returns:
      Current showDisabled value. Default value is true
      See Also:
    • setShowDisabledIconsOnFocus

      public FormItem setShowDisabledIconsOnFocus(Boolean showDisabledIconsOnFocus)
      If showIconsOnFocus is true, should icons marked as disabled be shown on focus?

      Default setting is false - it is not commonly desirable to present a user with a disabled icon on focus.

      Can be overridden at the icon level by FormItemIcon.showDisabledOnFocus

      Note : This is an advanced setting

      Parameters:
      showDisabledIconsOnFocus - New showDisabledIconsOnFocus value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getShowDisabledIconsOnFocus

      public Boolean getShowDisabledIconsOnFocus()
      If showIconsOnFocus is true, should icons marked as disabled be shown on focus?

      Default setting is false - it is not commonly desirable to present a user with a disabled icon on focus.

      Can be overridden at the icon level by FormItemIcon.showDisabledOnFocus

      Returns:
      Current showDisabledIconsOnFocus value. Default value is false
    • setShowDisabledPickerIconOnFocus

      public FormItem setShowDisabledPickerIconOnFocus(Boolean showDisabledPickerIconOnFocus)
      If showPickerIconOnFocus is true, should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?)

      Default setting is false - it is not commonly desirable to present a user with a disabled icon on focus.

      Can be overridden at the icon level by FormItemIcon.showDisabledOnFocus

      Note : This is an advanced setting

      Parameters:
      showDisabledPickerIconOnFocus - New showDisabledPickerIconOnFocus value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getShowDisabledPickerIconOnFocus

      public Boolean getShowDisabledPickerIconOnFocus()
      If showPickerIconOnFocus is true, should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?)

      Default setting is false - it is not commonly desirable to present a user with a disabled icon on focus.

      Can be overridden at the icon level by FormItemIcon.showDisabledOnFocus

      Returns:
      Current showDisabledPickerIconOnFocus value. Default value is false
    • setShowErrorIcon

      public FormItem setShowErrorIcon(Boolean showErrorIcon)
      showErrorIcons, showErrorText, errorOrientation, and showErrorStyle control how validation errors are displayed when they are displayed inline in the form (next to the form item where there is a validation error). To instead display all errors at the top of the form, set showInlineErrors:false.

      showErrorIcons, showErrorText, errorOrientation and showErrorStyle are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual FormItems.

      The HTML displayed next to a form item with errors is generated by getErrorHTML(). The default implementation of that method respects showErrorIcons and showErrorText as follows:

      showErrorIcons, or showErrorIcon at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed by errorIconSrc, errorIconWidth and errorIconHeight

      showErrorText determines whether the text of the validation error should be displayed next to fields which have validation errors. The attribute DynamicForm.showTitlesWithErrorMessages may be set to prefix error messages with the form item's title + ":" (may be desired if the item has showTitle set to false).
      If showErrorText is unset, the error text will be shown if DynamicForm.linearMode is true (or DynamicForm.linearOnMobile is true for mobile devices), otherwise it will not be shown.

      In addition to this:

      DynamicForm.errorOrientation controls where the error HTML should appear relative to form items. Therefore the combination of showErrorText:false and errorOrientation:"left" creates a compact validation error display consisting of just an icon, to the left of the item with the error message available via a hover (similar appearance to ListGrid validation error display).
      If errorOrientation is unset, the error orientation will default to "top" if DynamicForm.linearMode is enabled (or DynamicForm.linearOnMobile is true for mobile devices) and error text is not showing, "left" otherwise.

      showErrorStyle determines whether fields with validation errors should have special styling applied to them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See FormItemBaseStyle for more on this.

      Parameters:
      showErrorIcon - New showErrorIcon value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowErrorIcon

      public Boolean getShowErrorIcon()
      showErrorIcons, showErrorText, errorOrientation, and showErrorStyle control how validation errors are displayed when they are displayed inline in the form (next to the form item where there is a validation error). To instead display all errors at the top of the form, set showInlineErrors:false.

      showErrorIcons, showErrorText, errorOrientation and showErrorStyle are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual FormItems.

      The HTML displayed next to a form item with errors is generated by getErrorHTML(). The default implementation of that method respects showErrorIcons and showErrorText as follows:

      showErrorIcons, or showErrorIcon at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed by errorIconSrc, errorIconWidth and errorIconHeight

      showErrorText determines whether the text of the validation error should be displayed next to fields which have validation errors. The attribute DynamicForm.showTitlesWithErrorMessages may be set to prefix error messages with the form item's title + ":" (may be desired if the item has showTitle set to false).
      If showErrorText is unset, the error text will be shown if DynamicForm.linearMode is true (or DynamicForm.linearOnMobile is true for mobile devices), otherwise it will not be shown.

      In addition to this:

      DynamicForm.errorOrientation controls where the error HTML should appear relative to form items. Therefore the combination of showErrorText:false and errorOrientation:"left" creates a compact validation error display consisting of just an icon, to the left of the item with the error message available via a hover (similar appearance to ListGrid validation error display).
      If errorOrientation is unset, the error orientation will default to "top" if DynamicForm.linearMode is enabled (or DynamicForm.linearOnMobile is true for mobile devices) and error text is not showing, "left" otherwise.

      showErrorStyle determines whether fields with validation errors should have special styling applied to them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See FormItemBaseStyle for more on this.

      Returns:
      Current showErrorIcon value. Default value is null
      See Also:
    • setShowErrorIconInline

      public FormItem setShowErrorIconInline(Boolean showErrorIconInline)
      When set to true, this attribute renders the error-icon inline in the FormItem, next to other icons, instead of in a separate error-element outside of the item's main editor. When rendering the error-icon inline, the error-text is not displayed but is available in the icon's hover.

      Icon-properties can be applied to the error-icon via errorIconProperties.

      Note : This is an advanced setting

      Parameters:
      showErrorIconInline - New showErrorIconInline value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getShowErrorIconInline

      public Boolean getShowErrorIconInline()
      When set to true, this attribute renders the error-icon inline in the FormItem, next to other icons, instead of in a separate error-element outside of the item's main editor. When rendering the error-icon inline, the error-text is not displayed but is available in the icon's hover.

      Icon-properties can be applied to the error-icon via errorIconProperties.

      Returns:
      Current showErrorIconInline value. Default value is null
    • setShowErrorStyle

      public FormItem setShowErrorStyle(Boolean showErrorStyle)
      showErrorIcons, showErrorText, errorOrientation, and showErrorStyle control how validation errors are displayed when they are displayed inline in the form (next to the form item where there is a validation error). To instead display all errors at the top of the form, set showInlineErrors:false.

      showErrorIcons, showErrorText, errorOrientation and showErrorStyle are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual FormItems.

      The HTML displayed next to a form item with errors is generated by getErrorHTML(). The default implementation of that method respects showErrorIcons and showErrorText as follows:

      showErrorIcons, or showErrorIcon at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed by errorIconSrc, errorIconWidth and errorIconHeight

      showErrorText determines whether the text of the validation error should be displayed next to fields which have validation errors. The attribute DynamicForm.showTitlesWithErrorMessages may be set to prefix error messages with the form item's title + ":" (may be desired if the item has showTitle set to false).
      If showErrorText is unset, the error text will be shown if DynamicForm.linearMode is true (or DynamicForm.linearOnMobile is true for mobile devices), otherwise it will not be shown.

      In addition to this:

      DynamicForm.errorOrientation controls where the error HTML should appear relative to form items. Therefore the combination of showErrorText:false and errorOrientation:"left" creates a compact validation error display consisting of just an icon, to the left of the item with the error message available via a hover (similar appearance to ListGrid validation error display).
      If errorOrientation is unset, the error orientation will default to "top" if DynamicForm.linearMode is enabled (or DynamicForm.linearOnMobile is true for mobile devices) and error text is not showing, "left" otherwise.

      showErrorStyle determines whether fields with validation errors should have special styling applied to them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See FormItemBaseStyle for more on this.

      Parameters:
      showErrorStyle - New showErrorStyle value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowErrorStyle

      public Boolean getShowErrorStyle()
      showErrorIcons, showErrorText, errorOrientation, and showErrorStyle control how validation errors are displayed when they are displayed inline in the form (next to the form item where there is a validation error). To instead display all errors at the top of the form, set showInlineErrors:false.

      showErrorIcons, showErrorText, errorOrientation and showErrorStyle are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual FormItems.

      The HTML displayed next to a form item with errors is generated by getErrorHTML(). The default implementation of that method respects showErrorIcons and showErrorText as follows:

      showErrorIcons, or showErrorIcon at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed by errorIconSrc, errorIconWidth and errorIconHeight

      showErrorText determines whether the text of the validation error should be displayed next to fields which have validation errors. The attribute DynamicForm.showTitlesWithErrorMessages may be set to prefix error messages with the form item's title + ":" (may be desired if the item has showTitle set to false).
      If showErrorText is unset, the error text will be shown if DynamicForm.linearMode is true (or DynamicForm.linearOnMobile is true for mobile devices), otherwise it will not be shown.

      In addition to this:

      DynamicForm.errorOrientation controls where the error HTML should appear relative to form items. Therefore the combination of showErrorText:false and errorOrientation:"left" creates a compact validation error display consisting of just an icon, to the left of the item with the error message available via a hover (similar appearance to ListGrid validation error display).
      If errorOrientation is unset, the error orientation will default to "top" if DynamicForm.linearMode is enabled (or DynamicForm.linearOnMobile is true for mobile devices) and error text is not showing, "left" otherwise.

      showErrorStyle determines whether fields with validation errors should have special styling applied to them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See FormItemBaseStyle for more on this.

      Returns:
      Current showErrorStyle value. Default value is null
      See Also:
    • setShowErrorText

      public FormItem setShowErrorText(Boolean showErrorText)
      showErrorIcons, showErrorText, errorOrientation, and showErrorStyle control how validation errors are displayed when they are displayed inline in the form (next to the form item where there is a validation error). To instead display all errors at the top of the form, set showInlineErrors:false.

      showErrorIcons, showErrorText, errorOrientation and showErrorStyle are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual FormItems.

      The HTML displayed next to a form item with errors is generated by getErrorHTML(). The default implementation of that method respects showErrorIcons and showErrorText as follows:

      showErrorIcons, or showErrorIcon at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed by errorIconSrc, errorIconWidth and errorIconHeight

      showErrorText determines whether the text of the validation error should be displayed next to fields which have validation errors. The attribute DynamicForm.showTitlesWithErrorMessages may be set to prefix error messages with the form item's title + ":" (may be desired if the item has showTitle set to false).
      If showErrorText is unset, the error text will be shown if DynamicForm.linearMode is true (or DynamicForm.linearOnMobile is true for mobile devices), otherwise it will not be shown.

      In addition to this:

      DynamicForm.errorOrientation controls where the error HTML should appear relative to form items. Therefore the combination of showErrorText:false and errorOrientation:"left" creates a compact validation error display consisting of just an icon, to the left of the item with the error message available via a hover (similar appearance to ListGrid validation error display).
      If errorOrientation is unset, the error orientation will default to "top" if DynamicForm.linearMode is enabled (or DynamicForm.linearOnMobile is true for mobile devices) and error text is not showing, "left" otherwise.

      showErrorStyle determines whether fields with validation errors should have special styling applied to them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See FormItemBaseStyle for more on this.

      Parameters:
      showErrorText - New showErrorText value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowErrorText

      public Boolean getShowErrorText()
      showErrorIcons, showErrorText, errorOrientation, and showErrorStyle control how validation errors are displayed when they are displayed inline in the form (next to the form item where there is a validation error). To instead display all errors at the top of the form, set showInlineErrors:false.

      showErrorIcons, showErrorText, errorOrientation and showErrorStyle are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual FormItems.

      The HTML displayed next to a form item with errors is generated by getErrorHTML(). The default implementation of that method respects showErrorIcons and showErrorText as follows:

      showErrorIcons, or showErrorIcon at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed by errorIconSrc, errorIconWidth and errorIconHeight

      showErrorText determines whether the text of the validation error should be displayed next to fields which have validation errors. The attribute DynamicForm.showTitlesWithErrorMessages may be set to prefix error messages with the form item's title + ":" (may be desired if the item has showTitle set to false).
      If showErrorText is unset, the error text will be shown if DynamicForm.linearMode is true (or DynamicForm.linearOnMobile is true for mobile devices), otherwise it will not be shown.

      In addition to this:

      DynamicForm.errorOrientation controls where the error HTML should appear relative to form items. Therefore the combination of showErrorText:false and errorOrientation:"left" creates a compact validation error display consisting of just an icon, to the left of the item with the error message available via a hover (similar appearance to ListGrid validation error display).
      If errorOrientation is unset, the error orientation will default to "top" if DynamicForm.linearMode is enabled (or DynamicForm.linearOnMobile is true for mobile devices) and error text is not showing, "left" otherwise.

      showErrorStyle determines whether fields with validation errors should have special styling applied to them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See FormItemBaseStyle for more on this.

      Returns:
      Current showErrorText value. Default value is null
      See Also:
    • setShowFocused

      public FormItem setShowFocused(Boolean showFocused)
      When this item receives focus, should it be re-styled to indicate it has focus?

      See FormItemStyling for more details on formItem styling.

      Note : This is an advanced setting

      Parameters:
      showFocused - New showFocused value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowFocused

      public Boolean getShowFocused()
      When this item receives focus, should it be re-styled to indicate it has focus?

      See FormItemStyling for more details on formItem styling.

      Returns:
      Current showFocused value. Default value is false
      See Also:
    • setShowFocusedErrorState

      public FormItem setShowFocusedErrorState(Boolean showFocusedErrorState)
      If set to true, when an item has errors and is focused, an "ErrorFocused" suffix will appear on the stylename.

      Note : This is an advanced setting

      Parameters:
      showFocusedErrorState - New showFocusedErrorState value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowFocusedErrorState

      public Boolean getShowFocusedErrorState()
      If set to true, when an item has errors and is focused, an "ErrorFocused" suffix will appear on the stylename.
      Returns:
      Current showFocusedErrorState value. Default value is false
      See Also:
    • setShowFocusedIcons

      public FormItem setShowFocusedIcons(Boolean showFocusedIcons)
      If we're showing icons, should we change their image source to the appropriate focused source when this item has focus? Can be overridden on a per icon basis by the formItemIcon showFocused property.

      Note : This is an advanced setting

      Parameters:
      showFocusedIcons - New showFocusedIcons value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getShowFocusedIcons

      public Boolean getShowFocusedIcons()
      If we're showing icons, should we change their image source to the appropriate focused source when this item has focus? Can be overridden on a per icon basis by the formItemIcon showFocused property.
      Returns:
      Current showFocusedIcons value. Default value is null
    • setShowFocusedPickerIcon

      public FormItem setShowFocusedPickerIcon(Boolean showFocusedPickerIcon)
      If showPickerIcon is true for this item, should the picker icon show a focused image when the form item has focus?
      Parameters:
      showFocusedPickerIcon - New showFocusedPickerIcon value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
    • getShowFocusedPickerIcon

      public Boolean getShowFocusedPickerIcon()
      If showPickerIcon is true for this item, should the picker icon show a focused image when the form item has focus?
      Returns:
      Current showFocusedPickerIcon value. Default value is false
    • setShowHint

      public FormItem setShowHint(Boolean showHint)
      If a hint is defined for this form item, should it be shown?

      Note : This is an advanced setting

      Parameters:
      showHint - New showHint value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowHint

      public Boolean getShowHint()
      If a hint is defined for this form item, should it be shown?
      Returns:
      Current showHint value. Default value is true
      See Also:
    • setShowIcons

      public FormItem setShowIcons(Boolean showIcons)
      Set to false to suppress writing out any icons for this item.

      Note : This is an advanced setting

      Parameters:
      showIcons - New showIcons value. Default value is true
      Returns:
      FormItem instance, for chaining setter calls
    • getShowIcons

      public Boolean getShowIcons()
      Set to false to suppress writing out any icons for this item.
      Returns:
      Current showIcons value. Default value is true
    • setShowIconsOnFocus

      public FormItem setShowIconsOnFocus(Boolean showIconsOnFocus)
      Show the icons when the item gets focus, and hide them when it loses focus. Can be overridden at the icon level by FormItemIcon.showOnFocus.

      Note that icons marked as disabled will not be shown on focus even if this flag is true by default. This may be overridden by showDisabledIconsOnFocus.

      If this method is called after the component has been drawn/initialized: Sets showIconsOnFocus and causes the visibility of all icons to be updated and the item redrawn as appropriate.

      Note : This is an advanced setting

      Parameters:
      showIconsOnFocus - new value of showIconsOnFocus. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getShowIconsOnFocus

      public Boolean getShowIconsOnFocus()
      Show the icons when the item gets focus, and hide them when it loses focus. Can be overridden at the icon level by FormItemIcon.showOnFocus.

      Note that icons marked as disabled will not be shown on focus even if this flag is true by default. This may be overridden by showDisabledIconsOnFocus.

      Returns:
      Current showIconsOnFocus value. Default value is null
    • setShowImageAsURL

      public FormItem setShowImageAsURL(Boolean showImageAsURL)
      For fields of type:"image", if the field is non editable, and being displayed with readOnlyDisplay:"static", should the value (URL) be displayed as text, or should an image be rendered?

      If unset, DynamicForm.showImageAsURL will be consulted instead.

      Parameters:
      showImageAsURL - New showImageAsURL value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getShowImageAsURL

      public Boolean getShowImageAsURL()
      For fields of type:"image", if the field is non editable, and being displayed with readOnlyDisplay:"static", should the value (URL) be displayed as text, or should an image be rendered?

      If unset, DynamicForm.showImageAsURL will be consulted instead.

      Returns:
      Current showImageAsURL value. Default value is null
    • setShowOldValueInHover

      public FormItem setShowOldValueInHover(Boolean showOldValueInHover)
      Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when the FormItem.itemHover() event would fire).

      When showOldValueInHover and the form's DynamicForm.showOldValueInHover are both unset, defaults to the value of showPending.

      The message shown is controlled by originalValueMessage, unless the item is disabled and disabledHover is set - in this case, the hover shows the disabledHover HTML.

      If the item suppresses hovers, nothing will be shown.

      Note : This is an advanced setting

      Parameters:
      showOldValueInHover - New showOldValueInHover value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getShowOldValueInHover

      public Boolean getShowOldValueInHover()
      Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when the FormItem.itemHover() event would fire).

      When showOldValueInHover and the form's DynamicForm.showOldValueInHover are both unset, defaults to the value of showPending.

      The message shown is controlled by originalValueMessage, unless the item is disabled and disabledHover is set - in this case, the hover shows the disabledHover HTML.

      If the item suppresses hovers, nothing will be shown.

      Returns:
      Current showOldValueInHover value. Default value is null
    • setShowOver

      public FormItem setShowOver(boolean showOver)
      When the user rolls over this item, should it be re-styled to indicate it has focus?

      When enabled, the "Over" styling is applied to the text box, control table (if present), and pickerIcon (if present), and any icons where FormItemIcon.showOver is true and FormItemIcon.showOverWhen is set to "textBox".
      These behaviors can be disabled piecemeal via updateTextBoxOnOver, updateControlOnOver and updatePickerIconOnOver properties.

      Developers may also show rollover styling for other icons (see showOverIcons and FormItemIcon.showOverWhen).

      See FormItemStyling for more details on formItem styling.

      Note : This is an advanced setting

      Parameters:
      showOver - New showOver value. Default value is false
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowOver

      public boolean getShowOver()
      When the user rolls over this item, should it be re-styled to indicate it has focus?

      When enabled, the "Over" styling is applied to the text box, control table (if present), and pickerIcon (if present), and any icons where FormItemIcon.showOver is true and FormItemIcon.showOverWhen is set to "textBox".
      These behaviors can be disabled piecemeal via updateTextBoxOnOver, updateControlOnOver and updatePickerIconOnOver properties.

      Developers may also show rollover styling for other icons (see showOverIcons and FormItemIcon.showOverWhen).

      See FormItemStyling for more details on formItem styling.

      Returns:
      Current showOver value. Default value is false
      See Also:
    • setShowOverIcons

      public FormItem setShowOverIcons(Boolean showOverIcons)
      If we're showing icons, should we change their image source to the appropriate over source when the user rolls over (or puts focus onto) them? Can be overridden on a per icon basis by the formItemIcon showOver property.

      Note : This is an advanced setting

      Parameters:
      showOverIcons - New showOverIcons value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
    • getShowOverIcons

      public Boolean getShowOverIcons()
      If we're showing icons, should we change their image source to the appropriate over source when the user rolls over (or puts focus onto) them? Can be overridden on a per icon basis by the formItemIcon showOver property.
      Returns:
      Current showOverIcons value. Default value is null
    • setShowPending

      public FormItem setShowPending(Boolean showPending)
      When set to true, this property adds the optional "Pending" suffix to the CSS styles applied to the widget if the current value of the item differs from the value that would be restored by invoking DynamicForm.resetValues(). See FormItemBaseStyle for details.

      shouldSaveValue must be true for this setting to have an effect.

      Styling of the value is updated only after the FormItem.change() event is processed, so depending on the value of changeOnKeypress, styling may be updated immediately on keystroke or only when the user leaves the field.

      Default styling is provided for the Enterprise, EnterpriseBlue, and Graphite skins only. showPending should not be enabled for an item when using a skin without default styling unless the default FormItem.pendingStatusChanged() behavior is canceled and a custom pending visual state is implemented by the item.

      On the other hand, when set to true and if canHover is also true, a hover will appear, displaying the old value and controlled by showOldValueInHover, originalValueMessage and nullOriginalValueText. Additionally, if the new value is clipped, it will be shown in the hover as well.

      NOTE: Whether an item is shown as pending is not reflected to screen readers. Therefore, it is not advisable to design a UI where it is necessary for the user to know whether an item is shown as pending in order to work with the form.

      Note : This is an advanced setting

      Parameters:
      showPending - New showPending value. Default value is null
      Returns:
      FormItem instance, for chaining setter calls
      See Also:
    • getShowPending

      public