Field Scripts

About Field Scripts

Note: All the examples listed in this page are applicable to the old AgileApps UI and not the revamped UI.

Field scripts let you execute JavaScript when a field in a Form gets focus or its value changes.

JavaScript code can be run at these field-level events:

• On Change - This event happens when a user enters a new value in a field. At this event you can change other fields based on the value a user just entered or change the formatting of the value (such as for a telephone number).
• On Focus - This event happens when a user moves the focus to a field. At this event you can remind the user what to enter or temporarily change the appearance of the field (set as setting the background color).

See Field Scripting Variables for information on variable syntax.

See also:

• Form Scripts for operations at the Form level
• Post Selection JavaScript to use additional variables available for Lookup fields

You can add On Change or On Focus event scripts to any field except the following:

• Auto Number
• Custom Control
• File field
• Formula
• Image field
• Lookup
• Multi object Lookup
• Rich Text Area

Working with Field Scripts

Editing Field Scripts

Follow these steps to add or change event scripting for a field:

Note: To run the JavaScript in the LongJump UI and the legacy AgileApps UI, enter the script in the Legacy UI Script tab. To run the JavaScript in the New AgileApps UI, enter the script in the New UI Script tab.

1. Click the script icon () next to a field in the layout
2. Enter or change the JavaScript in Field On Change Script and/or Field On Focus Script
3. Click the Save button

Writing JavaScript

Using JavaScript, you can

• Reference Fields in the current form.
• Use AJAX and REST to communicate with the platform.

You can also use the implicit variable obj to refer to the field where the most recent event occurred.

These examples show using the implicit variable obj with these properties:

<syntaxhighlight lang="javascript" enclose="div">

alert("Selected field's name: " + obj.name); alert("Selected field's value: " + obj.value); </syntaxhighlight>

On Change Examples

Check Approval Status

When a user changes an order, if a discount is given, make sure that approval_required is checked.

<syntaxhighlight lang="javascript" enclose="div">

if (_sdForm[0].discount.value != '0') {

  setCheckboxState(_sdForm, "approval_required", true);

} </syntaxhighlight>

Capitalize a Name

When a user enters a first name, capitalize it automatically:

<syntaxhighlight lang="javascript" enclose="div">

var upperName = _sdForm[0].first_name.value.toUpperCase();
setTextFieldValue(_sdForm, "first_name", upperName);
   // The line could also be written as:
   // obj.value = obj.value.toUpperCase();
</syntaxhighlight>

Display an Alert with Multiple Values
Display an alert dialog showing the values selected from multiple checkboxes.
:<syntaxhighlight lang="javascript" enclose="div">
var values = getMultiCheckBoxValue(_sdForm, "assets", 0); 
    // Returns a list. For example: ["Laptop", "Cellphone"]
alert( "Multi Check Box Values are: " + values);
</syntaxhighlight>

Copy a Field in the Current Record
When a user changes the job_knowledge_notes field, copy the new value to the dependability_notes field.
:<syntaxhighlight lang="javascript" enclose="div">
var note = _sdForm[0].job_knowledge_notes.value;
setTextFieldValue(_sdForm, "dependability_notes", note);
</syntaxhighlight>

Conditional Change to a Value
Change the value of a text area based on a variable.
:<syntaxhighlight lang="javascript" enclose="div">
if(obj.value == "Record1") {
    setTextFieldValue(_sdForm, "description", "First Record") 
}
if(obj.value == "Record2") {
    setTextFieldValue(_sdForm, "description", "Second Record") 
}
else {
    setTextFieldValue(_sdForm, "description", "Not first or second record") 
}
</syntaxhighlight>

Change the value of a checkbox field to true when the request amount is large enough.
:<syntaxhighlight lang="javascript" enclose="div">
if(_sdForm[0].request_amount.value > 10000) {
    setCheckboxState(_sdForm, "approval_required", true);
}
</syntaxhighlight>

On Focus Example
When a user moves the focus to the account name field, remind the user to enter the name capitalized.
:<syntaxhighlight lang="javascript" enclose="div">
alert("Please enter the account name in all caps");
</syntaxhighlight>

Grid Field Scripting
You can run JavaScript code for On Change and On Focus events in grid fields.

Follow these steps to add event scripting to a grid field:

# Click the script icon () in the column header of a field in a grid.
# Enter the JavaScript in On Change Script and/or On Focus Script.
# Click the Save button.

You can refer to these implicit variables in event scripts for grid fields:
* grid_section: current grid name used as a prefix for field names
* grid_section_row_id: current row identifier

For example, assume that you have a grid with these field names: full_name, first_name, and last_name. You can create references to the fundamental fields with the statements below:
:<syntaxhighlight lang="javascript" enclose="div">
var firstname = eval('_sdForm[0].'+grid_section+'first_name');
var lastname = eval('_sdForm[0].'+grid_section+'last_name');
</syntaxhighlight>

You can then update the full_name field automatically in an On Change event script for the first name or last name field with this code:
:<syntaxhighlight lang="javascript" enclose="div">
var fullname = firstname.value + ' ' + lastname.value;
setTextFieldValue(_sdForm, "full_name", fullname);
</syntaxhighlight>

Learn More
:* Referencing Form Fields in JavaScript
:* Field Name and Field Value syntax
:* Use AJAX and REST to communicate with the platform in JavaScript code. 
:* JavaScript Functions
:* Accessing Additional Lookup Variables in a Form