GetFieldValue

Gets the value of the specified field.

Parameters

Name	Type	Description
fieldName	String	The name of the field.
defaultValue (optional)	String	The default value to return if the field does not exist on the form, if it is not found, or if its value is empty. If this parameter is not provided, "null" is returned.
path (optional)	String	The name of the sub-field to return. On some field types, a path of “ID” will return a unique internal identification number.

Return Value

Field Type	Field Style	Return Value
Binary/Trinary	Drop down list, Radio buttons	String value of the field.
Binary/Trinary	Check box	Numeric value 1 if checked; empty value if cleared. (It is recommended that you use IsFieldChecked instead for this field type and style.)
Date/Time	Date and time, Date only, Time of day	A Date object containing the value of the field.
Date/Time	Elapsed time	Numeric value for the number of milliseconds of elapsed time.
Folder	N/A	String value of the field
Multi-Group, Multi-User, Multi-Selection, Multi-Relational	N/A	String value of the field. If multiple values are selected, a comma-separated list is returned. If the values have embedded commas, use GetFieldValues instead to retrieve the array.
Grid	Embedded Report, Relational Grid	String value of the field. If multiple values are selected, a comma-separated list is returned. A path parameter is required to specify the column to retrieve values from.
Numeric	N/A	Numeric value of the field.
User, Single Selection, Single Relational	N/A	String value of the field.
Sub-Relational	N/A	Depends on the referenced field.
Summation	N/A	Numeric value of the field.
Text	N/A	String value of the field. For journal fields, the return value depends on what you specify in the path (see below). If the path is not included, the current editable contents (or an empty string if the field is read-only) are returned.

For journal fields, you can include the following tokens in the path (in any order):

• "" (a blank or non-existent path) – Returns an object that contains all properties of the most recent entry on a state form, or the current editable value on a transition.
• date – Returns the date of the most recent entry (returned as a JavaScript Date object).
• user – Returns the author of the most recent entry.
• userid – Returns the user ID for the author of the most recent entry.
• contents – Returns the plain or rich text value of the most recent entry. Contents are either un-escaped plaintext or HTML with tags (as determined by the Enable Rich Text option on the journal field).
• [] – Returns either:
  • An array of complete entry objects when by itself (for example, [])
  • An array of whatever type is specified by the property token when used in combination with [], starting with the oldest entry (for example, contents[])
  If the path does not contain [], only the most recent entry is returned. Also, the current editable entry is not returned (if any exists) in any case.
• DESC – Token that can be used in combination with [] to sort from most recent to oldest. For example, []DESC returns an array of all entries, sorted from most recent to oldest.

Including any one of the date, user, userid, or contents properties in the path returns only that specific part of the output value. If none of these are in the path, the output will be an object (or an array of objects) that contains all four properties. The path does not accept more than one property token; therefore, if you need more than one property returned, do not specify any of them.

Examples

This example returns the string value of the Unit Price field:

GetFieldValue("Unit Price");

This example returns the string value of a multi-relational field, or “none” if there is nothing to return:

GetFieldValue("MyMultiRelational", "none");

This example returns a comma separated list of IDs corresponding to selected rows on an embedded report, or an empty string if there is nothing to return:

GetFieldValue("MyEmbeddedReport", "", "IDs");

This example returns an array of string values corresponding to the Title sub-field of an embedded report’s selected rows, or “No items selected” if there is nothing to return:

GetFieldValue("MyEmbeddedReport", "No items selected", "Title[]");

This example returns an array of all the text entries from a journal field.

GetFieldValue("MyJournalField", [], "contents[]");

This example function could be placed in a form's included JavaScript files and would return the number of existing entries in a journal field.

function numJournalEntries(objname) {
  if (LookupFieldType(objname) != "text" || LookupFieldSubType(objname) != "journal") return 0;
  var contents = GetFieldValue(objname, [], "[]");
  return contents.length;
}

Comments

(none)