AgileApps Support Wiki Pre Release

Difference between revisions of "Field Scripts"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
Β 
(35 intermediate revisions by the same user not shown)
Line 1: Line 1:
===About Field Scripts===
===About Field Scripts===
Field scripts let you execute [[JavaScript]] when a field in a [[Form]] gets focus or its value changes.
{{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: Β 
JavaScript code can be run at these field-level events: Β 
Line 9: Line 10:
See [[Field Scripting Variables]] for information on variable syntax.
See [[Field Scripting Variables]] for information on variable syntax.


:''Compare to [[Forms#Form Scripting|Form Scripting]] and [[Post Selection JavaScript]]''
:''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:
You can add On Change or On Focus event scripts to any field ''except'' the following:
Line 25: Line 28:
==== Editing Field Scripts ====
==== Editing Field Scripts ====
Follow these steps to add or change event scripting for a field:
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.}}


# Click the script icon ([[Image:script_icon.gif]]) next to a field in the layout
# Click the script icon ([[Image:script_icon.gif]]) next to a field in the layout
Line 30: Line 34:
# Click the '''Save''' button
# Click the '''Save''' button


==== Writing Field Scripts ====
==== Writing JavaScript ====
In the HTML document object model (DOM), the current form is named <tt>mainForm</tt>. For example, the line of code below gets a reference to the current form in the variable named <tt>form</tt>:
Using JavaScript, you can
:{|
:* [[Referencing Form Fields in JavaScript|Reference Fields]] in the current form.
<pre>var form = document._sdForm;</pre>
:* Use [[AJAX and REST]] to communicate with the platform.
|}


You can refer to a field in a form using the name under "Field Name" when you select '''[[File:GearIcon.png]] > Customization > Objects' > {object} > Fields'''. For example, the line of code below gets a reference to the <tt>first_name</tt> field, and puts it in the variable <tt>elem</tt>:
You can also use the implicit variable <tt>obj</tt> to refer to the field where the most recent event occurred.
:{|
<pre>var elem = sdForm[0].first_name;</pre>
|}
Β 
However, you can also use the implicit variable <tt>obj</tt> to refer to the current field where the event occurred.
Β 
Fields have two properties that you can access in code:
:* <tt>name</tt>: the name of the field
:* <tt>value</tt>: the value of the field


These examples show using the implicit variable <tt>obj</tt> with these properties:
These examples show using the implicit variable <tt>obj</tt> with these properties:
:{|
:<syntaxhighlight lang="javascript" enclose="div">
<pre>alert("Selected field's name: " + obj.name);
alert("Selected field's name: " + obj.name);
Β 
alert("Selected field's value: " + obj.value);
alert("Selected field's value: " + obj.value);
</pre>
</syntaxhighlight>
|}
Β 
Use [[AJAX and REST]] to communicate with the platform in JavaScript code.


==== On Change Examples ====
==== On Change Examples ====
=====Check Approval Status=====
When a user changes an order, if a discount is given, make sure that <tt>approval_required</tt> is checked.
When a user changes an order, if a discount is given, make sure that <tt>approval_required</tt> is checked.
:{|
:<syntaxhighlight lang="javascript" enclose="div">
<pre>
if (_sdForm[0].discount.value != '0') {
var form = document.mainForm;
Β  setCheckboxState(_sdForm, "approval_required", true);
Β 
if (form.discount.value != '0')
{
Β  form.approval_required.checked = true;
}
}
</pre>
</syntaxhighlight>
|}


=====Capitalize a Name=====
When a user enters a first name, capitalize it automatically:
When a user enters a first name, capitalize it automatically:
:{|
:<syntaxhighlight lang="javascript" enclose="div">
<pre>
<pre>
var form = document.mainForm
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>


form.test.value = form.test.value.toUpperCase();
=====Display an Alert with Multiple Values=====
// The line above could also be written as:
Display an alert dialog showing the values selected from multiple checkboxes.
// obj.value = obj.value.toUpperCase();
:<syntaxhighlight lang="javascript" enclose="div">
</pre>
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 <tt>job_knowledge_notes</tt> field, copy the new value to the <tt>dependability_notes</tt> field.
When a user changes the <tt>job_knowledge_notes</tt> field, copy the new value to the <tt>dependability_notes</tt> field.
:{|
:<syntaxhighlight lang="javascript" enclose="div">
<pre>
var note = _sdForm[0].job_knowledge_notes.value;
document.mainForm.dependability_notes.value = document.mainForm.job_knowledge_notes.value
setTextFieldValue(_sdForm, "dependability_notes", note);
</pre>
</syntaxhighlight>
|}
Β 
Display an alert dialog showing the value of a checkbox.
:{|
<pre>
var form = document.mainForm;
var value = form.multicheckbox[0].value;
alert( "Multi Check Box Value is: " + value);
</pre>
|}
Β 
Change the value of text area field based on a variable.
:{|
<pre>
var form = document.mainForm;


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


{{:Change Checkbox Value Script}}
{{:Change Checkbox Value Script}}
Line 121: Line 99:
==== On Focus Example ====
==== On Focus Example ====
When a user moves the focus to the account name field, remind the user to enter the name capitalized.
When a user moves the focus to the account name field, remind the user to enter the name capitalized.
:{|
:<syntaxhighlight lang="javascript" enclose="div">
<pre>
var form = document.mainForm;
alert("Please enter the account name in all caps");
alert("Please enter the account name in all caps");
</pre> Β 
</syntaxhighlight>
|}


==== Grid Field Scripting ====
==== Grid Field Scripting ====
You can run [[JavaScript]] code at on change and on focus events in grid fields.
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:
Follow these steps to add event scripting to a grid field:
Line 141: Line 116:
* <tt>grid_section_row_id</tt>: current row identifier
* <tt>grid_section_row_id</tt>: 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 these fields with the statements below:
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">
<pre>
var firstname = eval('_sdForm[0].'+grid_section+'first_name');
var fullname = eval('document.mainForm.'+grid_section+'full_name');
var lastname = eval('_sdForm[0].'+grid_section+'last_name');
var firstname = eval('document.mainForm.'+grid_section+'first_name');
</syntaxhighlight>
var lastname = eval('document.mainForm.'+grid_section+'last_name');
</pre>
|}


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:
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">
<pre>
var fullname = firstname.value + ' ' + lastname.value;
fullname = firstname.value + ' ' + lastname.value;
setTextFieldValue(_sdForm, "full_name", fullname);
</pre>
</syntaxhighlight>
|}


===Learn More===
===Learn More===
:* [[Referencing Form Fields in JavaScript]]
:* [[Field Name|Field Name and Field Value]] syntax
:* [[Field Name|Field Name and Field Value]] syntax
:* Use [[AJAX and REST]] to communicate with the platform in JavaScript code. Β 
:* Use [[AJAX and REST]] to communicate with the platform in JavaScript code. Β 
:* [[Global JavaScript Variables]]
:* [[JavaScript Functions]]
:* [[JavaScript#Accessing_Additional_Lookup_Variables_in_a_Form|Accessing Additional Lookup Variables in a Form]]
:* [[JavaScript#Accessing_Additional_Lookup_Variables_in_a_Form|Accessing Additional Lookup Variables in a Form]]
<noinclude>
<noinclude>

Latest revision as of 10:59, 13 August 2020

About Field Scripts

Notepad.png

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:

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:

Notepad.png

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 (Script icon.gif) 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

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:

alert("Selected field's name: " + obj.name);
alert("Selected field's value: " + obj.value);

On Change Examples

Check Approval Status

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

if (_sdForm[0].discount.value != '0') {
   setCheckboxState(_sdForm, "approval_required", true);
}
Capitalize a Name

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

<pre>
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();
Display an Alert with Multiple Values

Display an alert dialog showing the values selected from multiple checkboxes.

var values = getMultiCheckBoxValue(_sdForm, "assets", 0); 
    // Returns a list. For example: ["Laptop", "Cellphone"]
alert( "Multi Check Box Values are: " + values);
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.

var note = _sdForm[0].job_knowledge_notes.value;
setTextFieldValue(_sdForm, "dependability_notes", note);
Conditional Change to a Value

Change the value of a text area based on a variable.

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") 
}

Change the value of a checkbox field to true when the request amount is large enough.

if(_sdForm[0].request_amount.value > 10000) {
    setCheckboxState(_sdForm, "approval_required", true);
}

On Focus Example

When a user moves the focus to the account name field, remind the user to enter the name capitalized.

alert("Please enter the account name in all caps");

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:

  1. Click the script icon (Script icon.gif) in the column header of a field in a grid.
  2. Enter the JavaScript in On Change Script and/or On Focus Script.
  3. 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:

var firstname = eval('_sdForm[0].'+grid_section+'first_name');
var lastname = eval('_sdForm[0].'+grid_section+'last_name');

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:

var fullname = firstname.value + ' ' + lastname.value;
setTextFieldValue(_sdForm, "full_name", fullname);

Learn More