Individual Field objects manage a single field for a single submission. They can be mass-manipulated with the Field Management object. In this documentation submission.fields.first() will be used to refer to a generic field, but other lookup methods can be used interchangeably.
column_name
This method is available to server-side scripts.
Returns the script-accessible variable name for the field. By default this is a snake_case of the current field name.
submission.fields.first().column_name
container
Returns the wrapping container for the field's DOM element.
submission.fields.first().container
default(value)
This method is available to server-side scripts.
Sets the value of the field, if the field's value is empty. This is a wrapper around the value method, and allows quick default values from custom scripts.
submission.fields.first().default("Default Value")
empty()
This method is available to server-side scripts.
Returns a boolean indicating whether the field is empty. This should be used instead of directly checking if field.value() is empty because advanced field types like Address fields can return objects with empty keys rather than a directly falsey value.
submission.fields.first().empty()
error(text)
This method is available to server-side scripts.
Adds user-visible error text to the field. This is equivalent to errors.add(text)
submission.fields.first().error("There's a problem here!")
submission.fields.first().errors.add("This is an equivalent method!")
errors
This method is available to server-side scripts.
Returns an Error Management object to control errors for this field.
submission.fields.first().errors.all()
submission.fields.first().errors.add("Error Text")
submission.fields.first().errors.any()
hide()
Hides this field's DOM element on the page. This is the reverse of show.
submission.fields().first.hide()
menu(options)
Adds a menu option to the field. A menu icon will be added to the field's name which will open a dropdown with the field's options when clicked. Options can open links or trigger callback functions when they are clicked.
submission.fields.first().menu({
label: "Remove Value",
callback: function(event) {
this.value("");
}
});
The callback function is executed in the context of a field, but you can reference the submission with the submission field property.
submission.fields.first().menu({
label: "Remove Another Field's Value",
callback: function(event) {
this.submission.fields.second().value("");
}
});
Field menu options can be made into links that open in a new tab with the href option.
submission.fields.first().menu({
label: "More Information",
href: "https://info.sonadier.com"
});
If a field's label is ---, it will be made into a separator line to separate sections.
submission.fields.first().menu({
label: "---"
});
For example, the code below will set a date or time field's value to the current time when clicked.
submission.fields.first().menu({ label: "Set to Now", callback: function(e) {
date = new Date();
/* JavaScript returns months starting with January as 0 */
this.value({
year: date.getFullYear(),
month: date.getMonth() + 1,
day: date.getDate(),
hour: date.getHours(),
minute: date.getMinutes()
});
}});
name
This method is available to server-side scripts.
Returns the user-friendly name of the field.
submission.fields.first().name == "Field Name"
show()
Makes this field's DOM element visible on the page. This is the reverse of hide.
type
This method is available to server-side scripts.
Returns a string indicating the field's type. A full list of field types can be found at field types.
submission.fields.first().type == "text"
valid()
This method is available to server-side scripts.
Returns a boolean indicating whether any errors are currently present for the submission. This does not run any validations, only checks the current status. A value of true means that there are no errors associated with the submission.
submission.fields.first().valid()
value(field_value = undefined)
This method is available to server-side scripts.
Returns the value of a field. This method also accepts an optional field_value parameter to set the value of the field. It's strongly recommended that you use this method instead of directly setting the .val() for an input, as it handles advanced field types naturally. For example, the Address field accepts a hash of values for its sub-fields.
submission.fields.text_field.value("My Text Value")
submission.fields.address_field.value({ street_address: "1234 Sonadier Drive." })
If you leave out the key for a sub-field in an advanced field value object, its value won't be affected. This means you can set the Addresses street_address without affecting the state or country. You must directly send an empty key to clear the value of a subfield.