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
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
static interface
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected boolean
protected String
protected boolean
protected static boolean
Fields inherited from class com.smartgwt.client.core.RefDataClass
id
Fields inherited from class com.smartgwt.client.core.DataClass
factoryCreated, factoryProperties
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddBlurHandler
(BlurHandler handler) Add a blur handler.addChangedHandler
(ChangedHandler handler) Add a changed handler.addChangeHandler
(ChangeHandler handler) Add a change handler.addClickHandler
(ClickHandler handler) Add a click handler.addDoubleClickHandler
(DoubleClickHandler handler) Add a doubleClick handler.addEditorEnterHandler
(EditorEnterHandler handler) Add a editorEnter handler.addEditorExitHandler
(EditorExitHandler handler) Add a editorExit handler.addFocusHandler
(FocusHandler handler) Add a focus handler.addIcon
(FormItemIcon icon) Adds aFormItemIcon
to this item.addIcon
(FormItemIcon icon, int index) Adds aFormItemIcon
to this item.addIconClickHandler
(IconClickHandler handler) Add a iconClick handler.Add a iconKeyPress handler.addItemHoverHandler
(ItemHoverHandler handler) Add a itemHover handler.addKeyDownHandler
(KeyDownHandler handler) Add a keyDown handler.addKeyPressHandler
(KeyPressHandler handler) Add a keyPress handler.addKeyUpHandler
(KeyUpHandler handler) Add a keyUp handler.Add a pendingStatusChanged handler.Add a pickerIconClick handler.Add a showContextMenu handler.addTitleClickHandler
(TitleClickHandler handler) Add a titleClick handler.Add a titleDoubleClick handler.addTitleHoverHandler
(TitleHoverHandler handler) Add a titleHover handler.addValueHoverHandler
(ValueHoverHandler handler) Add a valueHover handler.Add a valueIconClick handler.void
Manually sets this FormItem to the result offormula
ortextFormula
.static <T extends RefDataClass>
TasSGWTComponent
(JavaScriptObject jsObj) Returns the existing SGWT FormItem, or creates and returns one if none exist, associated with the suppliedJavaScriptObject
.void
blurItem()
Takes focus from this form item's focusable element.final Boolean
canEditCriterion
(Criterion criterion) Calls thecanEditCriterion()
method of theFormItemCanEditCriterionPredicate
that is registered with this field.static void
changeAutoChildDefaults
(String autoChildName, Canvas defaults) Changes the defaults for Canvas AutoChildren namedautoChildName
.static void
changeAutoChildDefaults
(String autoChildName, FormItem defaults) Changes the defaults for FormItem AutoChildren namedautoChildName
.static void
changePickerIconDefaults
(FormItemIcon defaults) static String
checkFormItemType
(String editorType) void
Clear all error messages for this itemvoid
Clear the value for this form item.void
disable()
Set this item to be disabled at runtime.void
disableIcon
(String icon) This method will disable some icon in this item'sicons
array, if it is currently enabled.void
enable()
Set this item to be enabled at runtime.void
enableIcon
(String icon) This method will enable some icon in this item'sicons
array, if it is currently disabled.protected final void
protected final void
protected final void
errorIfNotCreated
(String property) void
focusAfterItem
(boolean forward) Shifts focus to the next focusable element after this item, skipping any elements nested inside the tabbing group for this item, such as sub-elements, nested canvases in a CanvasItem, or icons.void
Move the keyboard focus into this item's focusable elementIf specified this governs the HTML accessKey for the item.getAlign()
Alignment of this item in its cell.For a form that produces filter criteria (seeform.getValuesAsCriteria()
), allows the user to type in simple expressions to cause filtering with that operator.If this form item has a specifiedoptionDataSource
andfetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related record ifdisplayField
is specified and the new item value is not present in any valueMap explicitly specified on the item.A formItem showing apickerIcon
will always write out a "control box" around the text box and picker icon.boolean
Ifheight
is specified, should it be applied to the item's text box element?ARIA role of this formItem.getAttribute
(String attribute) Returns attribute value as a StringgetAttributeAsBoolean
(String property) Returns attribute value set as a Boolean.getAttributeAsBoolean
(String property, boolean allowNull) Returns attribute value set as a Boolean.getAttributeAsDate
(String property) Returns attribute value as a Date.getAttributeAsDouble
(String property) Returns attribute as a Double.getAttributeAsFloat
(String property) Returns attribute value as a Float.getAttributeAsInt
(String property) Returns attribute value as an Integer.getAttributeAsJavaScriptObject
(String property) Returns attribute value as a JavaScript Object.getAttributeAsObject
(String property, JavaScriptObject convertToObject) getAttributeAsString
(String property) Returns attribute value as a String.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.String[]
Set of autocompletion keywords to be used with the native "autocomplete" attribute, in accordance with the HTML5 Autofill specification.Form item input type - governs which keyboard should be displayed for mobile devices (supported on iPhone / iPad)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.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.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.Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as aStaticTextItem
will cause the item to be included in the page's tab order and respond to keyboard events.Indicates whether hovers can be shown for this item.boolean
For items showing a text value, should the user be able to select the text in this item?Should this item'sicons
andpicker icon
be included in the page's tab order by default? If not explicitly set, this property will be derived fromDynamicForm.canTabToIcons
.final Canvas
getCanvasAutoChild
(String autoChildName) Returns theCanvas
AutoChild namedautoChildName
if already created.If specified, this property will govern the height of the cell in which this form item is rendered.CSS style applied to the form item as a whole, including the text element, any icons, and any hint text for the item.Should this form item fire itschange
handler (and store its value in the form) on every keypress? Set tofalse
to suppress the 'change' handler firing (and the value stored) on every keypress.Returns the JavaScript class name.If this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value be clipped if it overflows the specified size of the item? If set, overrides the form-levelDynamicForm.clipStaticValue
default.If the title for this form item is showing, and is too large for the available space should the title be clipped?Returns the FormItem's config object suitable for use in API's that set the editorTypeA Read-Only pointer to the Smart GWT canvas that holds this form item.Base CSS class name for a form item's "control box".final Criterion
Calls thegetCriterion()
method of theFormItemCriterionGetter
that is registered with this field.final Criterion
getCriterion
(TextMatchStyle textMatchStyle) Calls thegetCriterion()
method of theFormItemCriterionGetter
that is registered with this field.For text-based items, this method returns the index of the start of the current selection if the item currently has the focus (if no text is selected, this equates to the current position of the text editing cursor).getCustomState
(FormItemElementType elementType, String derivedState) Optional method to retrieve a custom state suffix to append to the style name that is applied to some element of a formItem - seeFormItemBaseStyle
for more information on how state-based FormItem style names are derived.dataPath for this item.Display format to use for date type values within this formItem.Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.Applies only to fields of type "float" and affects how many significant digits are shown.Default icon image source.The default search-operator for this item when it or its form allowfilter-expressions
.Value used when no value is provided for this item.The destroyed attribute will be set to true if this item has been destroyed() Note that FormItem lifecycle is managed by the DynamicForm itself.Deprecated.Do not use this API.This text is shown as a tooltip prompt when the cursor hovers over this item and the item isdisabled
orread-only
withreadOnlyDisplay:disabled
.If set, this item will display a value from another field to the user instead of showing the underlying data value for thefield name
.Returns thedisplayField
for this item.Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.getDisplayValue
(String value) Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.Custom CSS text to be applied to cells with pending edits that have not yet been submitted.Default class used to construct theEditProxy
for this component when the component isfirst placed into edit mode
.Text to display when this form item has a null or undefined value.This property allows the developer to specify an icon to display when this item has no value.Whether this item should end the row it's in in the form layoutint
Height of the error icon, if we're showing icons when validation errors occur.URL of the image to show as an error icon, if we're showing icons when validation errors occur.int
Height of the error icon, if we're showing icons when validation errors occur.int
WhenDynamicForm.showInlineErrors
andshowErrorText
are both true anderrorOrientation
is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon.String[]
Returns any validation errors for this field.Controls whether HTML item value(s) should be rendered or shown as HTML source.FormatString
used during exports for numeric or date formatting.If this form item has a specifiedoptionDataSource
, should the item ever perform a fetch against this dataSource to retrieve the related record.Return the name for the this formItem.If this form item is mapping data values to a display value by fetching records from a dataSource (seeoptionDataSource
,displayField
andfetchMissingValues
), 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.For items with anoptionDataSource
, this property specifies an explicit display field for records within the option dataSource.getForm()
A reference to the FormItem's DynamicForm.FormatString
for numeric or date formatting.final FormItem
getFormItemAutoChild
(String autoChildName) Returns theFormItem
AutoChild namedautoChildName
if already created.Formula to be used to calculate the numeric value of this FormItem.Return the fully-qualified dataPath for the this formItem (ie, the dataPath expressed in absolute terms from the root of the hierarchy, rather than relative to the item's parent form).TabIndex for the form item within the page.If this formItem is part of aListGrid
'sinline edit form
, returns the number of the grid column this formItem is responsible for editing, but only if a row is currently being edited.If this formItem is part of aListGrid
'sinline edit form
, returns the number of the row currently being edited.int
Height of the FormItem.Height of the FormItem.Should this form item be hidden? Setting this property totrue
on an item configuration will have the same effect as having ashowIf()
implementation which returnsfalse
.getHint()
Specifies "hint" string to show next to the form item to indicate something to the user.CSS class for the "hint" string.Text alignment for text displayed in this item's hover canvas, if shown.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 specifiedthis.form.itemHoverDelay
will be used instead.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).Option to specify a height for any hover shown for this item.Option to specify a height for any hover shown for this item.Opacity for any hover shown for this itemAllows interaction with hovers when the cursor is positioned over them.Explicit CSS Style for any hover shown for this item.Vertical text alignment for text displayed in this item's hover canvas, if shown.Option to specify a width for any hover shown for this item.Option to specify a width for any hover shown for this item.Given aFormItemIcon.name
, returns theFormItemIcon
object.Fallback base CSS class to apply to this item'sicons
if they don't specify abaseStyle
or provide a sprite-basedsrc string
that specifies acssClass
.int
Default height for form item icons.int
Horizontal space (in px) to leave between form item icons.getIconPageRect
(FormItemIcon icon) Default prompt (and tooltip-text) for icons.getIconRect
(FormItemIcon icon) getIcons()
An array of descriptor objects for icons to display in a line after this form item.Returns the desired tab-position of some icon with respect to other focusable sub-elements for this formItem.How should icons be aligned vertically for this form item.int
Default width for form item icons.getID()
Global identifier for referring to the formItem in JavaScript.Prefix to apply to the beginning of anyvalueIcons
when determining the URL for the image.Suffix to apply to the end of anyvalueIcons
when determining the URL for the image.When true, indicates that changes to this item will cause an automatic save on adelay
, as well as when the entire form is submitted.If set to true, this item's value will be saved immediately when its "editorExit" handler is fired.For fields of type"date"
, if this is an editable field such as aTextItem
, this property allows you to specify theinputFormat
applied to the item.int
getLeft()
Left coordinate of this item in pixels.int
Specifies a column span for an item inlinearMode
, overriding the default value of "*" in that mode.Specifies a column span for an item inlinearMode
, overriding the default value of "*" in that mode.int
int
int
Specifies a width for an item inlinearMode
, overriding the default width of "*" in that mode.Specifies a width for an item inlinearMode
, overriding the default width of "*" in that mode.If this item is being used to edit cells in a ListGrid (seeisInGrid()
), this method returns the grid in question.Value shown in field whenfetchMissingValues
is active and a fetch is pending.WhenAutoTest.getElement()
is used to parse locator strings generated byAutoTest.getLocator()
for this form item, should the item be identified? If the locator has a specifiedname
, it is considered to definitely locate the item and no fallback approach will be used.If this item is showing ahint
, this setting specifies how much horizontal space is made available for rendering the hint text by default.If true, multiple values may be selected.If this item is displaying multiple values, this property will be the string that separates those values for display purposes.getName()
Name for this form field.Text shown as the value in theoriginalValueMessage
whenshowOldValueInHover
is enabled, and when the value has been modified but was originally unset.OperatorId
to be used whenDynamicForm.getValuesAsCriteria()
is called.If this item has a specifiedoptionDataSource
, and this property may be used
 to specify criteria to pass to the datasource when
 performing the fetch operation on the dataSource to obtain a data-value to display-value
 mappingIf set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.If set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.If this item has a specifiedoptionDataSource
, and this property is
 not null, this will be passed to the datasource asRPCRequest
properties when
 performing the fetch operation on the dataSource to obtain a data-value to display-value
 mappingIf this item has a specifiedoptionDataSource
, this attribute may be set to specify an explicitDSRequest.operationId
when performing a fetch against the option dataSource to pick up display value mapping.If this item has a specifiedoptionDataSource
, this property determines the textMatchStyle to use when interpretating anyoptionCriteria
during the fetch to map valueField values to displayField values.static FormItem
getOrCreateRef
(JavaScriptObject jsObj) Message shown whenshowOldValueInHover
is enabled and the value has been modified.int
Returns the drawn page-left coordinate of this form item in pixels.Return the page-level coordinates of this object.int
Returns the drawn page-top coordinate of this form item in pixels.This method returns a Map of config properties suitable for use as the "defaults" attribute of aPaletteNode
.The component that will be displayed whenshowPicker()
is called due to a click on thepicker icon
.static FormItemIcon
getPickerIcon
(PickerIconName pickerName) Returns aFormItemIcon
for a standard picker with skin-specific settings.static FormItemIcon
getPickerIcon
(PickerIconName pickerName, FormItemIcon properties) Returns aFormItemIcon
for a standard picker with skin-specific settings.IfshowPickerIcon
is true for this item, this property governs the size of the picker icon.IfshowPickerIcon
is true, this attribute specifies theFormItemIcon.name
applied to the picker iconPrompt to show when the user hovers the mouse over the picker icon.IfshowPickerIcon
is true for this item, this block of properties will be applied to the pickerIcon.IfshowPickerIcon
is true for this item, this property governs thesrc
of the picker icon image to be displayed.Base CSS class name for a form item's picker icon cell.Returns the desired tab-position of the picker icon with respect to other focusable sub-elements for this formItem.IfshowPickerIcon
is true for this item, this property governs the size of the picker icon.int
Returns the specifiedheight
of this formItem in pixels.int
Returns the specifiedwidth
of this formItem in pixels.CSS class name to apply to the print view of an item's text box if the item iscanEdit:false
, withreadOnlyDisplay:static
.Base CSS class name for a form item's text box element when getting printable HTML for the form.Base CSS stylename for a form item's title when generating print HTML for the item.This text is shown as a tooltip prompt when the cursor hovers over this item.For items showing a text value withcanEdit
set to false, should the user be able to select the text in the item?Modifiedcontrol style
to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.If this item isread-only
, how should this item be displayed to the user? If set, overrides the form-levelDynamicForm.readOnlyDisplay
default.This text is shown as a tooltip prompt when the cursor hovers over this item and the item isread-only
.Base text box style to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.Criteria to be evaluated to determine whether this FormItem should be maderead-only
.getRect()
Return the coordinates of this object.If true, this item will cause the entire form to be redrawn when the item's "elementChanged" event is done firingIf 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.Whether a non-empty value is required for this field to pass validation.The required message for required field errors.Criteria to be evaluated to determine whether this FormItem should berequired
.int
Number of rows that this item spansSet this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem andsaveOnEnter
is true on the parent form.Get the name of the underlying SmartClient classGet the record returned from theoptionDataSource
whenfetchMissingValues
is true, and the missing value is fetched.Allows theselectOnClick
behavior to be configured on a per-FormItem basis.Allows theselectOnFocus
behavior to be configured on a per-FormItem basis.Should this item's value be saved in the form's values and hence returned fromform.getValues()
?boolean
If true and the title is clipped, then a hover containing the full title of this item is enabled.If true and the value is clipped, then a hover containing the full value of this item is enabled.For items that supportmultiple values
, this causes distinct CSS styling to be applied to values that the user has unselected.When this item is disabled, should it be re-styled to indicate its disabled state?IfshowIconsOnFocus
is true, should icons marked as disabled be shown on focus?IfshowPickerIconOnFocus
is true, should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?)showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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).When set to true, this attribute renders theerror-icon
inline
in the FormItem, next to other icons, instead of in a separate error-element outside of the item's main editor.showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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).showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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).When this item receives focus, should it be re-styled to indicate it has focus?If set to true, when an item has errors and is focused, an "ErrorFocused" suffix will appear on the stylename.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 formItemIconshowFocused
property.IfshowPickerIcon
is true for this item, should the picker icon show a focused image when the form item has focus?If a hint is defined for this form item, should it be shown?Set to false to suppress writing out anyicons
for this item.Show theicons
when the item gets focus, and hide them when it loses focus.For fields oftype:"image"
, if the field is non editable, and being displayed withreadOnlyDisplay:"static"
, should the value (URL) be displayed as text, or should an image be rendered?Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when theFormItem.itemHover()
event would fire).boolean
When the user rolls over this item, should it be re-styled to indicate it has focus?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 formItemIconshowOver
property.When set totrue
, 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 invokingDynamicForm.resetValues()
.Should we show a special 'picker'icon
for this form item? Picker icons are customizable viapickerIconProperties
.Show the picker icon when the item gets focus, and hide it when it loses focus.boolean
When this item is in RTL mode, should its style name include an "RTL" suffix?Should we show a title cell for this formItem?IfvalueIcons
is set, this property may be set to show the valueIcon only and prevent the standard form item element or text from displayingWhether this item should always start a new row in the form layout.Height of the FormItem whencanEdit
is false andreadOnlyDisplay
is "static".Indicates that if validation fails, the user should not be allowed to exit the field - focus will be forced back into the field until the error is corrected.If specified, this overrides theDynamicForm.storeDisplayValues
property for this field.boolean
Does the current formItem support native cut and paste events?IfvalueIcons
is set, this property may be set to prevent the value icons from showing up next to the form items valueIf enabled, whenever validation is triggered and a request to the server is required, user interactivity will be blocked until the request returns.TabIndex for the form item within the form, which controls the order in which controls are visited when the user hits the tab or shift-tab keys to navigate between items.Alignment of the text / content within this form item.Base CSS class name for a form item's text box element.Formula to be used to calculate the text value of this FormItem.Time-format to apply to date type values within this formItem.getTitle()
User visible title for this form item.Alignment of this item's title in its cell.int
Number of columns that this item's title spans.On which side of this item should the title be placed.Base CSS class name for a regular form-item's title.Vertical alignment of this item's title in its cell.This text is shown as a tooltip prompt when the cursor hovers over this item.int
getTop()
Top coordinate of this item in pixels.getType()
The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the field).IfshowOver
is true, setting this property to false will explicitly disable showing the "Over" state for the control table element of this item (if present).IfshowOver
is true, setting this property to false will explicitly disable showing the "Over" state for the PickerIcon of this item (if present)IfshowOver
is true, setting this property to false will explicitly disable showing the "Over" state for the TextBox element of this item.Should this form item always produce anAdvancedCriteria
sub criterion object? When set to true, causeshasAdvancedCriteria
to return true.By default,read-only
fields use the same style name as editable fields for in-field hints, unless they aredisabled
or configured to use a disabledReadOnlyDisplayAppearance
.IfdisplayField
is specified for a field, should the display value for the field be picked up from therecord currently being edited
?If true, form items will be validated when each item's "change" handler is fired as well as when the entire form is submitted or validated.If true, form items will be validated when each item's "editorExit" handler is fired as well as when the entire form is submitted or validated.Array of valid filtering operators (eg "greaterThan") that are legal for this FormItem.Vertical alignment of this item within its cell.getValue()
Return the value tracked by this form item.Return the value tracked by this form item as a Float.Return the value tracked by this form item as an Integer.Return the value tracked by this form item as a Long.Custom CSS text to be applied to values that have been deleted, whenshowDeletions
is enabled.If this form item maps data values to display values by retrieving thedisplayField
values from anoptionDataSource
, this property denotes the the field to use as the underlying data value in records from the optionDataSource.
If not explicitly supplied, the valueField name will be derived as described ingetValueFieldName()
.Getter method to retrieve thevalueField
for this item.IfvalueIcons
is specified, use this property to specify a height for the value icon written out.int
If we're showing a value icon, this attribute governs the amount of space between the icon and the start edge of the form item cell.int
If we're showing a value icon, this attribute governs the amount of space between the icon and the value text.int
IfvalueIcons
is specified, this property may be used to specify both the width and height of the icon written out.IfvalueIcons
is specified, use this property to specify a width for the value icon written out.In a form, valueMaps are used for FormItem types that allow the user to pick from a limited set of values, such as aSelectItem
.String[]
See alsogetValueMap()
Whether this item is currently visible.int
Output the drawn height for this item in pixels.int
getVisibleTitleWidth
(Boolean labelOnly) Returns the visible width of this item's title in px.Criteria to be evaluated to determine whether this FormItem should be visible.int
Output the drawn width for this item in pixels.boolean
Gets whether a warning will be logged if the Framework replaces this SmartGWT FormItem (that wraps the SmartClient item instance) to more closely match the underlying item's type.static boolean
Gets whether, by default, a warning will be logged if the Framework replaces a SmartGWT FormItem (that wraps the SmartClient item instance) to more closely match the underlying item's type.int
getWidth()
Width of the FormItem.Width of the FormItem.If this item is showing ahint
, should the hint text be allowed to wrap? Setting this property tofalse
will render the hint on a single line without wrapping, expanding the width required to render the item if necessary.If this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value wrap?If specified determines whether this items title should wrap.void
handleWarnOnEditorTypeConversion
(FormItem oldItem, FormItem newItem) Does this form item produce anAdvancedCriteria
sub criterion object? If this method returns true,DynamicForm.getValuesAsCriteria()
on the form containing this item will always return anAdvancedCriteria
object, callingFormItemCriterionGetter.getCriterion()
on each item to retrieve the individual criteria.boolean
Return whether this item currently has any validation errors as a result of a previous validation pass.void
hide()
Hide this form item.void
This method will hide some icon in this item'sicons
array, if it is currently visible.void
If this item has a specifieddisplayField
, the value displayed to the user for this item may be derived from another field.static boolean
isAssignableFrom
(Class<?> scClass) Whether the supplied class is a subclass ofcom.smartgwt.client.form.fields.FormItem
.boolean
final boolean
boolean
Is the user performing a native "cut" event to modify the value of a freeform text field? This method may be invoked during change notification flow methods includingFormItem.change()
,FormItem.changed()
andFormItem.transformInput()
.Is this item disabled?isDrawn()
Returns true if this item has been written out into the DOM.Returns true if this formItem has the keyboard focus.isInGrid()
Returns true if this item'scontainerWidget
is aGridRenderer
or GridRenderer subclassboolean
Is the user performing a native "paste" event to modify the value of a freeform text field? This method may be invoked during change notification flow methods includingFormItem.change()
,FormItem.changed()
andFormItem.transformInput()
.Return true if the form item is currently visible.void
mapDisplayToValue
(String value) Given a display value for this FormItem, return the underlying data value.mapValueToDisplay
(Object value) mapValueToDisplay
(Map value) Given a value for this FormItem, return the value to be displayed.void
redraw()
Redraw this form item.void
Redraw this form item.boolean
removeIcon
(String icon) Given an icon'sname
, remove it from this item.void
selectedRecordChanged
(ListGridRecord record) Notification method fired fordata bound items
withfetchMissingValues
enabled when theselected record
is updated as a result of the value changing or a fetch for a new record completing.
Note that a formItem with an optionDataSource may avoid fetching an associated record altogether in some cases.setAccessKey
(String accessKey) If specified this governs the HTML accessKey for the item.Alignment of this item in its cell.setAllowExpressions
(Boolean allowExpressions) For a form that produces filter criteria (seeform.getValuesAsCriteria()
), allows the user to type in simple expressions to cause filtering with that operator.setAlwaysFetchMissingValues
(Boolean alwaysFetchMissingValues) If this form item has a specifiedoptionDataSource
andfetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related record ifdisplayField
is specified and the new item value is not present in any valueMap explicitly specified on the item.setAlwaysShowControlBox
(Boolean alwaysShowControlBox) A formItem showing apickerIcon
will always write out a "control box" around the text box and picker icon.setApplyAlignToText
(boolean applyAlignToText) setApplyHeightToTextBox
(Boolean applyHeightToTextBox) Ifheight
is specified, should it be applied to the item's text box element?setAriaRole
(String ariaRole) ARIA role of this formItem.void
setAriaState
(String stateName, Object stateValue) Set a specific ARIA state mapping for this form item.setAttribute
(String attribute, boolean value) Set attribute value to a boolean.setAttribute
(String attribute, double value) Set attribute value to a double.setAttribute
(String attribute, double[] value) Set attribute value to a double array.setAttribute
(String attribute, int value) Set attribute value to an int.setAttribute
(String attribute, int[] value) Set attribute value to an int array.setAttribute
(String attribute, long value) Set attribute value to a long.setAttribute
(String attribute, JavaScriptObject value) Set attribute value to a JavaScriptObject.setAttribute
(String attribute, BaseClass value) Set attribute value to a BaseClass.setAttribute
(String attribute, BaseClass[] value) Set attribute value to a BaseClass array.setAttribute
(String attribute, DataClass value) Set attribute value to a DataClass.setAttribute
(String attribute, DataClass[] value) Set attribute value to a DataClass array.setAttribute
(String attribute, ValueEnum[] value) Set attribute value to a ValueEnum array.setAttribute
(String attribute, Boolean value) Set attribute value to a Boolean.setAttribute
(String attribute, Double value) Set attribute value to a Double.setAttribute
(String attribute, Float value) Set attribute value to a Float.setAttribute
(String attribute, Integer value) Set attribute value to an Integer.setAttribute
(String attribute, Integer[] value) Set attribute value to an Integer array.setAttribute
(String attribute, String value) Set attribute value to a StringsetAttribute
(String attribute, String[] value) Set attribute value to a String array.setAttribute
(String attribute, Date value) Set attribute value to a Date.setAttribute
(String attribute, Map value) Set attribute value to a Map.void
setAutoChildConstructor
(String autoChildName, String className) Sets the SmartClient constructor for the AutoChild namedautoChildName
.void
setAutoChildProperties
(String autoChildName, EditProxy properties) Sets the properties for creating an AutoChild namedautoChildName
.void
setAutoChildProperties
(String autoChildName, Canvas properties) Sets the properties for creating aCanvas
AutoChild namedautoChildName
.void
setAutoChildProperties
(String autoChildName, FormItem properties) Sets the properties for creating aFormItem
AutoChild namedautoChildName
.void
setAutoChildVisibility
(String autoChildName, boolean visible) Sets whether to create and show the AutoChild namedautoChildName
.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.setAutoCompleteKeywords
(String... autoCompleteKeywords) Set of autocompletion keywords to be used with the native "autocomplete" attribute, in accordance with the HTML5 Autofill specification.setBrowserInputType
(String browserInputType) Form item input type - governs which keyboard should be displayed for mobile devices (supported on iPhone / iPad)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.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.void
When a dynamic form is editing an advanced criteria object viaDynamicForm.setValuesAsCriteria
, this predicate is used to determine which sub-criteria apply to which form item(s).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.setCanFocus
(Boolean canFocus) Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as aStaticTextItem
will cause the item to be included in the page's tab order and respond to keyboard events.setCanHover
(Boolean canHover) Indicates whether hovers can be shown for this item.setCanSelectText
(boolean canSelectText) For items showing a text value, should the user be able to select the text in this item?setCanTabToIcons
(Boolean canTabToIcons) Should this item'sicons
andpicker icon
be included in the page's tab order by default? If not explicitly set, this property will be derived fromDynamicForm.canTabToIcons
.setCellHeight
(Integer cellHeight) If specified, this property will govern the height of the cell in which this form item is rendered.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.setChangeOnKeypress
(Boolean changeOnKeypress) Should this form item fire itschange
handler (and store its value in the form) on every keypress? Set tofalse
to suppress the 'change' handler firing (and the value stored) on every keypress.setClipStaticValue
(Boolean clipStaticValue) If this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value be clipped if it overflows the specified size of the item? If set, overrides the form-levelDynamicForm.clipStaticValue
default.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?setColSpan
(int colSpan) Number of columns that this item spans.setColSpan
(String colSpan) Number of columns that this item spans.void
setConfigOnly
(boolean configOnly) setControlStyle
(String controlStyle) Base CSS class name for a form item's "control box".setCriteriaField
(String criteriaField) final void
setCriterion
(Criterion criterion) Calls thesetCriterion()
method of theFormItemCriterionSetter
that is registered with this field.void
Provides a specialized criterion from this formItem when creating an AdvancedCriteria viaDynamicForm.getValuesAsCriteria
.void
Set the method to update this form item to reflect a criterion object from within an AdvancedCriteria.void
Deprecated.Do not use CustomStateGetter; usecom.smartgwt.client.widgets.form.fields.FormItem.setStateCustomizer
insteadsetDataPath
(String dataPath) dataPath for this item.setDateFormatter
(DateDisplayFormat dateFormatter) Display format to use for date type values within this formItem.setDecimalPad
(Integer decimalPad) Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.setDecimalPrecision
(Integer decimalPrecision) Applies only to fields of type "float" and affects how many significant digits are shown.setDefaultIconSrc
(String defaultIconSrc) Default icon image source.setDefaultOperator
(OperatorId defaultOperator) The default search-operator for this item when it or its form allowfilter-expressions
.static void
setDefaultProperties
(FormItem formItemProperties) Class level method to set the default properties of this class.setDefaultValue
(Boolean defaultValue) Value used when no value is provided for this item.setDefaultValue
(Double defaultValue) Value used when no value is provided for this item.setDefaultValue
(Float defaultValue) Value used when no value is provided for this item.setDefaultValue
(Integer defaultValue) Value used when no value is provided for this item.void
setDefaultValue
(Object value) setDefaultValue
(String defaultValue) Value used when no value is provided for this item.setDefaultValue
(Date defaultValue) Value used when no value is provided for this item.setDisabled
(Boolean disabled) Whether this item is disabled.setDisabledHover
(String disabledHover) This text is shown as a tooltip prompt when the cursor hovers over this item and the item isdisabled
orread-only
withreadOnlyDisplay:disabled
.setDisableIconsOnReadOnly
(Boolean disableIconsOnReadOnly) 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 thefield name
.setDisplayFormat
(DateDisplayFormat displayFormat) void
setDisplayFormat
(TimeFormatter displayFormat) void
setEditorProperties
(FormItem editorProperties) Set the defaultFormItem
properties to be used whenever this field is edited.void
setEditorType
(FormItem editorType) Deprecated.Renamed tosetEditorProperties(FormItem)
.void
setEditorType
(Class<? extends FormItem> editorType) Set the FormItem subclass to use when editing.void
setEditorType
(String editorType) Set the FormItem subclass to use when editing.void
setEditorValueFormatter
(FormItemValueFormatter formatter) An optionalFormItemValueFormatter
to map this item's current data value to a display value.void
setEditorValueParser
(FormItemValueParser valueParser) An optionalFormItemValueParser
to map a user-entered display value to a data value for storage.setEditPendingCSSText
(String editPendingCSSText) Custom CSS text to be applied to cells with pending edits that have not yet been submitted.setEditProxyConstructor
(String editProxyConstructor) Default class used to construct theEditProxy
for this component when the component isfirst placed into edit mode
.setEmptyDisplayValue
(String emptyDisplayValue) Text to display when this form item has a null or undefined value.setEmptyValueIcon
(String emptyValueIcon) This property allows the developer to specify an icon to display when this item has no value.Whether this item should end the row it's in in the form layoutvoid
setErrorFormatter
(FormItemErrorFormatter errorFormatter) Register a custom error formatter for this FormItem.setErrorIconHeight
(int errorIconHeight) Height of the error icon, if we're showing icons when validation errors occur.setErrorIconProperties
(FormItemIcon errorIconProperties) setErrorIconSrc
(String errorIconSrc) URL of the image to show as an error icon, if we're showing icons when validation errors occur.setErrorIconWidth
(int errorIconWidth) Height of the error icon, if we're showing icons when validation errors occur.setErrorMessageWidth
(int errorMessageWidth) WhenDynamicForm.showInlineErrors
andshowErrorText
are both true anderrorOrientation
is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon.void
setErrorOrientation
(FormErrorOrientation errorOrientation) IfshowInlineErrors
is true, where should the error icon and text appear relative to the form item itself.void
Sets a validation error message for this field.void
Sets multiple validation error messages for this field.setEscapeHTML
(Boolean escapeHTML) Controls whether HTML item value(s) should be rendered or shown as HTML source.setExportFormat
(String exportFormat) FormatString
used during exports for numeric or date formatting.setFetchMissingValues
(Boolean fetchMissingValues) If this form item has a specifiedoptionDataSource
, should the item ever perform a fetch against this dataSource to retrieve the related record.setFilterLocally
(Boolean filterLocally) If this form item is mapping data values to a display value by fetching records from a dataSource (seeoptionDataSource
,displayField
andfetchMissingValues
), 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.setForeignDisplayField
(String foreignDisplayField) For items with anoptionDataSource
, this property specifies an explicit display field for records within the option dataSource.FormatString
for numeric or date formatting.setFormula
(UserFormula formula) Formula to be used to calculate the numeric value of this FormItem.setGlobalTabIndex
(Integer globalTabIndex) TabIndex for the form item within the page.setHeight
(int height) Height of the FormItem.Height of the FormItem.Should this form item be hidden? Setting this property totrue
on an item configuration will have the same effect as having ashowIf()
implementation which returnsfalse
.Specifies "hint" string to show next to the form item to indicate something to the user.setHintStyle
(String hintStyle) CSS class for the "hint" string.setHoverAlign
(Alignment hoverAlign) Text alignment for text displayed in this item's hover canvas, if shown.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 specifiedthis.form.itemHoverDelay
will be used instead.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).setHoverHeight
(Integer hoverHeight) Option to specify a height for any hover shown for this item.setHoverHeight
(String hoverHeight) Option to specify a height for any hover shown for this item.setHoverOpacity
(Integer hoverOpacity) Opacity for any hover shown for this itemsetHoverPersist
(HoverPersistMode hoverPersist) Allows interaction with hovers when the cursor is positioned over them.setHoverStyle
(String hoverStyle) Explicit CSS Style for any hover shown for this item.setHoverVAlign
(VerticalAlignment hoverVAlign) Vertical text alignment for text displayed in this item's hover canvas, if shown.setHoverWidth
(Integer hoverWidth) Option to specify a width for any hover shown for this item.setHoverWidth
(String hoverWidth) Option to specify a width for any hover shown for this item.setIconBaseStyle
(String iconBaseStyle) Fallback base CSS class to apply to this item'sicons
if they don't specify abaseStyle
or provide a sprite-basedsrc string
that specifies acssClass
.void
setIconDisabled
(String icon, boolean disabled) Set an icon as enabled or disabled at runtime.setIconHeight
(int iconHeight) Default height for form item icons.setIconHSpace
(int iconHSpace) Horizontal space (in px) to leave between form item icons.setIconPrompt
(String iconPrompt) Default prompt (and tooltip-text) for icons.setIcons
(FormItemIcon... icons) An array of descriptor objects for icons to display in a line after this form item.void
setIconShowOnFocus
(String icon, Boolean showOnFocus) SetsFormItemIcon.showOnFocus
for the supplied icon, and causes that icon's visibility to be updated and the item redrawn as appropriate.setIconVAlign
(VerticalAlignment iconVAlign) How should icons be aligned vertically for this form item.setIconWidth
(int iconWidth) Default width for form item icons.Global identifier for referring to the formItem in JavaScript.setImageURLPrefix
(String imageURLPrefix) Prefix to apply to the beginning of anyvalueIcons
when determining the URL for the image.setImageURLSuffix
(String imageURLSuffix) Suffix to apply to the end of anyvalueIcons
when determining the URL for the image.setImplicitSave
(Boolean implicitSave) When true, indicates that changes to this item will cause an automatic save on adelay
, as well as when the entire form is submitted.setImplicitSaveOnBlur
(Boolean implicitSaveOnBlur) If set to true, this item's value will be saved immediately when its "editorExit" handler is fired.void
setInitHandler
(FormItemInitHandler initHandler) Specify a notification method to fire when this formItem is initialized in JavaScript.setInputFormat
(String inputFormat) For fields of type"date"
, if this is an editable field such as aTextItem
, this property allows you to specify theinputFormat
applied to the item.void
setInputTransformer
(FormItemInputTransformer inputTransformer) The transformer is called when a FormItem's value is about to change as the result of user interaction.void
setItemHoverFormatter
(FormItemHoverFormatter hoverFormatter) The FormItemHoverFormatter should return the HTML to display in a hover canvas when the user holds the mousepointer over this item.void
setItemTitleHoverFormatter
(FormItemHoverFormatter hoverFormatter) TheFormItemHoverFormatter
should return the HTML to display in a hover canvas when the user holds the mouse pointer over this item's title and the title is clipped.void
setItemValueHoverFormatter
(FormItemHoverFormatter hoverFormatter) TheFormItemHoverFormatter
should return the HTML to display in a hover canvas when the user holds the mouse pointer over this item's value and the value is clipped.final void
setLeft
(int left) Left coordinate of this item in pixels.setLinearColSpan
(int linearColSpan) Specifies a column span for an item inlinearMode
, overriding the default value of "*" in that mode.setLinearColSpan
(String linearColSpan) Specifies a column span for an item inlinearMode
, overriding the default value of "*" in that mode.setLinearEndRow
(int linearEndRow) setLinearEndRow
(String linearEndRow) setLinearStartRow
(int linearStartRow) setLinearStartRow
(String linearStartRow) setLinearWidth
(int linearWidth) Specifies a width for an item inlinearMode
, overriding the default width of "*" in that mode.setLinearWidth
(String linearWidth) Specifies a width for an item inlinearMode
, overriding the default width of "*" in that mode.setLoadingDisplayValue
(String loadingDisplayValue) Value shown in field whenfetchMissingValues
is active and a fetch is pending.setLocateItemBy
(String locateItemBy) WhenAutoTest.getElement()
is used to parse locator strings generated byAutoTest.getLocator()
for this form item, should the item be identified? If the locator has a specifiedname
, it is considered to definitely locate the item and no fallback approach will be used.setMinHintWidth
(Integer minHintWidth) If this item is showing ahint
, this setting specifies how much horizontal space is made available for rendering the hint text by default.setMultiple
(Boolean multiple) If true, multiple values may be selected.setMultipleValueSeparator
(String multipleValueSeparator) If this item is displaying multiple values, this property will be the string that separates those values for display purposes.Name for this form field.setNullOriginalValueText
(String nullOriginalValueText) Text shown as the value in theoriginalValueMessage
whenshowOldValueInHover
is enabled, and when the value has been modified but was originally unset.void
setNullProperty
(String property) setOperator
(OperatorId operator) OperatorId
to be used whenDynamicForm.getValuesAsCriteria()
is called.void
setOptionCriteria
(Criteria optionCriteria) If this item has a specifiedoptionDataSource
, and this property may be used
 to specify criteria to pass to the datasource when
 performing the fetch operation on the dataSource to obtain a data-value to display-value
 mappingsetOptionDataSource
(DataSource optionDataSource) If set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.setOptionDataSource
(String optionDataSource) If set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
in loaded records, to derive one valueMap entry per record loaded from the optionDataSource.void
setOptionFilterContext
(RPCRequest rpcRequestProperties) If this item has a specifiedoptionDataSource
, and this property is
 not null, this will be passed to the datasource asRPCRequest
properties when
 performing the fetch operation on the dataSource to obtain a data-value to display-value
 mappingsetOptionOperationId
(String optionOperationId) If this item has a specifiedoptionDataSource
, this attribute may be set to specify an explicitDSRequest.operationId
when performing a fetch against the option dataSource to pick up display value mapping.setOptionTextMatchStyle
(TextMatchStyle optionTextMatchStyle) If this item has a specifiedoptionDataSource
, this property determines the textMatchStyle to use when interpretating anyoptionCriteria
during the fetch to map valueField values to displayField values.setOriginalValueMessage
(String originalValueMessage) Message shown whenshowOldValueInHover
is enabled and the value has been modified.setPickerIconHeight
(Integer pickerIconHeight) IfshowPickerIcon
is true for this item, this property governs the size of the picker icon.setPickerIconName
(String pickerIconName) IfshowPickerIcon
is true, this attribute specifies theFormItemIcon.name
applied to the picker iconsetPickerIconPrompt
(String pickerIconPrompt) Prompt to show when the user hovers the mouse over the picker icon.setPickerIconProperties
(FormItemIcon pickerIconProperties) IfshowPickerIcon
is true for this item, this block of properties will be applied to the pickerIcon.setPickerIconSrc
(String pickerIconSrc) IfshowPickerIcon
is true for this item, this property governs thesrc
of the picker icon image to be displayed.setPickerIconStyle
(String pickerIconStyle) Base CSS class name for a form item's picker icon cell.setPickerIconWidth
(Integer pickerIconWidth) IfshowPickerIcon
is true for this item, this property governs the size of the picker icon.setPrintReadOnlyTextBoxStyle
(String printReadOnlyTextBoxStyle) CSS class name to apply to the print view of an item's text box if the item iscanEdit:false
, withreadOnlyDisplay:static
.setPrintTextBoxStyle
(String printTextBoxStyle) Base CSS class name for a form item's text box element when getting printable HTML for the form.setPrintTitleStyle
(String printTitleStyle) Base CSS stylename for a form item's title when generating print HTML for the item.This text is shown as a tooltip prompt when the cursor hovers over this item.void
setProperty
(String property, boolean value) void
setProperty
(String property, double value) void
setProperty
(String property, int value) void
setProperty
(String property, JavaScriptObject value) void
setProperty
(String property, String value) setReadOnlyCanSelectText
(ReadOnlyDisplayAppearance... readOnlyCanSelectText) For items showing a text value withcanEdit
set to false, should the user be able to select the text in the item?setReadOnlyControlStyle
(String readOnlyControlStyle) Modifiedcontrol style
to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.setReadOnlyDisplay
(ReadOnlyDisplayAppearance readOnlyDisplay) If this item isread-only
, how should this item be displayed to the user? If set, overrides the form-levelDynamicForm.readOnlyDisplay
default.setReadOnlyHover
(String readOnlyHover) This text is shown as a tooltip prompt when the cursor hovers over this item and the item isread-only
.setReadOnlyTextBoxStyle
(String readOnlyTextBoxStyle) Base text box style to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.setReadOnlyWhen
(AdvancedCriteria readOnlyWhen) Criteria to be evaluated to determine whether this FormItem should be maderead-only
.setRedrawOnChange
(Boolean redrawOnChange) If true, this item will cause the entire form to be redrawn when the item's "elementChanged" event is done firingsetRejectInvalidValueOnChange
(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.setRequired
(Boolean required) Whether a non-empty value is required for this field to pass validation.setRequiredMessage
(String requiredMessage) The required message for required field errors.setRequiredWhen
(Criteria requiredWhen) Criteria to be evaluated to determine whether this FormItem should berequired
.setRowSpan
(int rowSpan) Number of rows that this item spanssetSaveOnEnter
(Boolean saveOnEnter) Set this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem andsaveOnEnter
is true on the parent form.void
setScClassName
(String scClassName) Set the name of the underlying SmartClient class.setSelectOnClick
(Boolean selectOnClick) Allows theselectOnClick
behavior to be configured on a per-FormItem basis.setSelectOnFocus
(Boolean selectOnFocus) Allows theselectOnFocus
behavior to be configured on a per-FormItem basis.setShouldSaveValue
(Boolean shouldSaveValue) Should this item's value be saved in the form's values and hence returned fromform.getValues()
?setShowClippedTitleOnHover
(boolean showClippedTitleOnHover) If true and the title is clipped, then a hover containing the full title of this item is enabled.setShowClippedValueOnHover
(Boolean showClippedValueOnHover) If true and the value is clipped, then a hover containing the full value of this item is enabled.setShowDeletions
(Boolean showDeletions) For items that supportmultiple values
, this causes distinct CSS styling to be applied to values that the user has unselected.setShowDisabled
(Boolean showDisabled) When this item is disabled, should it be re-styled to indicate its disabled state?setShowDisabledIconsOnFocus
(Boolean showDisabledIconsOnFocus) IfshowIconsOnFocus
is true, should icons marked as disabled be shown on focus?setShowDisabledPickerIconOnFocus
(Boolean showDisabledPickerIconOnFocus) IfshowPickerIconOnFocus
is true, should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?)setShowErrorIcon
(Boolean showErrorIcon) showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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).setShowErrorIconInline
(Boolean showErrorIconInline) When set to true, this attribute renders theerror-icon
inline
in the FormItem, next to other icons, instead of in a separate error-element outside of the item's main editor.setShowErrorStyle
(Boolean showErrorStyle) showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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).setShowErrorText
(Boolean showErrorText) showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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).setShowFocused
(Boolean showFocused) When this item receives focus, should it be re-styled to indicate it has focus?setShowFocusedErrorState
(Boolean showFocusedErrorState) If set to true, when an item has errors and is focused, an "ErrorFocused" suffix will appear on the stylename.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 formItemIconshowFocused
property.setShowFocusedPickerIcon
(Boolean showFocusedPickerIcon) IfshowPickerIcon
is true for this item, should the picker icon show a focused image when the form item has focus?setShowHint
(Boolean showHint) If a hint is defined for this form item, should it be shown?setShowIcons
(Boolean showIcons) Set to false to suppress writing out anyicons
for this item.setShowIconsOnFocus
(Boolean showIconsOnFocus) Show theicons
when the item gets focus, and hide them when it loses focus.void
setShowIfCondition
(FormItemIfFunction showIf) Expression that's evaluated to see if an item should be dynamically hidden.setShowImageAsURL
(Boolean showImageAsURL) For fields oftype:"image"
, if the field is non editable, and being displayed withreadOnlyDisplay:"static"
, should the value (URL) be displayed as text, or should an image be rendered?setShowOldValueInHover
(Boolean showOldValueInHover) Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when theFormItem.itemHover()
event would fire).setShowOver
(boolean showOver) When the user rolls over this item, should it be re-styled to indicate it has focus?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 formItemIconshowOver
property.setShowPending
(Boolean showPending) When set totrue
, 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 invokingDynamicForm.resetValues()
.setShowPickerIcon
(Boolean showPickerIcon) Should we show a special 'picker'icon
for this form item? Picker icons are customizable viapickerIconProperties
.setShowPickerIconOnFocus
(Boolean showPickerIconOnFocus) Show the picker icon when the item gets focus, and hide it when it loses focus.setShowRTL
(boolean showRTL) When this item is in RTL mode, should its style name include an "RTL" suffix?setShowTitle
(Boolean showTitle) Should we show a title cell for this formItem?setShowValueIconOnly
(Boolean showValueIconOnly) IfvalueIcons
is set, this property may be set to show the valueIcon only and prevent the standard form item element or text from displayingsetStartRow
(Boolean startRow) Whether this item should always start a new row in the form layout.void
setStateCustomizer
(FormItem.StateCustomizer customizer) Specify a StateCustomizer to use for this formItem.setStaticHeight
(Integer staticHeight) Height of the FormItem whencanEdit
is false andreadOnlyDisplay
is "static".setStopOnError
(Boolean stopOnError) Indicates that if validation fails, the user should not be allowed to exit the field - focus will be forced back into the field until the error is corrected.setStoreDisplayValues
(Boolean storeDisplayValues) If specified, this overrides theDynamicForm.storeDisplayValues
property for this field.setSupportsCutPasteEvents
(boolean supportsCutPasteEvents) Does the current formItem support native cut and paste events?setSuppressValueIcon
(Boolean suppressValueIcon) IfvalueIcons
is set, this property may be set to prevent the value icons from showing up next to the form items valuesetSynchronousValidation
(Boolean synchronousValidation) If enabled, whenever validation is triggered and a request to the server is required, user interactivity will be blocked until the request returns.setTabIndex
(Integer tabIndex) TabIndex for the form item within the form, which controls the order in which controls are visited when the user hits the tab or shift-tab keys to navigate between items.setTextAlign
(Alignment textAlign) Alignment of the text / content within this form item.setTextBoxStyle
(String textBoxStyle) Base CSS class name for a form item's text box element.setTextFormula
(UserSummary textFormula) Formula to be used to calculate the text value of this FormItem.setTimeFormatter
(TimeDisplayFormat timeFormatter) Time-format to apply to date type values within this formItem.User visible title for this form item.setTitleAlign
(Alignment titleAlign) Alignment of this item's title in its cell.setTitleColSpan
(int titleColSpan) Number of columns that this item's title spans.void
setTitleHoverFormatter
(FormItemHoverFormatter hoverFormatter) Synonym forsetItemTitleHoverFormatter(FormItemHoverFormatter)
.setTitleOrientation
(TitleOrientation titleOrientation) On which side of this item should the title be placed.setTitleStyle
(String titleStyle) Base CSS class name for a regular form-item's title.setTitleVAlign
(VerticalAlignment titleVAlign) Vertical alignment of this item's title in its cell.void
setTooltip
(String tooltip) This text is shown as a tooltip prompt when the cursor hovers over this item.setTop
(int top) Top coordinate of this item in pixels.void
The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the field).setUpdateControlOnOver
(Boolean updateControlOnOver) IfshowOver
is true, setting this property to false will explicitly disable showing the "Over" state for the control table element of this item (if present).setUpdatePickerIconOnOver
(Boolean updatePickerIconOnOver) IfshowOver
is true, setting this property to false will explicitly disable showing the "Over" state for the PickerIcon of this item (if present)setUpdateTextBoxOnOver
(Boolean updateTextBoxOnOver) IfshowOver
is true, setting this property to false will explicitly disable showing the "Over" state for the TextBox element of this item.setUseAdvancedCriteria
(Boolean useAdvancedCriteria) Should this form item always produce anAdvancedCriteria
sub criterion object? When set to true, causeshasAdvancedCriteria
to return true.setUseDisabledHintStyleForReadOnly
(Boolean useDisabledHintStyleForReadOnly) By default,read-only
fields use the same style name as editable fields for in-field hints, unless they aredisabled
or configured to use a disabledReadOnlyDisplayAppearance
.setUseLocalDisplayFieldValue
(Boolean useLocalDisplayFieldValue) IfdisplayField
is specified for a field, should the display value for the field be picked up from therecord currently being edited
?static void
setUseObjectFactoryForTypeFallback
(boolean useFallback) Configures whether we useObjectFactory
as a fallback for resolving editorType class names forsetEditorType(java.lang.String)
if Reflection is not available for the type.setValidateOnChange
(Boolean validateOnChange) If true, form items will be validated when each item's "change" handler is fired as well as when the entire form is submitted or validated.setValidateOnExit
(Boolean validateOnExit) If true, form items will be validated when each item's "editorExit" handler is fired as well as when the entire form is submitted or validated.setValidators
(Validator... validators) Validators for this form item.setValidOperators
(OperatorId... validOperators) Array of valid filtering operators (eg "greaterThan") that are legal for this FormItem.setVAlign
(VerticalAlignment vAlign) Vertical alignment of this item within its cell.void
setValue
(boolean value) Set the value of the form item.void
setValue
(double value) Set the value of the form item.void
setValue
(int value) Set the value of the form item.void
Set the value of the form item as an object.void
Set the value of the form item.void
Set the value of the form item.setValueDeselectedCSSText
(String valueDeselectedCSSText) Custom CSS text to be applied to values that have been deleted, whenshowDeletions
is enabled.setValueField
(String valueField) If this form item maps data values to display values by retrieving thedisplayField
values from anoptionDataSource
, this property denotes the the field to use as the underlying data value in records from the optionDataSource.
If not explicitly supplied, the valueField name will be derived as described ingetValueFieldName()
.void
setValueFormatter
(FormItemValueFormatter formatter) OptionalFormItemValueFormatter
, if provided, is evaluated to get the display value to show for this form items underlying data value.void
setValueHoverFormatter
(FormItemHoverFormatter hoverFormatter) Synonym forsetItemValueHoverFormatter(FormItemHoverFormatter)
.setValueIconHeight
(Integer valueIconHeight) IfvalueIcons
is specified, use this property to specify a height for the value icon written out.setValueIconLeftPadding
(int valueIconLeftPadding) If we're showing a value icon, this attribute governs the amount of space between the icon and the start edge of the form item cell.void
setValueIconMapper
(ValueIconMapper valueIconMapper) Set the FormItem Value Icon mapper that allows the developer to specify the image source for an icon to be displayed for the current form item value.setValueIconRightPadding
(int valueIconRightPadding) If we're showing a value icon, this attribute governs the amount of space between the icon and the value text.void
setValueIcons
(Map valueIcons) Set the valueIcons for this item.setValueIconSize
(int valueIconSize) IfvalueIcons
is specified, this property may be used to specify both the width and height of the icon written out.setValueIconWidth
(Integer valueIconWidth) IfvalueIcons
is specified, use this property to specify a width for the value icon written out.setValueMap
(String... valueMap) Set the valueMap for this item.setValueMap
(Map valueMap) Set the valueMap for this item.setVisible
(Boolean visible) Whether this item is currently visible.setVisibleWhen
(AdvancedCriteria visibleWhen) Criteria to be evaluated to determine whether this FormItem should be visible.void
setWarnOnEditorTypeConversion
(boolean warn) Sets whether a warning will be logged if the Framework replaces this SmartGwt FormItem (that wraps the SmartClient item instance) to more closely match the underlying item's type whengetOrCreateRef()
is called.static void
setWarnOnEditorTypeConversionDefault
(boolean warn) Sets whether, by default, a warning will be logged if the Framework replaces a SmartGWT FormItem (that wraps the SmartClient item instance) to more closely match the underlying item's type.setWidth
(int width) Width of the FormItem.Width of the FormItem.setWrapHintText
(Boolean wrapHintText) If this item is showing ahint
, should the hint text be allowed to wrap? Setting this property tofalse
will render the hint on a single line without wrapping, expanding the width required to render the item if necessary.setWrapStaticValue
(Boolean wrapStaticValue) If this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value wrap?setWrapTitle
(Boolean wrapTitle) If specified determines whether this items title should wrap.boolean
Ifheight
is specified, should it be applied to the item's text box element? If this method returns false, the text box will not have an explicit height applied, though the containing cell will be sized to accommodate any specified height.shouldFetchMissingValue
(Object newValue) If this field has a specifiedoptionDataSource
, should we perform a fetch against that dataSource to find the record that matches this field's value?Returns true if 'Enter' key presses in this formItem should allow a saveOnEnter: true parent form to save it's data.boolean
shouldStopKeyPressBubbling
(String keyName, int characterValue) Should some keypress event on this item be prevented from bubbling (such that the containing form and ancestors do not receive the event).void
show()
Show this form item.void
This method will show some icon in this item'sicons
array, if it is not already visible.void
Method to show a picker for this item.void
This method is fired when the user rolls off this item (or the title for this item) and will clear any hover canvas shown by the item.void
storeValue
(Object value) Store (and optionally show) a value for this form item.void
storeValue
(Object value, Boolean showValue) Store (and optionally show) a value for this form item.void
Update the visual state of a FormItem to reflect any changes in state or any changes in style settings (e.g.validate()
Validate this item.boolean
Is the value clipped?Methods inherited from class com.smartgwt.client.data.Field
getCanExport, getExportTitle, getSortByField, setCanExport, setExportTitle, setSortByField
Methods inherited from class com.smartgwt.client.core.RefDataClass
getRef, getRef, internalSetID
Methods inherited from class com.smartgwt.client.core.DataClass
applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
-
Field Details
-
scClassName
-
configOnly
protected boolean configOnly -
warnOnEditorTypeConversionDefault
protected static boolean warnOnEditorTypeConversionDefault -
warnOnEditorTypeConversion
protected boolean warnOnEditorTypeConversion
-
-
Constructor Details
-
FormItem
public FormItem() -
FormItem
-
FormItem
-
-
Method Details
-
getOrCreateRef
-
getPaletteDefaults
This method returns a Map of config properties suitable for use as the "defaults" attribute of aPaletteNode
. Use it when you need to work with PaletteNodes indirectly, such when setting upTileRecord
s that will be used in aTilePalette
. Seethe dev tools overview
for examples of how to assemble and acquire a suitable defaults object when you are creating a PaletteNode indirectly -
changeAutoChildDefaults
Changes the defaults for Canvas AutoChildren namedautoChildName
.- 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, seeSGWTProperties
.- See Also:
-
changeAutoChildDefaults
Changes the defaults for FormItem AutoChildren namedautoChildName
.- 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, seeSGWTProperties
.- See Also:
-
changePickerIconDefaults
-
setAccessKey
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
- Internet Explorer (all platforms):
-
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:
- Internet Explorer (all platforms):
-
setAlign
Alignment of this item in its cell. Note that the alignment of text / content within this item is controlled separately viatextAlign
(typicallytextAlign
applies to items showing a "textBox", such as aTextItem
orSelectItem
, as well as text-only form item types such asStaticTextItem
andHeaderItem
). IfapplyAlignToText
is true, then thetextAlign
setting, if unset, will default to thealign
setting if set.- Parameters:
align
- New align value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getAlign
Alignment of this item in its cell. Note that the alignment of text / content within this item is controlled separately viatextAlign
(typicallytextAlign
applies to items showing a "textBox", such as aTextItem
orSelectItem
, as well as text-only form item types such asStaticTextItem
andHeaderItem
). IfapplyAlignToText
is true, then thetextAlign
setting, if unset, will default to thealign
setting if set.- Returns:
- Current align value. Default value is null
- See Also:
-
setAllowExpressions
For a form that produces filter criteria (seeform.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.Prefix Operator < lessThan > greaterThan <= lessThanOrEqual >= greaterThanOrEqual someValue...someValue betweenInclusive ! 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 ifformItem.operator
is unspecified, a default operator chosen as described underoperator
.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 viaDynamicForm.allowExpressions
.Finally, note that, like
operator
, enablingallowExpressions:true
causesform.getValuesAsCriteria()
) to returnAdvancedCriteria
.- Parameters:
allowExpressions
- New allowExpressions value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getAllowExpressions
For a form that produces filter criteria (seeform.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.Prefix Operator < lessThan > greaterThan <= lessThanOrEqual >= greaterThanOrEqual someValue...someValue betweenInclusive ! 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 ifformItem.operator
is unspecified, a default operator chosen as described underoperator
.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 viaDynamicForm.allowExpressions
.Finally, note that, like
operator
, enablingallowExpressions:true
causesform.getValuesAsCriteria()
) to returnAdvancedCriteria
.- Returns:
- Current allowExpressions value. Default value is null
- See Also:
-
setAlwaysFetchMissingValues
If this form item has a specifiedoptionDataSource
andfetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related record ifdisplayField
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()
orformatEditorValue()
were written to display properties from theselected 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
If this form item has a specifiedoptionDataSource
andfetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related record ifdisplayField
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()
orformatEditorValue()
were written to display properties from theselected 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
A formItem showing apickerIcon
will always write out a "control box" around the text box and picker icon. This is an HTML element styled using the specifiedcontrolStyle
.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 viaFormItemIcon.showIf()
. This means the control table can be written out with no visible picker ifshowPickerIconOnFocus
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
A formItem showing apickerIcon
will always write out a "control box" around the text box and picker icon. This is an HTML element styled using the specifiedcontrolStyle
.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 viaFormItemIcon.showIf()
. This means the control table can be written out with no visible picker ifshowPickerIconOnFocus
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
If thetextAlign
is unset, should thealign
setting, if set, be used for this item'stextAlign
?applyAlignToText
defaults to false for most form item types. It defaults to true forStaticTextItem
andHeaderItem
, 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 thetextAlign
is unset, should thealign
setting, if set, be used for this item'stextAlign
?applyAlignToText
defaults to false for most form item types. It defaults to true forStaticTextItem
andHeaderItem
, 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
Ifheight
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
Ifheight
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
ARIA role of this formItem. Usually does not need to be manually set - seeAccessibility
.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
ARIA role of this formItem. Usually does not need to be manually set - seeAccessibility
.- Returns:
- Current ariaRole value. Default value is null
- See Also:
-
setAutoComplete
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. IfautoCompleteKeywords
are not provided, andautoComplete
is not set on this FormItem, the value ofDynamicForm.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 andpassword
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
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. IfautoCompleteKeywords
are not provided, andautoComplete
is not set on this FormItem, the value ofDynamicForm.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 andpassword
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
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
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
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
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
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
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
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 thesetCanEdit()
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 theDynamicForm.canEditFieldAttribute
on the associated dataSource field.Developers should also be aware that the
readOnlyDisplay
attribute is unrelated to theDataSourceField.readOnlyEditorType
attribute. When a DynamicForm is first bound to a dataSource, forcanEdit:false
DataSourceFields,DataSourceField.readOnlyEditorType
will determine whatFormItemType
should be created for the field. Once created, a FormItem's type can not be changed. SettingcanEdit
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 fromfalse
. SeeDynamicForm.fieldIsEditable()
for an API that will always returntrue
orfalse
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 viareadOnlyDisplay
.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 classField
- Parameters:
canEdit
- Can this form item be edited?. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 thesetCanEdit()
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 theDynamicForm.canEditFieldAttribute
on the associated dataSource field.Developers should also be aware that the
readOnlyDisplay
attribute is unrelated to theDataSourceField.readOnlyEditorType
attribute. When a DynamicForm is first bound to a dataSource, forcanEdit:false
DataSourceFields,DataSourceField.readOnlyEditorType
will determine whatFormItemType
should be created for the field. Once created, a FormItem's type can not be changed. SettingcanEdit
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 fromfalse
. SeeDynamicForm.fieldIsEditable()
for an API that will always returntrue
orfalse
and give a definitive answer as to whether editing is possible.- Overrides:
getCanEdit
in classField
- 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
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 theSimpleType system
to convert these opaque values into "atomic" values that can be edited by the built-in editors likeTextItem
. 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 togetAtomicValue()
andupdateAtomicValue()
. 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
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 theSimpleType system
to convert these opaque values into "atomic" values that can be edited by the built-in editors likeTextItem
. 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 togetAtomicValue()
andupdateAtomicValue()
. 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
Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as aStaticTextItem
will cause the item to be included in the page's tab order and respond to keyboard events.Note : This is an advanced setting
-
getCanFocus
Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as aStaticTextItem
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 wherecanFocus
was explicitly set to true. Default value is null - See Also:
-
setCanHover
Indicates whether hovers can be shown for this item. When set to false, suppresses all hovers, including those for theitem in general
, or for itsvalue
ortitle
.For finer control over suppressing hovers, see
itemHover
,titleHover
andvalueHover
.- Parameters:
canHover
- New canHover value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getCanHover
Indicates whether hovers can be shown for this item. When set to false, suppresses all hovers, including those for theitem in general
, or for itsvalue
ortitle
.For finer control over suppressing hovers, see
itemHover
,titleHover
andvalueHover
.- Returns:
- Current canHover value. Default value is null
- See Also:
-
setCanSelectText
For items showing a text value, should the user be able to select the text in this item?For
canEdit:false
items, seereadOnlyCanSelectText
- 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, seereadOnlyCanSelectText
- Returns:
- Current canSelectText value. Default value is true
-
setCanTabToIcons
Should this item'sicons
andpicker icon
be included in the page's tab order by default? If not explicitly set, this property will be derived fromDynamicForm.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
Should this item'sicons
andpicker icon
be included in the page's tab order by default? If not explicitly set, this property will be derived fromDynamicForm.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
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 setsitemLayout:"absolute"
.- Parameters:
cellHeight
- New cellHeight value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 setsitemLayout:"absolute"
.- Returns:
- Current cellHeight value. Default value is null
- See Also:
-
setCellStyle
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 theCompoundFormItem_skinning
discussion for special skinning considerations.
If this method is called after the component has been drawn/initialized: Setter forcellStyle
.- Parameters:
cellStyle
- the newcellStyle
value. Default value is "formCell"- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 theCompoundFormItem_skinning
discussion for special skinning considerations.- Returns:
- Current cellStyle value. Default value is "formCell"
- See Also:
-
setChangeOnKeypress
Should this form item fire itschange
handler (and store its value in the form) on every keypress? Set tofalse
to suppress the 'change' handler firing (and the value stored) on every keypress.Note: If
false
, the value returned bygetValue
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
Should this form item fire itschange
handler (and store its value in the form) on every keypress? Set tofalse
to suppress the 'change' handler firing (and the value stored) on every keypress.Note: If
false
, the value returned bygetValue
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
If this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value be clipped if it overflows the specified size of the item? If set, overrides the form-levelDynamicForm.clipStaticValue
default.- Parameters:
clipStaticValue
- New clipStaticValue value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getClipStaticValue
If this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value be clipped if it overflows the specified size of the item? If set, overrides the form-levelDynamicForm.clipStaticValue
default.- Returns:
- Current clipStaticValue value. Default value is null
- See Also:
-
setClipTitle
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
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
A Read-Only pointer to the Smart GWT canvas that holds this form item. In most cases this will be theDynamicForm
containing the item but in some cases editable components handle writing out form items directly. An example of this isGrid Editing
- when a listGrid shows per-field editors, thecontainerWidget
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 asform
), allowing access to standard APIs such asDynamicForm.getValues()
- Returns:
- Current containerWidget value. Default value is null
-
setControlStyle
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 theCompoundFormItem_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
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 theCompoundFormItem_skinning
discussion for special skinning considerations.- Returns:
- Current controlStyle value. Default value is null
- See Also:
-
setCriteriaField
When usingoperator
, the name of the DataSource field for theCriterion
this FormItem generates. If not specified, defaults toname
.Generally, because
criteriaField
defaults toitem.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 forname
but should setcriteriaField
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 asDynamicForm.setValue()
. -
getCriteriaField
When usingoperator
, the name of the DataSource field for theCriterion
this FormItem generates. If not specified, defaults toname
.Generally, because
criteriaField
defaults toitem.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 forname
but should setcriteriaField
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 asDynamicForm.setValue()
.- Returns:
- Current criteriaField value. Default value is null
- See Also:
-
setDataPath
dataPath for this item. Allows the user to edit details nested data structures in a flat set of form fieldsNOTE: 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 theDataPath 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. -
getDataPath
dataPath for this item. Allows the user to edit details nested data structures in a flat set of form fieldsNOTE: 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 theDataPath 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
Display format to use for date type values within this formItem.Note that Fields of type
"date"
,"datetime"
or"time"
will be edited using aDateItem
orTimeItem
by default, but this can be overridden - forcanEdit:false
fields, aStaticTextItem
is used by default, and the developer can always specify a customeditorType
as well asdata type
.The
timeFormatter
may also be used to format underlying Date values as times (ommitting the date part entirely). If bothdateFormatter
andtimeFormatter
are specified on an item, for fields specified astype "time"
thetimeFormatter
will be used, otherwise thedateFormatter
If
item.dateFormatter
anditem.timeFormatter
is unspecified, date display format may be defined at the component level viaDynamicForm.dateFormatter
, or for fields of type"datetime"
DynamicForm.datetimeFormatter
. Otherwise the default is to use the system-wide default short date format, configured viaDateUtil.setShortDisplayFormat()
. Specify any validDateDisplayFormat
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 explicitinputFormat
or via entirely customsetEditorValueFormatter
andsetEditorValueParser
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
Display format to use for date type values within this formItem.Note that Fields of type
"date"
,"datetime"
or"time"
will be edited using aDateItem
orTimeItem
by default, but this can be overridden - forcanEdit:false
fields, aStaticTextItem
is used by default, and the developer can always specify a customeditorType
as well asdata type
.The
timeFormatter
may also be used to format underlying Date values as times (ommitting the date part entirely). If bothdateFormatter
andtimeFormatter
are specified on an item, for fields specified astype "time"
thetimeFormatter
will be used, otherwise thedateFormatter
If
item.dateFormatter
anditem.timeFormatter
is unspecified, date display format may be defined at the component level viaDynamicForm.dateFormatter
, or for fields of type"datetime"
DynamicForm.datetimeFormatter
. Otherwise the default is to use the system-wide default short date format, configured viaDateUtil.setShortDisplayFormat()
. Specify any validDateDisplayFormat
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 explicitinputFormat
or via entirely customsetEditorValueFormatter
andsetEditorValueParser
methods.- Returns:
- Current dateFormatter value. Default value is null
- See Also:
-
setDecimalPad
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
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
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
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
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 theicon.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. Ificon.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 aSCSpriteConfig
formatted string.Note : This is an advanced setting
-
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 theicon.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. Ificon.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 aSCSpriteConfig
formatted string.- Returns:
- Current defaultIconSrc value. Default value is "[SKIN]/DynamicForm/default_formItem_icon.gif"
- See Also:
-
setDefaultOperator
The default search-operator for this item when it or its form allowfilter-expressions
.- Parameters:
defaultOperator
- New defaultOperator value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getDefaultOperator
The default search-operator for this item when it or its form allowfilter-expressions
.- Returns:
- Current defaultOperator value. Default value is null
- See Also:
-
getDefaultValue
Value used when no value is provided for this item. Note that whenever this item's value is cleared programmatically (for example viaitem.clearValue()
oritem.setValue(null)
), it will be reverted to thedefaultValue
.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 ofnull
.Developers looking to provide a 'hint' or placeholder value for an empty item may wish to use
hint
(possibly in conjunction withTextItem.showHintInField
), orprompt
.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:
-
com.smartgwt.client.widgets.form.fields.FormItem#defaultDynamicValue
- Enable & Disable Example
-
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
Whether this item is disabled. Can be updated at runtime via thesetDisabled()
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
This text is shown as a tooltip prompt when the cursor hovers over this item and the item isdisabled
orread-only
withreadOnlyDisplay: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 itemsuppresses hovers
, nothing will be shown.- Parameters:
disabledHover
- New disabledHover value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getDisabledHover
This text is shown as a tooltip prompt when the cursor hovers over this item and the item isdisabled
orread-only
withreadOnlyDisplay: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 itemsuppresses hovers
, nothing will be shown.- Returns:
- Current disabledHover value. Default value is null
- See Also:
-
setDisableIconsOnReadOnly
IfcanEdit
is set to false, shouldicons
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
IfcanEdit
is set to false, shouldicons
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
If set, this item will display a value from another field to the user instead of showing the underlying data value for thefield name
.This property is used in two ways:
The item will display the displayField value from the
record currently being edited
ifuseLocalDisplayFieldValue
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 - seegetDisplayFieldName()
for more on this behavior.
If not usinglocal display values
, the display value for this item will be derived by performing a fetch against theoption dataSource
to find a record where thevalue field
matches this item's value, and use thedisplayField
value from that record.
In addition to this, PickList-based form items that provide a list of possible options such as theSelectItem
orComboBoxItem
will show thedisplayField
values to the user by default, allowing them to choose a new data value (seevalueField
) from a list of user-friendly display values.This essentially allows the specified
optionDataSource
to be used as a server basedvalueMap
.If
local display values
are being used andstoreDisplayValues
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 todisplayField
. 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 forDataSourceField.foreignDisplayField
for more on this.
If a foreignDisplayField is specified, as with just displayField, iflocal display values
are being used andstoreDisplayValues
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
If set, this item will display a value from another field to the user instead of showing the underlying data value for thefield name
.This property is used in two ways:
The item will display the displayField value from the
record currently being edited
ifuseLocalDisplayFieldValue
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 - seegetDisplayFieldName()
for more on this behavior.
If not usinglocal display values
, the display value for this item will be derived by performing a fetch against theoption dataSource
to find a record where thevalue field
matches this item's value, and use thedisplayField
value from that record.
In addition to this, PickList-based form items that provide a list of possible options such as theSelectItem
orComboBoxItem
will show thedisplayField
values to the user by default, allowing them to choose a new data value (seevalueField
) from a list of user-friendly display values.This essentially allows the specified
optionDataSource
to be used as a server basedvalueMap
.If
local display values
are being used andstoreDisplayValues
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 todisplayField
. 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 forDataSourceField.foreignDisplayField
for more on this.
If a foreignDisplayField is specified, as with just displayField, iflocal display values
are being used andstoreDisplayValues
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 explicitforeignDisplayField
is specified, this will be returned. - Otherwise if an explicit
displayField
is specified it will be returned by default. If thedisplayField
was specified on the underlying dataSource field, and no matching field is present in theoptionDataSource
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 theoptionDataSource
, this method will return the title field for theoptionDataSource
.
- If this item has an
- See Also:
-
setEditPendingCSSText
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
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
Default class used to construct theEditProxy
for this component when the component isfirst placed into edit mode
.- Parameters:
editProxyConstructor
- New editProxyConstructor value. Default value is "FormItemEditProxy"- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getEditProxyConstructor
Default class used to construct theEditProxy
for this component when the component isfirst placed into edit mode
.- Returns:
- Current editProxyConstructor value. Default value is "FormItemEditProxy"
- See Also:
-
setEmptyDisplayValue
Text to display when this form item has a null or undefined value.If the formItem has a databound pickList, and its
displayField
orvalueField
(if the former isn't set) has an undefinedemptyCellValue
setting, that field'semptyCellValue
will automatically be set to theemptyDisplayValue
.- Parameters:
emptyDisplayValue
- New emptyDisplayValue value. Default value is ""- Returns:
FormItem
instance, for chaining setter calls
-
getEmptyDisplayValue
Text to display when this form item has a null or undefined value.If the formItem has a databound pickList, and its
displayField
orvalueField
(if the former isn't set) has an undefinedemptyCellValue
setting, that field'semptyCellValue
will automatically be set to theemptyDisplayValue
.- Returns:
- Current emptyDisplayValue value. Default value is ""
-
setEmptyValueIcon
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 (seevalueIcons
)- Parameters:
emptyValueIcon
- New emptyValueIcon value. Default value is null- Returns:
FormItem
instance, for chaining setter calls
-
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 (seevalueIcons
)- Returns:
- Current emptyValueIcon value. Default value is null
-
setEndRow
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
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
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
Icon-properties
to apply to theerror-icon
whenshowErrorIconInline
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
- Returns:
- Current errorIconProperties value. Default value is null
-
setErrorIconSrc
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
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
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
WhenDynamicForm.showInlineErrors
andshowErrorText
are both true anderrorOrientation
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()WhenDynamicForm.showInlineErrors
andshowErrorText
are both true anderrorOrientation
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
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 classField
- Parameters:
escapeHTML
- New escapeHTML value. Default value is varies- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 classField
- Returns:
- Current escapeHTML value. Default value is varies
- See Also:
-
setExportFormat
FormatString
used during exports for numeric or date formatting. SeeDataSourceField.exportFormat
.- Parameters:
exportFormat
- New exportFormat value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getExportFormat
FormatString
used during exports for numeric or date formatting. SeeDataSourceField.exportFormat
.- Returns:
- Current exportFormat value. Default value is null
- See Also:
-
setFetchMissingValues
If this form item has a specifiedoptionDataSource
, 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 explicitvalueMap
containing the data value as a key.
However you can also setalwaysFetchMissingValues
to have a fetch occur even if nodisplayField
is specified. This ensuresgetSelectedRecord()
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
If this form item has a specifiedoptionDataSource
, 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 explicitvalueMap
containing the data value as a key.
However you can also setalwaysFetchMissingValues
to have a fetch occur even if nodisplayField
is specified. This ensuresgetSelectedRecord()
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
If this form item is mapping data values to a display value by fetching records from a dataSource (seeoptionDataSource
,displayField
andfetchMissingValues
), 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
If this form item is mapping data values to a display value by fetching records from a dataSource (seeoptionDataSource
,displayField
andfetchMissingValues
), 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
For items with anoptionDataSource
, this property specifies an explicit display field for records within the option dataSource. Typically this property will be set in conjunction withdisplayField
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
For items with anoptionDataSource
, this property specifies an explicit display field for records within the option dataSource. Typically this property will be set in conjunction withdisplayField
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
FormatString
for numeric or date formatting. SeeDataSourceField.format
.- Parameters:
format
- New format value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getFormat
FormatString
for numeric or date formatting. SeeDataSourceField.format
.- Returns:
- Current format value. Default value is null
- See Also:
-
setFormula
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 tofalse
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
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 tofalse
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
TabIndex for the form item within the page. Takes precedence over any local tab index specified asitem.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
-
getGlobalTabIndex
TabIndex for the form item within the page. Takes precedence over any local tab index specified asitem.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
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 theFormLayout
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
) andSpinnerItem
s, if there is no explicitpickerIconHeight
, 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 asbackground-image
,background-size
, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using theSCSpriteConfig
format. See the section on spriting in theskinning overview
for further information.
Alternatively, thepickerIconStyle
could be changed to a custom CSS style name, and in the case ofSpinnerItem
s, thebaseStyle
andsrc
of theSpinnerItem.increaseIcon
andSpinnerItem.decreaseIcon
AutoChildren could be customized.Note that when FormItem is rendered as read-only with
readOnlyDisplay
as "static" the propertystaticHeight
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 theFormLayout
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
) andSpinnerItem
s, if there is no explicitpickerIconHeight
, 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 asbackground-image
,background-size
, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using theSCSpriteConfig
format. See the section on spriting in theskinning overview
for further information.
Alternatively, thepickerIconStyle
could be changed to a custom CSS style name, and in the case ofSpinnerItem
s, thebaseStyle
andsrc
of theSpinnerItem.increaseIcon
andSpinnerItem.decreaseIcon
AutoChildren could be customized.Note that when FormItem is rendered as read-only with
readOnlyDisplay
as "static" the propertystaticHeight
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
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 theFormLayout
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
) andSpinnerItem
s, if there is no explicitpickerIconHeight
, 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 asbackground-image
,background-size
, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using theSCSpriteConfig
format. See the section on spriting in theskinning overview
for further information.
Alternatively, thepickerIconStyle
could be changed to a custom CSS style name, and in the case ofSpinnerItem
s, thebaseStyle
andsrc
of theSpinnerItem.increaseIcon
andSpinnerItem.decreaseIcon
AutoChildren could be customized.Note that when FormItem is rendered as read-only with
readOnlyDisplay
as "static" the propertystaticHeight
is used instead.- Parameters:
height
- New height value. Default value is 20- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 theFormLayout
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
) andSpinnerItem
s, if there is no explicitpickerIconHeight
, 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 asbackground-image
,background-size
, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using theSCSpriteConfig
format. See the section on spriting in theskinning overview
for further information.
Alternatively, thepickerIconStyle
could be changed to a custom CSS style name, and in the case ofSpinnerItem
s, thebaseStyle
andsrc
of theSpinnerItem.increaseIcon
andSpinnerItem.decreaseIcon
AutoChildren could be customized.Note that when FormItem is rendered as read-only with
readOnlyDisplay
as "static" the propertystaticHeight
is used instead.- Returns:
- Current height value. Default value is 20
- See Also:
-
setHidden
Should this form item be hidden? Setting this property totrue
on an item configuration will have the same effect as having ashowIf()
implementation which returnsfalse
.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 withhidden
set totrue
can still be displayed in a DynamicForm either by being explicitly included in the specifieditems array
, or by havingDataBoundComponent.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 thehidden
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
Should this form item be hidden? Setting this property totrue
on an item configuration will have the same effect as having ashowIf()
implementation which returnsfalse
.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 withhidden
set totrue
can still be displayed in a DynamicForm either by being explicitly included in the specifieditems array
, or by havingDataBoundComponent.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 thehidden
property was set to true on the dataSourceField configuration object.- Returns:
- Current hidden value. Default value is null
-
setHint
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 thehint
for this item.- Parameters:
hint
- new hint for the item. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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
CSS class for the "hint" string. For items that supportTextItem.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
CSS class for the "hint" string. For items that supportTextItem.showHintInField
, this only applies when showHintInField is false.- Returns:
- Current hintStyle value. Default value is "formHint"
- See Also:
-
setHoverAlign
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
Text alignment for text displayed in this item's hover canvas, if shown.- Returns:
- Current hoverAlign value. Default value is null
- See Also:
-
setHoverDelay
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 specifiedthis.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
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 specifiedthis.form.itemHoverDelay
will be used instead.- Returns:
- Current hoverDelay value. Default value is null
-
setHoverFocusKey
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
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
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
Option to specify a height for any hover shown for this item.- Returns:
- Current hoverHeight value. Default value is null
- See Also:
-
setHoverHeight
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
Option to specify a height for any hover shown for this item.- Returns:
- Current hoverHeight value. Default value is null
- See Also:
-
setHoverOpacity
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
Opacity for any hover shown for this item- Returns:
- Current hoverOpacity value. Default value is null
- See Also:
-
setHoverPersist
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
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
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
Explicit CSS Style for any hover shown for this item.- Returns:
- Current hoverStyle value. Default value is null
- See Also:
-
setHoverVAlign
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
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
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
Option to specify a width for any hover shown for this item.- Returns:
- Current hoverWidth value. Default value is null
- See Also:
-
setHoverWidth
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
Option to specify a width for any hover shown for this item.- Returns:
- Current hoverWidth value. Default value is null
- See Also:
-
setIconBaseStyle
Fallback base CSS class to apply to this item'sicons
if they don't specify abaseStyle
or provide a sprite-basedsrc string
that specifies acssClass
.- Parameters:
iconBaseStyle
- New iconBaseStyle value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getIconBaseStyle
Fallback base CSS class to apply to this item'sicons
if they don't specify abaseStyle
or provide a sprite-basedsrc string
that specifies acssClass
.- Returns:
- Current iconBaseStyle value. Default value is null
- See Also:
-
setIconHeight
Default height for form item icons. May be overridden at the icon level byFormItemIcon.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 byFormItemIcon.height
.- Returns:
- Takes an icon definition object, and returns the height for that icon in px. Default value is 20
-
setIconHSpace
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 viaFormItemIcon.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 viaFormItemIcon.hspace
. Must be non-negative.- Returns:
- Current iconHSpace value. Default value is 3
-
setIconPrompt
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
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
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
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
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
How should icons be aligned vertically for this form item.- Returns:
- Current iconVAlign value. Default value is "bottom"
-
setIconWidth
Default width for form item icons. May be overridden at the icon level byFormItemIcon.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 byFormItemIcon.width
.- Returns:
- Takes an icon definition object, and returns the width for that icon in px. Default value is 20
-
setID
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, viaform.getItem("itemName")
).An internal, unique ID will automatically be created upon instantiation for any formItem where one is not provided.
-
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, viaform.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
Prefix to apply to the beginning of anyvalueIcons
when determining the URL for the image. Will not be applied if thevalueIcon
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
Prefix to apply to the beginning of anyvalueIcons
when determining the URL for the image. Will not be applied if thevalueIcon
URL is absolute.- Returns:
- Current imageURLPrefix value. Default value is null
-
setImageURLSuffix
Suffix to apply to the end of anyvalueIcons
when determining the URL for the image. A common usage would be to specify a suffix of".gif"
in which case thevalueIcons
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
Suffix to apply to the end of anyvalueIcons
when determining the URL for the image. A common usage would be to specify a suffix of".gif"
in which case thevalueIcons
property would map values to the names of images without the".gif"
extension.- Returns:
- Current imageURLSuffix value. Default value is null
-
setImplicitSave
When true, indicates that changes to this item will cause an automatic save on adelay
, as well as when the entire form is submitted. If implicitSaveOnBlur is set to true on either thisformItem
or it'sform
, 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
When true, indicates that changes to this item will cause an automatic save on adelay
, as well as when the entire form is submitted. If implicitSaveOnBlur is set to true on either thisformItem
or it'sform
, changes will also be automatically saved immediately on editorExit.- Returns:
- Current implicitSave value. Default value is false
-
setImplicitSaveOnBlur
If set to true, this item's value will be saved immediately when its "editorExit" handler is fired. This attribute works separately fromimplicitSave
, which causes saves during editing, after ashort 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
If set to true, this item's value will be saved immediately when its "editorExit" handler is fired. This attribute works separately fromimplicitSave
, which causes saves during editing, after ashort delay
, and when the entire form is submitted.- Returns:
- Current implicitSaveOnBlur value. Default value is false
-
setInputFormat
For fields of type"date"
, if this is an editable field such as aTextItem
, this property allows you to specify theinputFormat
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
For fields of type"date"
, if this is an editable field such as aTextItem
, this property allows you to specify theinputFormat
applied to the item.- Returns:
- Current inputFormat value. Default value is null
- See Also:
-
setLeft
Left coordinate of this item in pixels. Applies only when the containing DynamicForm setsitemLayout:"absolute"
.
If this method is called after the component has been drawn/initialized: For a form withitemLayout
:"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 setsitemLayout:"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
Specifies a column span for an item inlinearMode
, 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 inlinearMode
, 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
Specifies a column span for an item inlinearMode
, 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
Specifies a column span for an item inlinearMode
, 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
- Parameters:
linearEndRow
- New linearEndRow value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getLinearEndRow
public int getLinearEndRow()SpecifiesendRow
for an item inlinearMode
, overriding the default oftrue
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
- Parameters:
linearEndRow
- New linearEndRow value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getLinearEndRowAsString
- Returns:
- Current linearEndRow value. Default value is null
- See Also:
-
setLinearStartRow
- Parameters:
linearStartRow
- New linearStartRow value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getLinearStartRow
public int getLinearStartRow()SpecifiesstartRow
for an item inlinearMode
, overriding the default offalse
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
- Parameters:
linearStartRow
- New linearStartRow value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getLinearStartRowAsString
- Returns:
- Current linearStartRow value. Default value is null
- See Also:
-
setLinearWidth
Specifies a width for an item inlinearMode
, 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 inlinearMode
, 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
Specifies a width for an item inlinearMode
, 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
Specifies a width for an item inlinearMode
, overriding the default width of "*" in that mode.- Returns:
- Current linearWidth value. Default value is null
- See Also:
-
setLoadingDisplayValue
Value shown in field whenfetchMissingValues
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
Value shown in field whenfetchMissingValues
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
WhenAutoTest.getElement()
is used to parse locator strings generated byAutoTest.getLocator()
for this form item, should the item be identified? If the locator has a specifiedname
, 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
WhenAutoTest.getElement()
is used to parse locator strings generated byAutoTest.getLocator()
for this form item, should the item be identified? If the locator has a specifiedname
, 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
If this item is showing ahint
, 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 towrapHintText
being set tofalse
, 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
If this item is showing ahint
, 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 towrapHintText
being set tofalse
, 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
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 asMultiComboBoxItem
are always effectively multiple:true, even if multiple:true is not set.- Overrides:
setMultiple
in classField
- Parameters:
multiple
- New multiple value. Default value is false- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 asMultiComboBoxItem
are always effectively multiple:true, even if multiple:true is not set.- Overrides:
getMultiple
in classField
- Returns:
- Current multiple value. Default value is false
- See Also:
-
setMultipleValueSeparator
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
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
Name for this form field. Must be unique within the form as well as a valid JavaScript identifier - seeFieldName
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. -
setNullOriginalValueText
Text shown as the value in theoriginalValueMessage
whenshowOldValueInHover
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
Text shown as the value in theoriginalValueMessage
whenshowOldValueInHover
is enabled, and when the value has been modified but was originally unset.- Returns:
- Current nullOriginalValueText value. Default value is "None"
- See Also:
-
setOperator
OperatorId
to be used whenDynamicForm.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 theFilterBuilder
. For example, two SpinnerItems could be created withformItem.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 anAdvancedCriteria
object instead of a normalCriteria
object. Each FormItem will produce oneCriterion
affecting the DataSource field specified bycriteriaField
. The criteria produced by the FormItems will be grouped under the logical operator provided byDynamicForm.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 byDynamicForm.defaultSearchOperator
.Note:
formItem.operator
is only supported for a form that has adataSource
. In a form with no DataSource, settingformItem.operator
will have no effect.- Parameters:
operator
- New operator value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getOperator
OperatorId
to be used whenDynamicForm.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 theFilterBuilder
. For example, two SpinnerItems could be created withformItem.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 anAdvancedCriteria
object instead of a normalCriteria
object. Each FormItem will produce oneCriterion
affecting the DataSource field specified bycriteriaField
. The criteria produced by the FormItems will be grouped under the logical operator provided byDynamicForm.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 byDynamicForm.defaultSearchOperator
.Note:
formItem.operator
is only supported for a form that has adataSource
. In a form with no DataSource, settingformItem.operator
will have no effect.- Returns:
- Current operator value. Default value is null
- See Also:
-
setOptionDataSource
If set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
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 tosetValue()
, such as may happen whenDynamicForm.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 andoptionDataSource
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 theoptionDataSource
at runtime- Parameters:
optionDataSource
- new optionDatasource. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getOptionDataSource
If set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
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 tosetValue()
, such as may happen whenDynamicForm.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 andoptionDataSource
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, ifDataSourceField.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
If set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
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 tosetValue()
, such as may happen whenDynamicForm.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 andoptionDataSource
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 theoptionDataSource
at runtime- Parameters:
optionDataSource
- new optionDatasource. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getOptionDataSourceAsString
If set, this FormItem will map stored values to display values as though acom.smartgwt.client.types.ValueMap
were specified, by fetching records from the specifiedoptionDataSource
and extracting thevalueField
anddisplayField
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 tosetValue()
, such as may happen whenDynamicForm.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 andoptionDataSource
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, ifDataSourceField.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
If this item has a specifiedoptionDataSource
, this attribute may be set to specify an explicitDSRequest.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
If this item has a specifiedoptionDataSource
, this attribute may be set to specify an explicitDSRequest.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
If this item has a specifiedoptionDataSource
, this property determines the textMatchStyle to use when interpretating anyoptionCriteria
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
If this item has a specifiedoptionDataSource
, this property determines the textMatchStyle to use when interpretating anyoptionCriteria
during the fetch to map valueField values to displayField values.- Returns:
- Current optionTextMatchStyle value. Default value is "exact"
- See Also:
-
setOriginalValueMessage
Message shown whenshowOldValueInHover
is enabled and the value has been modified.If unset, defaults to the form's
DynamicForm.originalValueMessage
. Otherwise, overrides the form-defaultoriginalValueMessage
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
Message shown whenshowOldValueInHover
is enabled and the value has been modified.If unset, defaults to the form's
DynamicForm.originalValueMessage
. Otherwise, overrides the form-defaultoriginalValueMessage
for this item.- Returns:
- Current originalValueMessage value. Default value is null
- See Also:
-
getPicker
The component that will be displayed whenshowPicker()
is called due to a click on thepicker 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
IfshowPickerIcon
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 theSCSpriteConfig
format. See the section on spriting in theskinning 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
IfshowPickerIcon
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 theSCSpriteConfig
format. See the section on spriting in theskinning overview
for further information.- Returns:
- Current pickerIconHeight value. Default value is null
-
setPickerIconName
IfshowPickerIcon
is true, this attribute specifies theFormItemIcon.name
applied to the picker iconNote : This is an advanced setting
- Parameters:
pickerIconName
- New pickerIconName value. Default value is "picker"- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getPickerIconName
IfshowPickerIcon
is true, this attribute specifies theFormItemIcon.name
applied to the picker icon- Returns:
- Current pickerIconName value. Default value is "picker"
- See Also:
-
setPickerIconPrompt
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
Prompt to show when the user hovers the mouse over the picker icon.- Returns:
- Current pickerIconPrompt value. Default value is null
- See Also:
-
setPickerIconProperties
IfshowPickerIcon
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
IfshowPickerIcon
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
IfshowPickerIcon
is true for this item, this property governs thesrc
of the picker icon image to be displayed.Spriting
can be used for this image, by setting this property to aSCSpriteConfig
formatted string.Note : This is an advanced setting
-
getPickerIconSrc
IfshowPickerIcon
is true for this item, this property governs thesrc
of the picker icon image to be displayed.Spriting
can be used for this image, by setting this property to aSCSpriteConfig
formatted string.- Returns:
- Current pickerIconSrc value. Default value is ""
- See Also:
-
setPickerIconStyle
Base CSS class name for a form item's picker icon cell. If unset, inherits from this item'scontrolStyle
.- Parameters:
pickerIconStyle
- New pickerIconStyle value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getPickerIconStyle
Base CSS class name for a form item's picker icon cell. If unset, inherits from this item'scontrolStyle
.- Returns:
- Current pickerIconStyle value. Default value is null
- See Also:
-
setPickerIconWidth
IfshowPickerIcon
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 theSCSpriteConfig
format. See the section on spriting in theskinning 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
IfshowPickerIcon
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 theSCSpriteConfig
format. See the section on spriting in theskinning overview
for further information.- Returns:
- Current pickerIconWidth value. Default value is null
-
setPrintReadOnlyTextBoxStyle
CSS class name to apply to the print view of an item's text box if the item iscanEdit:false
, withreadOnlyDisplay: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
CSS class name to apply to the print view of an item's text box if the item iscanEdit:false
, withreadOnlyDisplay:static
.If specified this will take precedence over
printTextBoxStyle
for static readonly items.- Returns:
- Current printReadOnlyTextBoxStyle value. Default value is null
- See Also:
-
setPrintTextBoxStyle
Base CSS class name for a form item's text box element when getting printable HTML for the form. If unsettextBoxStyle
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
withreadOnlyDisplay:static
.
To override this behavior, developers may also specify a custom print style for this state via theprintReadOnlyTextBoxStyle
.- Parameters:
printTextBoxStyle
- New printTextBoxStyle value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getPrintTextBoxStyle
Base CSS class name for a form item's text box element when getting printable HTML for the form. If unsettextBoxStyle
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
withreadOnlyDisplay:static
.
To override this behavior, developers may also specify a custom print style for this state via theprintReadOnlyTextBoxStyle
.- Returns:
- Current printTextBoxStyle value. Default value is null
- See Also:
-
setPrintTitleStyle
Base CSS stylename for a form item's title when generating print HTML for the item. If unsettitleStyle
will be used instead.- Parameters:
printTitleStyle
- New printTitleStyle value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getPrintTitleStyle
Base CSS stylename for a form item's title when generating print HTML for the item. If unsettitleStyle
will be used instead.- Returns:
- Current printTitleStyle value. Default value is null
- See Also:
-
setPrompt
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 withreadOnlyHover
. Or, when the item isdisabled
or read-only withreadOnlyDisplay:disabled
a different hover can be shown withdisabledHover
.Note that when the form is
disabled
, or when this itemsuppresses hovers
, this prompt will not be shown.
If this method is called after the component has been drawn/initialized: Sets theprompt
for this item.- Parameters:
prompt
- new prompt for the item. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 withreadOnlyHover
. Or, when the item isdisabled
or read-only withreadOnlyDisplay:disabled
a different hover can be shown withdisabledHover
.Note that when the form is
disabled
, or when this itemsuppresses hovers
, this prompt will not be shown.- Returns:
- Current prompt value. Default value is null
- See Also:
-
setReadOnlyCanSelectText
For items showing a text value withcanEdit
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
For items showing a text value withcanEdit
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
Modifiedcontrol style
to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.- Parameters:
readOnlyControlStyle
- New readOnlyControlStyle value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getReadOnlyControlStyle
Modifiedcontrol style
to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.- Returns:
- Current readOnlyControlStyle value. Default value is null
- See Also:
-
setReadOnlyDisplay
If this item isread-only
, how should this item be displayed to the user? If set, overrides the form-levelDynamicForm.readOnlyDisplay
default.
If this method is called after the component has been drawn/initialized: Setter forreadOnlyDisplay
.Note that calling this method for a
ButtonItem
withButtonItem.enableWhen
set is an error, sincereadOnlyDisplay
is then considered to always be "disabled".- Parameters:
readOnlyDisplay
- newreadOnlyDisplay
value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getReadOnlyDisplay
If this item isread-only
, how should this item be displayed to the user? If set, overrides the form-levelDynamicForm.readOnlyDisplay
default.- Returns:
- Current readOnlyDisplay value. Default value is null
- See Also:
-
setReadOnlyHover
This text is shown as a tooltip prompt when the cursor hovers over this item and the item isread-only
.Note that when the form is
disabled
, or when this itemsuppresses hovers
, nothing will be shown.- Parameters:
readOnlyHover
- New readOnlyHover value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getReadOnlyHover
This text is shown as a tooltip prompt when the cursor hovers over this item and the item isread-only
.Note that when the form is
disabled
, or when this itemsuppresses hovers
, nothing will be shown.- Returns:
- Current readOnlyHover value. Default value is null
- See Also:
-
setReadOnlyTextBoxStyle
Base text box style to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
. If set, overrides the form-levelDynamicForm.readOnlyTextBoxStyle
default.- Parameters:
readOnlyTextBoxStyle
- New readOnlyTextBoxStyle value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getReadOnlyTextBoxStyle
Base text box style to apply when this item isread-only
and is usingreadOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
. If set, overrides the form-levelDynamicForm.readOnlyTextBoxStyle
default.- Returns:
- Current readOnlyTextBoxStyle value. Default value is null
- See Also:
-
setReadOnlyWhen
Criteria to be evaluated to determine whether this FormItem should be maderead-only
. Appearance when read-only is determined byreadOnlyDisplay
.Criteria are evaluated against the
form's current values
as well as the currentrule 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 allowsshorthand formats
for defining criteria.Note: A FormItem using readOnlyWhen must have a
name
defined.shouldSaveValue
can be set tofalse
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
Criteria to be evaluated to determine whether this FormItem should be maderead-only
. Appearance when read-only is determined byreadOnlyDisplay
.Criteria are evaluated against the
form's current values
as well as the currentrule 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 allowsshorthand formats
for defining criteria.Note: A FormItem using readOnlyWhen must have a
name
defined.shouldSaveValue
can be set tofalse
to prevent the field from storing its value into the form's values.- Returns:
- Current readOnlyWhen value. Default value is null
- See Also:
-
setRedrawOnChange
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
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
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
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
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 aDataSourceField
.
If this method is called after the component has been drawn/initialized: Setter to mark this formItem asrequired
, or not required at runtime. Note that an alternative approach to updating therequired
flag directly would be to simply use arequiredIf
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()
orDynamicForm.clearErrors()
.- Overrides:
setRequired
in classField
- Parameters:
required
- newrequired
value. Default value is false- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
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 aDataSourceField
.- Returns:
- Current required value. Default value is false
- See Also:
-
setRequiredMessage
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
The required message for required field errors.- Returns:
- Current requiredMessage value. Default value is null
- See Also:
-
setRequiredWhen
Criteria to be evaluated to determine whether this FormItem should berequired
.Criteria are evaluated against the
form's current values
as well as the currentrule 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 allowsshorthand 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
Criteria to be evaluated to determine whether this FormItem should berequired
.Criteria are evaluated against the
form's current values
as well as the currentrule 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 allowsshorthand 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
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
Set this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem andsaveOnEnter
is true on the parent form.- Parameters:
saveOnEnter
- New saveOnEnter value. Default value is null- Returns:
FormItem
instance, for chaining setter calls
-
getSaveOnEnter
Set this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem andsaveOnEnter
is true on the parent form.- Returns:
- Current saveOnEnter value. Default value is null
-
setSelectOnClick
Allows theselectOnClick
behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value ofDynamicForm.selectOnClick
. -
getSelectOnClick
Allows theselectOnClick
behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value ofDynamicForm.selectOnClick
.- Returns:
- Current selectOnClick value. Default value is null
- See Also:
-
setSelectOnFocus
Allows theselectOnFocus
behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value ofDynamicForm.selectOnFocus
. -
getSelectOnFocus
Allows theselectOnFocus
behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value ofDynamicForm.selectOnFocus
.- Returns:
- Current selectOnFocus value. Default value is null
- See Also:
-
setShouldSaveValue
Should this item's value be saved in the form's values and hence returned fromform.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'svalues
. 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 viadefaultValue
or by callingform.setValue(item, value)
orformItem.setValue(value)
. Providing a value viaform.values
orform.setValues()
will automatically switch the item toshouldSaveValue: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
Should this item's value be saved in the form's values and hence returned fromform.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'svalues
. 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 viadefaultValue
or by callingform.setValue(item, value)
orformItem.setValue(value)
. Providing a value viaform.values
orform.setValues()
will automatically switch the item toshouldSaveValue: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
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 aFormItemHoverFormatter
on either thisFormItem
or theDynamicForm
. SeesetItemTitleHoverFormatter()
.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 aFormItemHoverFormatter
on either thisFormItem
or theDynamicForm
. SeesetItemTitleHoverFormatter()
.If the item
suppresses hovers
, nothing will be shown.- Returns:
- Current showClippedTitleOnHover value. Default value is true
-
setShowClippedValueOnHover
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 aFormItemHoverFormatter
on either thisFormItem
or theDynamicForm
. SeesetItemValueHoverFormatter()
.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
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 aFormItemHoverFormatter
on either thisFormItem
or theDynamicForm
. SeesetItemValueHoverFormatter()
.If the item
suppresses hovers
, nothing will be shown.- Returns:
- Current showClippedValueOnHover value. Default value is true
-
setShowDeletions
For items that supportmultiple values
, this causes distinct CSS styling to be applied to values that the user has unselected.Only allowed when
showPending
istrue
. Defaults to the form-levelDynamicForm.showDeletions
setting if set; otherwise, to the value ofshowPending
.Only supported for
MultiComboBoxItem
and forSelectItem
whenmultiple:true
is set. The specific default behaviors are:- For
MultiComboBoxItem
, buttons corresponding to deleted values (also called "deselected buttons") will be disabled and have theirButton.baseStyle
set toMultiComboBoxItem.deselectedButtonStyle
. - For a multiple
SelectItem
,valueDeselectedCSSText
is applied to any deleted value in the text box. In addition, "Deselected" is appended to the cells'ListGrid.baseStyle
for cells in the pickList menu corresponding to deleted values.
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:
- For
-
getShowDeletions
For items that supportmultiple values
, this causes distinct CSS styling to be applied to values that the user has unselected.Only allowed when
showPending
istrue
. Defaults to the form-levelDynamicForm.showDeletions
setting if set; otherwise, to the value ofshowPending
.Only supported for
MultiComboBoxItem
and forSelectItem
whenmultiple:true
is set. The specific default behaviors are:- For
MultiComboBoxItem
, buttons corresponding to deleted values (also called "deselected buttons") will be disabled and have theirButton.baseStyle
set toMultiComboBoxItem.deselectedButtonStyle
. - For a multiple
SelectItem
,valueDeselectedCSSText
is applied to any deleted value in the text box. In addition, "Deselected" is appended to the cells'ListGrid.baseStyle
for cells in the pickList menu corresponding to deleted values.
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:
- For
-
setShowDisabled
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 forshowDisabled
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
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
IfshowIconsOnFocus
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
IfshowIconsOnFocus
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
IfshowPickerIconOnFocus
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
IfshowPickerIconOnFocus
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
showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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, setshowInlineErrors
:false.showErrorIcons
,showErrorText
,errorOrientation
andshowErrorStyle
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 respectsshowErrorIcons
andshowErrorText
as follows:showErrorIcons
, orshowErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed byerrorIconSrc
,errorIconWidth
anderrorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The attributeDynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +":"
(may be desired if the item hasshowTitle
set to false).
IfshowErrorText
is unset, the error text will be shown ifDynamicForm.linearMode
is true (orDynamicForm.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 ofshowErrorText
:false
anderrorOrientation
:"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).
IferrorOrientation
is unset, the error orientation will default to "top" ifDynamicForm.linearMode
is enabled (orDynamicForm.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. SeeFormItemBaseStyle
for more on this.- Parameters:
showErrorIcon
- New showErrorIcon value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getShowErrorIcon
showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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, setshowInlineErrors
:false.showErrorIcons
,showErrorText
,errorOrientation
andshowErrorStyle
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 respectsshowErrorIcons
andshowErrorText
as follows:showErrorIcons
, orshowErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed byerrorIconSrc
,errorIconWidth
anderrorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The attributeDynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +":"
(may be desired if the item hasshowTitle
set to false).
IfshowErrorText
is unset, the error text will be shown ifDynamicForm.linearMode
is true (orDynamicForm.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 ofshowErrorText
:false
anderrorOrientation
:"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).
IferrorOrientation
is unset, the error orientation will default to "top" ifDynamicForm.linearMode
is enabled (orDynamicForm.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. SeeFormItemBaseStyle
for more on this.- Returns:
- Current showErrorIcon value. Default value is null
- See Also:
-
setShowErrorIconInline
When set to true, this attribute renders theerror-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, theerror-text
is not displayed but is available in the icon's hover.Icon-properties
can be applied to the error-icon viaerrorIconProperties
.Note : This is an advanced setting
- Parameters:
showErrorIconInline
- New showErrorIconInline value. Default value is null- Returns:
FormItem
instance, for chaining setter calls
-
getShowErrorIconInline
When set to true, this attribute renders theerror-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, theerror-text
is not displayed but is available in the icon's hover.Icon-properties
can be applied to the error-icon viaerrorIconProperties
.- Returns:
- Current showErrorIconInline value. Default value is null
-
setShowErrorStyle
showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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, setshowInlineErrors
:false.showErrorIcons
,showErrorText
,errorOrientation
andshowErrorStyle
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 respectsshowErrorIcons
andshowErrorText
as follows:showErrorIcons
, orshowErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed byerrorIconSrc
,errorIconWidth
anderrorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The attributeDynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +":"
(may be desired if the item hasshowTitle
set to false).
IfshowErrorText
is unset, the error text will be shown ifDynamicForm.linearMode
is true (orDynamicForm.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 ofshowErrorText
:false
anderrorOrientation
:"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).
IferrorOrientation
is unset, the error orientation will default to "top" ifDynamicForm.linearMode
is enabled (orDynamicForm.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. SeeFormItemBaseStyle
for more on this.- Parameters:
showErrorStyle
- New showErrorStyle value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getShowErrorStyle
showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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, setshowInlineErrors
:false.showErrorIcons
,showErrorText
,errorOrientation
andshowErrorStyle
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 respectsshowErrorIcons
andshowErrorText
as follows:showErrorIcons
, orshowErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed byerrorIconSrc
,errorIconWidth
anderrorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The attributeDynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +":"
(may be desired if the item hasshowTitle
set to false).
IfshowErrorText
is unset, the error text will be shown ifDynamicForm.linearMode
is true (orDynamicForm.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 ofshowErrorText
:false
anderrorOrientation
:"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).
IferrorOrientation
is unset, the error orientation will default to "top" ifDynamicForm.linearMode
is enabled (orDynamicForm.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. SeeFormItemBaseStyle
for more on this.- Returns:
- Current showErrorStyle value. Default value is null
- See Also:
-
setShowErrorText
showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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, setshowInlineErrors
:false.showErrorIcons
,showErrorText
,errorOrientation
andshowErrorStyle
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 respectsshowErrorIcons
andshowErrorText
as follows:showErrorIcons
, orshowErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed byerrorIconSrc
,errorIconWidth
anderrorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The attributeDynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +":"
(may be desired if the item hasshowTitle
set to false).
IfshowErrorText
is unset, the error text will be shown ifDynamicForm.linearMode
is true (orDynamicForm.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 ofshowErrorText
:false
anderrorOrientation
:"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).
IferrorOrientation
is unset, the error orientation will default to "top" ifDynamicForm.linearMode
is enabled (orDynamicForm.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. SeeFormItemBaseStyle
for more on this.- Parameters:
showErrorText
- New showErrorText value. Default value is null- Returns:
FormItem
instance, for chaining setter calls- See Also:
-
getShowErrorText
showErrorIcons
,showErrorText
,errorOrientation
, andshowErrorStyle
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, setshowInlineErrors
:false.showErrorIcons
,showErrorText
,errorOrientation
andshowErrorStyle
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 respectsshowErrorIcons
andshowErrorText
as follows:showErrorIcons
, orshowErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have validation errors. The icon's appearance is governed byerrorIconSrc
,errorIconWidth
anderrorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The attributeDynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +":"
(may be desired if the item hasshowTitle
set to false).
IfshowErrorText
is unset, the error text will be shown ifDynamicForm.linearMode
is true (orDynamicForm.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 ofshowErrorText
:false
anderrorOrientation
:"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).
IferrorOrientation
is unset, the error orientation will default to "top" ifDynamicForm.linearMode
is enabled (orDynamicForm.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. SeeFormItemBaseStyle
for more on this.- Returns:
- Current showErrorText value. Default value is null
- See Also:
-
setShowFocused
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
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
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
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
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 formItemIconshowFocused
property.Note : This is an advanced setting
- Parameters:
showFocusedIcons
- New showFocusedIcons value. Default value is null- Returns:
FormItem
instance, for chaining setter calls
-
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 formItemIconshowFocused
property.- Returns:
- Current showFocusedIcons value. Default value is null
-
setShowFocusedPickerIcon
IfshowPickerIcon
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
IfshowPickerIcon
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
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
If a hint is defined for this form item, should it be shown?- Returns:
- Current showHint value. Default value is true
- See Also:
-
setShowIcons
Set to false to suppress writing out anyicons
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
Set to false to suppress writing out anyicons
for this item.- Returns:
- Current showIcons value. Default value is true
-
setShowIconsOnFocus
Show theicons
when the item gets focus, and hide them when it loses focus. Can be overridden at the icon level byFormItemIcon.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: SetsshowIconsOnFocus
and causes the visibility of allicons
to be updated and the item redrawn as appropriate.Note : This is an advanced setting
- Parameters:
showIconsOnFocus
- new value ofshowIconsOnFocus
. Default value is null- Returns:
FormItem
instance, for chaining setter calls
-
getShowIconsOnFocus
Show theicons
when the item gets focus, and hide them when it loses focus. Can be overridden at the icon level byFormItemIcon.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
For fields oftype:"image"
, if the field is non editable, and being displayed withreadOnlyDisplay:"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
For fields oftype:"image"
, if the field is non editable, and being displayed withreadOnlyDisplay:"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
Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when theFormItem.itemHover()
event would fire).When
showOldValueInHover
and the form'sDynamicForm.showOldValueInHover
are both unset, defaults to the value ofshowPending
.The message shown is controlled by
originalValueMessage
, unless the item isdisabled
anddisabledHover
is set - in this case, the hover shows thedisabledHover
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
Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when theFormItem.itemHover()
event would fire).When
showOldValueInHover
and the form'sDynamicForm.showOldValueInHover
are both unset, defaults to the value ofshowPending
.The message shown is controlled by
originalValueMessage
, unless the item isdisabled
anddisabledHover
is set - in this case, the hover shows thedisabledHover
HTML.If the item
suppresses hovers
, nothing will be shown.- Returns:
- Current showOldValueInHover value. Default value is null
-
setShowOver
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 andFormItemIcon.showOverWhen
is set to "textBox".
These behaviors can be disabled piecemeal viaupdateTextBoxOnOver
,updateControlOnOver
andupdatePickerIconOnOver
properties.Developers may also show rollover styling for other icons (see
showOverIcons
andFormItemIcon.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 andFormItemIcon.showOverWhen
is set to "textBox".
These behaviors can be disabled piecemeal viaupdateTextBoxOnOver
,updateControlOnOver
andupdatePickerIconOnOver
properties.Developers may also show rollover styling for other icons (see
showOverIcons
andFormItemIcon.showOverWhen
).See
FormItemStyling
for more details on formItem styling.- Returns:
- Current showOver value. Default value is false
- See Also:
-
setShowOverIcons
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 formItemIconshowOver
property.Note : This is an advanced setting
- Parameters:
showOverIcons
- New showOverIcons value. Default value is null- Returns:
FormItem
instance, for chaining setter calls
-
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 formItemIconshowOver
property.- Returns:
- Current showOverIcons value. Default value is null
-
setShowPending
When set totrue
, 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 invokingDynamicForm.resetValues()
. SeeFormItemBaseStyle
for details.shouldSaveValue
must betrue
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 ofchangeOnKeypress
, 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 defaultFormItem.pendingStatusChanged()
behavior is canceled and a custom pending visual state is implemented by the item.On the other hand, when set to
true
and ifcanHover
is also true, a hover will appear, displaying the old value and controlled byshowOldValueInHover
,originalValueMessage
andnullOriginalValueText
. Additionally, if the new value isclipped
, 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
-