Difference between revisions of "Form Scripts"

From AgileApps Support Wiki
imported>Aeric
Β 
(125 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''Designer > Data > Objects > {object} > Forms > {form} > [Edit Form Script]'''
===About Form Scripts===
Β 
Form Scripting lets you specify [[JavaScript]] code to execute when a [[Form]] is loaded or saved.
===About Form Scripting===
Β 
:''Compare to [[Post Selection JavaScript]] and [[Field Scripting]]''


JavaScript code can be invoked at these form-level events:
JavaScript code can be invoked at these form-level events:
Line 12: Line 9:
:::''Learn more: [[#Trigger on a Specific Action|Trigger on a Specific Action]]''
:::''Learn more: [[#Trigger on a Specific Action|Trigger on a Specific Action]]''
:*;On Save: Β 
:*;On Save: Β 
::*This event happens when a user clicks the [Save] button on a form
::*This event happens when a user clicks the '''[Submit]''' button on a form
::*At this event, optionally perform custom front-end validations before sending the data to the server
::*At this event, optionally perform custom front-end validations before sending the data to the server
::*Return false to cancel the save
::*Return false to cancel the save
:*;Resusable Script Functions:
:*;Reusable Script Functions:
::*Available to be called for the On Load or On Save event scripts
::*Available to be called from the On Load or On Save event form scripts
::*Also available to be called from the On Change and On Focus event field scripts
Β 
:''Learn more:''
::* Compare to [[Post Selection JavaScript]] and [[Field Scripting]]
::* Using [[AJAX and REST]] to communicate with the platform


===Working with Form Scripts===
===Working with Form Scripts===
{{Note| Please note that all the examples listed in this page are limited to the legacy AgileApps UI and not the new runtime AgileApps UI.}}


====Editing Form Scripts====
====Editing Form Scripts====
Follow these steps to add or change scripting in a form:
Follow these steps to add or change scripting in a form:
# Click '''Designer > Data > Objects > {object} > Forms'''
{{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]])
# Click '''[Form Script]'''
# Enter or change the JavaScript in '''On Load Script''', '''On Save Script''', and/or '''Reusable Script Functions'''.
# Click '''[Edit]'''
# Click the [Save] button.
# Enter or change the JavaScript in '''On Load Script''', '''On Save Script''', and/or '''Reusable Script Functions'''
Β 
# Click '''[Save]'''
====Writing Form Scripts====


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>:
==== Writing JavaScript ====
:{|
Using JavaScript, you can
<pre>var form = document.mainForm;</pre>
:* [[Referencing Form Fields in JavaScript|Reference Fields]] in the current form.
|}
:* 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 '''Designer > Data > Objects > {object} > Fields'''. For example, the line of code below gets a reference to the <tt>firstName</tt> field in the variable <tt>elem</tt>:
===On Load Examples===
:{|
<pre>var elem = document.mainForm.firstName;</pre>
|}


Fields have two properties that you can access in code:
These examples perform operations when a form is loaded.
:* <tt>name</tt>: the name of the field
:* <tt>value</tt>: the value of the field


;Example - Update the field value of a text field:
====Add a Help Button to an Arbitrary Form====
This code works for forms in all objects, including Cases, Tasks, and custom objects. And it works when adding a new record, as well as when viewing an existing record.
For information about adding a help button to a form, see the tech community article [https://tech.forums.softwareag.com/t/adding-a-custom-button-to-an-arbitrary-form-using-form-script/237542 Adding a Custom Button to an Arbitrary Form using Form Script].


To update the field value of a text field <tt>first_name</tt>, use the following syntax:
====Convert a Date====
:<tt>form.first_name.value = "Adam"</tt>
Create readable date string from the current date for display in the <tt>order_date</tt> field.
Β 
:{| border="0" cellpadding="5" cellspacing="0"
;Example - Update the field value of a Lookup field:
Β 
To update the field value of a [[Lookup]] field, two parameters are required:
:;RecordID:<tt>lookup.value</tt>
::This is the [[Record Identifier]] of the record in the object
:;Field value:<tt>lookup_name.value</tt>
::This is the value of the record in the object
Β 
To update the field value of a lookup field (<tt>project_number</tt>), use the following syntax:
:{|
<pre>
form.project_number.value = "123456";
// 123456 is the internal record identifier of the record present in lookup object
form.project_number_name.value = "My Project";
// My project is the value present in the record locator field(s) of the lookup object
</pre>
|}
Β 
Use [[AJAX and REST]] to communicate with the platform in JavaScript code.
Β 
====On Load Examples====
Β 
Set the opportunity name with the account name when adding an opportunity.
:{|
<pre>
<pre>
var form = document.mainForm;
form.name.value = form.reference_id_name.value;
</pre>
|}
Convert the current date into day name, month name, and day number format and puts the resulting value in the <tt>account_order</tt> field.
:{|
<pre>
var form = document.mainForm;
var v1 = new Date(); Β 
var v1 = new Date(); Β 
var v2 = new Array('Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thurs', 'Fri', 'Sat', 'Sun'); Β 
var v2 = new Array('Sun', 'Mon', 'Tues', 'Wed', 'Thu', 'Fri', 'Sat'); Β 
var v3 = new Array('Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'); Β 
var v3 = new Array('Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', Β 
form.account_order.value = v2[v1.getDay()] + " " + v3[v1.getMonth()] + " " + v1.getDate(); Β 
Β  Β  Β  Β  Β  Β  Β  Β  Β  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'); Β 
date_string = v2[v1.getDay()] + " " + v3[v1.getMonth()] + " " + v1.getDate();
setTextFieldValue(_sdForm, "order_date", date_string);
</pre>
</pre>
|}
|}


=====Trigger on a Specific Action=====
====Trigger on a Specific Action====
To invoke a script On Load + Action (View, Update, Add or Clone a record):
To invoke a script On Load + Action (View, Update, Add or Clone a record):
{{Note|For new UI, see the section '''Variables and Methods Introduced in the Revamped UI ''' in [[JavaScript Field Type Reference for New AgileApps User Interface]]}}


Trigger on record ''View'':
Trigger on record ''View'':
:{| border="0" cellpadding="5" cellspacing="0"
:{| border="0" cellpadding="5" cellspacing="0"
|<pre>
|<pre>
var action = document.mainForm.a.value;
var action = _sdForm.get(0).a.value;
if ( action == "view") {
if ( action == "view") {
// java script to be triggered on the update of the record only
Β  // java script to be triggered on the view of the record only
<!--...-->
Β  ...
}
}
</pre>
</pre>
Line 108: Line 75:
:{| border="0" cellpadding="5" cellspacing="0"
:{| border="0" cellpadding="5" cellspacing="0"
|<pre>
|<pre>
var action = document.mainForm.a.value;
var action = _sdForm.get(0).a.value;
if ( action == "update") {
if ( action == "update") {
// java script to be triggered on the update of the record only
Β  // java script to be triggered on the update of the record only
<!--...-->
Β  ...
}
}
</pre>
</pre>
Line 118: Line 85:
Trigger on record ''Add'' or ''Clone'':
Trigger on record ''Add'' or ''Clone'':
:{| border="0" cellpadding="5" cellspacing="0"
:{| border="0" cellpadding="5" cellspacing="0"
|<pre>var action = document.mainForm.a.value; Β 
|<pre>var action = _sdForm.get(0).a.value; Β 
if ( action == "add") {
if ( action == "add") {
//java script to be triggered on the add or clone of the record only
Β  //java script to be triggered on the add or clone of the record only
<!--...-->
Β  ...
}
}
</pre>
</pre>
|}
|}


====On Save Examples====
===On Save Examples===


Make sure there is a contact when creating an opportunity.
For examples related to the On Save action, see the tech community article [https://tech.forums.softwareag.com/t/perform-custom-validations-using-form-script-in-agileapps/237545 Perform Custom Validations using Form Script in AgileApps].
:{|
<pre>
var form = document.mainForm;
if (form.reference_type[form.reference_type.selectedIndex].value == 'Lead')
{
Β  Β  if (form.contact_id.value == "")
Β  Β  {
Β  Β  Β  alert("Please enter Contact Name");
Β  Β  Β  return false; // cancel the save operation
Β  Β  }
}
</pre>
|}
Β 
If a user checked the "Done" radio button in a radio button group named <tt>technical_spec_completed</tt>, set the <tt>spec_date</tt> field with the current date formatted as month number, day number, and year.
:{|
<pre>
var form = document.mainForm;
function formatDate(value)
{
Β  Β  return value.getMonth()+1 + "/" + value.getDate() + "/" + value.getFullYear();
}
for (var i=0; i<form.technical_spec_completed.length; i++) {
Β  Β  if(form.technical_spec_completed[i].checked &&
Β  Β  Β  Β  form.technical_spec_completed[i].value == 'Done' && form.spec_date.value == '')
Β  Β  {
Β  Β  Β  Β  t = new Date();
Β  Β  Β  Β  form.spec_date.value = formatDate(t);
Β  Β  }
}
</pre>
|}
Β 
The email address field on a form is not mandatory, but you want to encourage users to enter it. If the user clicks OK in the confirm dialog, it cancels the save so they can then enter the email address. If they click cancel, the save proceeds.
:{|
<pre>
var form = document.mainForm;
Β 
if(form.email.value=="")
Β  Β  if (confirm("While the Email field is optional, we recommend that you
enter a value"))
Β  Β  {
Β  Β  Β  Β  //User clicked OK: do not proceed with save
Β  Β  Β  return false;
Β  Β  else
Β  Β  {
Β  Β  Β  Β  //User clicked cancel: let save happen
Β  Β  Β  Β  return true;
Β  Β  }
}
</pre>
|}
Β 
{{:Change Checkbox Value Script}}


===Learn More===
===Learn More===
:* [[JavaScript Field Type Reference for New AgileApps User Interface]]
:* [[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]]
<noinclude>
Β 
[[Category:JavaScript]]
</noinclude>

Latest revision as of 05:12, 17 May 2024

About Form Scripts

Form Scripting lets you specify JavaScript code to execute when a Form is loaded or saved.

JavaScript code can be invoked at these form-level events:

  • On Load
  • This event happens when the form loads
  • By default, the On Load scripts are triggered on any record action (View, Add, Update)
Optionally, invoke the script on a specific action (View or Add or Update)
Learn more: Trigger on a Specific Action
  • On Save
  • This event happens when a user clicks the [Submit] button on a form
  • At this event, optionally perform custom front-end validations before sending the data to the server
  • Return false to cancel the save
  • Reusable Script Functions
  • Available to be called from the On Load or On Save event form scripts
  • Also available to be called from the On Change and On Focus event field scripts
Learn more:

Working with Form Scripts

Notepad.png

Note: Please note that all the examples listed in this page are limited to the legacy AgileApps UI and not the new runtime AgileApps UI.

Editing Form Scripts

Follow these steps to add or change scripting in a form:

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 [Form Script]
  2. Click [Edit]
  3. Enter or change the JavaScript in On Load Script, On Save Script, and/or Reusable Script Functions
  4. Click [Save]

Writing JavaScript

Using JavaScript, you can

On Load Examples

These examples perform operations when a form is loaded.

Add a Help Button to an Arbitrary Form

This code works for forms in all objects, including Cases, Tasks, and custom objects. And it works when adding a new record, as well as when viewing an existing record. For information about adding a help button to a form, see the tech community article Adding a Custom Button to an Arbitrary Form using Form Script.

Convert a Date

Create readable date string from the current date for display in the order_date field.

var v1 = new Date(); 
var v2 = new Array('Sun', 'Mon', 'Tues', 'Wed', 'Thu', 'Fri', 'Sat'); 
var v3 = new Array('Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 
                   'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'); 
date_string = v2[v1.getDay()] + " " + v3[v1.getMonth()] + " " + v1.getDate(); 
setTextFieldValue(_sdForm, "order_date", date_string);

Trigger on a Specific Action

To invoke a script On Load + Action (View, Update, Add or Clone a record):

Notepad.png

Note: For new UI, see the section Variables and Methods Introduced in the Revamped UI in JavaScript Field Type Reference for New AgileApps User Interface

Trigger on record View:

var action = _sdForm.get(0).a.value;
if ( action == "view") {
   // java script to be triggered on the view of the record only
   ...
}

Trigger on record Update:

var action = _sdForm.get(0).a.value;
if ( action == "update") {
   // java script to be triggered on the update of the record only
   ...
}

Trigger on record Add or Clone:

var action = _sdForm.get(0).a.value; 
if ( action == "add") {
   //java script to be triggered on the add or clone of the record only
   ...
}

On Save Examples

For examples related to the On Save action, see the tech community article Perform Custom Validations using Form Script in AgileApps.

Learn More