OnItemChange Script Information

The OnItemChange Script column contains a drop-down list of existing OnItemChange Groovy scripts that are available within the database. You may also right-click this column and then click the Create/Edit Script command to either edit the currently assigned script or create a new one. Scripts configured here are typically used for validating data as it is entered by a user. These scripts run whenever a user has edited the value in a column and the user moves the cursor off of the field by tabbing or saves data.
Certain variables that are available at run time may be included in the script. A partial list of the variables that are available is shown in the table below.

Note: Do not change the values of these variables in the script; this could cause system instability.

Variable

Description

OWNER_ID

This is the ID value of the user login admin unit.

new_val_in

This variable contains the proposed edit of the column by the user. This is typically the data value you would validate.

row_in

This is the row being edited. It is typically used to set or retrieve values of other data in the row for validation purposes.

col_in

This is the Column ID being edited.

user_id

This is the User ID of the person editing the data.

module_id

This is the current module ID.

Note: During evaluation, the new_val_in variable is always passed as a string to the script. This means that if the column is a number, then the proposed new value is still a string until you cast the value as a number. This should be done when performing calculations. The following are examples of this:

This gives a number with decimals:

parseFloat(new_val_in);

This gives an integer:

parseInt(new_val_in); 

This converts a date string to a date:

StrToDate(new_val_in); 

Validation

To validate data, you write a custom set of commands to check if the proposed edit by the user is allowed. If it is not allowed, you issue the following command:

EventReturnValue = -1;

Messaging

The function to display a message to the user is:

basic_window.ShowAlert(text identifier here);

To display actual text, use the following function:

basic_window.ShowAlert("Message Goes Here!!!");

Some Useful Non-standard Functions Provided by AgileAssets Software

  • GetItemDisplay( ) — If you need the text label shown on screen for a drop-down list, use the GetItemDisplay function. Note: This function should not be used for the column you are currently validating (use the GetChild().Lookup() function for this purpose). An example of this function is shown below:
    • this.GetItemDisplay(row_in, "ROUTE_ID")
      This function always returns a string value.
    • GetChild( ).Lookup( ) — This function will return the display text for the column currently being evaluated. For example, if you are validating a change to the ROUTE_ID column and it is a drop-down list, you could use this function to get the ROUTE_NAME corresponding to the ID the user chose (which is held in the variable new_val_in):
      this.GetChild("ROUTE_ID").Lookup(new_val_in)
      This function always returns a string value.
    • SetItem( ) — This function sets the value of a column to the specified value. For example, the following statement sets the LANE_DIR column to 2 for the current row:
      this.SetItem(row_in,"LANE_DIR",2);
      This function is not data-type dependent, but you should use proper data types for the column being adjusted.
    • GetItem() — This function gets the value of a column. Note that for a drop-down list, this returns the ID value and not the drop-down list text label. For example, the following statement gets the value of the WC_ID column for the current row:
      this.GetItem(row_in, "WC_ID");
      This function always returns the data type of the underlying column.

Example: Validate IS_ACTIVE_SECTION Field

/*Validate IS_ACTIVE_SECTION Column

 Rules are

1. WC_ID must be 1,2, or 3

2. Sous Code must be 000 

Only process if being set to Active (value 1)*/

if(new_val_in == "1") {

/*Get WC_ID Value*/

           var wc_id = this.GetItem(row_in, "WC_ID");

/*Get Sous Code*/

 if(this.IsValidColumn("ROUTE_ID")) 

         {

                   var dir_code = this.GetItemDisplay(row_in, "ROUTE_ID").substr(13,3);

         }

 else

         {    

         var dir_code =  this.GetItem(row_in, "SOUS_ROUTE").substr(1,3);

         }

/*Check Rules and Show message and Reject Edit if necessary*/

   if((wc_id != 2 && wc_id != 3 && wc_id != 1 )||dir_code != "000" ) {


      basic_window.ShowAlert("Le segment ne peut être à « Utilisé » s'il
 est sur gravier, sur structure ou sur une sous-route non principale.");

      EventReturnValue = -1;   

   }

}
  • No labels

Provide Feedback