The Action Script

The Action script contains instructions that will be executed when calling an action. If you're not yet familiar with SIL, read Simple Issue Language Usage.

If the action required some input from the user via the Screen Script, the values are placed in the argv variable. This is a string array containing ordered sequences of label and value(s) for the fields shown on the screen.

For single value fields, the array contains the field label immediately followed by the value entered. For multi value fields, if no value was selected, the label is immediately followed by an empty value. If one or more values were selected, the label is immediately followed by the number of values selected, and the selected values.

In order to help you retrieve the selected value(s) faster, we have created more plugin-specific SIL routines.

For example, take the following Screen Script:

BA_createCheckboxGroup("checkbox group", {"o1", "o2", "o3"}, {"o1", "o2"}, false);

Assuming the user did not change the default values, the argv variable in the action script will have 4 values: "checkbox group", "2", "o1", "o2". The result of BA_getMultiValues(argv, "checkbox group") would return an array with two values: o1 and o2.

If the user unchecked all the values, the argv variable would have only 2 values: "checkbox group" and an empty string.

You might also use these in conjunction with array-specific routines like arrayGetElement and arrayElementExists. See Array Routines for a list of available routines that manipulate arrays.

Validating the Screen Fields

Once you have a screen that requires additional user input, it is necessary to validate that input and let the user know if s/he did something wrong. This can be done by returning values from the script.

Generic Errors

Generic errors show up in the upper part of the screen, as demonstrated below.

To do this, all you have to do is return the error message. Like this:

string fruit = getElement(argv, 1);

if( isNull(fruit) ){
	return "What? You don't like fruits?";
}

Field Validation Errors

If you have multiple input fields on the screen, it would be nice to validate them all at once and show errors for each one.

To do this, you will have to return an array containing pairs of label and error. 

string fruitLabel = getElement(argv, 0);
string fruit = getElement(argv, 1);

string chocolateLabel = getElement(argv, 2);
string chocolate = getElement(argv, 3);

string [] errors;

if( isNull(fruit) ){
 	errors = addElement(errors, fruitLabel);
	errors = addElement(errors, "What? You don't like fruits?");
}

if( chocolate != "yes" and chocolate != "of course"){
	errors = addElement(errors, chocolateLabel);
	errors = addElement(errors, "No way!");
}

return errors;

Examples

Example 1

Iterating over uploaded files

string [] files = BA_getMultiValues(argv, "file");
for(int i = 0; i < size(files); i+=2){
 number ORIGINAL_NAME = i;
 number NEW_PATH = i + 1;
 desc += "File " + files[ORIGINAL_NAME] + " was uploaded to " + files[NEW_PATH] + "\n";
}