SetFieldValue

Sets the value of the specified field.

Note: Sub-Relational fields are not supported. These fields are driven by associated Single Relational or Multi-Relational fields, which can be set using the SetFieldValue method.
Note: SetFieldValue is also a scripting method in SBM.
Note: If you are using translations for Selection fields, you must include all translations for SetFieldValue to work. If the number of translations is too large to maintain, it is recommended to use form actions instead of SetFieldValue.

Parameters

Name Type Description
fieldName String The name of the field.
value Various
The value to set on the field. The value is a string, with the following exceptions:
  • Binary/Trinary (Check box style): The value is a Boolean (true or false).
  • Date/Time (Date and time, Date only, Time of day style): The value is a Date object.
  • Date/Time (Elapsed time style): The value is a numeric value for the number of milliseconds of elapsed time.
If the field is a Combo Box or List Box, the value must match the value of an item already in the list, and is case-sensitive.

If the field is a Multi-Group, Multi-Relational, Multi-Selection, or Multi-User field, the value is a string of comma-separated values. If the values have embedded commas, use the SetFieldValues method instead to return the array.

In Modern Forms, the following input types are also accepted for Single- and Multi- Group, Relational, Selection, and User fields:
  • Single string. If the field is searchable and the value is not present, a search will be performed using this string. The search will attempt to set the desired value from the results. If no exact match is found, the default value from that search will be set.
  • Numeric database ID. If the field is searchable and the value is not present, a search will be performed using no keywords. The search will attempt to set the desired value from the results.
  • Name/value pair object in the form { name: "value", id: id}. If the value is not present, it will be inserted and selected without running a search. Arbitrary values may be inserted this way but the server will still perform validation of the values and dependencies.
  • An array of any of the above. If the field is searchable and any values are not present, a search will be performed using no keywords.
Note: Automatic searches performed by SetFieldValue may experience limitations with max search results or complex VDF. When possible, try to use name/value pairs when setting a searchable field, as any desired values that are already present or that can be constructed will be selected without searching.
fireEvent Boolean If this parameter is set to true, then setting the values causes the change event to fire. If this parameter is set to false, then the change event does not fire.

Return Value

Result Value
(none)  

Examples

This example sets the string value of a Text field:

SetFieldValue("UNITPRICE", "1.45", true);

This example sets the string value of a Binary/Trinary field with three radio button choices:

SetFieldValue("RELEASETYPE", "Beta", true);

This Modern Form example sets the value of a searchable Single Relational field (e.g. copied from another field referencing the same table). The value is inserted if necessary:

SetFieldValue("RELEASE", { name: "SBM 11.3", value: 12345 }, true);

Comments

(none)