Basic Usage

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

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

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

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

Let's take the following Screen Script as example.

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 the following four 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 can also use these in conjunction with array-specific routines like arrayGetElement and arrayElementExists. For a list of available routines that manipulate arrays, see Array Routines.

Action Script 

Once you have a screen that requires an additional user input, it is necessary to validate that input and let the user know if they 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 shown below.

To do this, all you have to do is return the error message, like the following one for instance:

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, we recommend to validate them all at once and show errors for each one.

To do this, 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;

Redirecting and Preventing Refresh

Since version 4.5.5, Power Actions got the ability to redirect to some random page and also to prevent refresh. For this to happen, the return of the action should be of predefined type BActionReturn,  which is defined as having the following fields:

1. errors, array of BActionError (see below)

2. location, string, represents the potential URL to redirect to, leave empty if you want to avoid redirection

3. disableRefresh, a boolean, which, if set, will prevent the refresh to be automatically executed at the end of the action

BActionError is a simple structure, containing just two fields:

1. field, string, the field is in question, leave empty if you want a global error message

2. message, string, containing the message, probably you should put something here.
   

Resolution on the screen is performed in the usual way, if there are errors added in the return, the processing will stop and errors will be shown on the screen. If the location field is filled and there are no errors, a redirect will happen. If the location is empty but the disableRefresh flag is set, the screen will not be refreshed, as usual. This may come in handy when integrating with certain 3rd party addons.

//example excerpt:
................

BActionReturn ret;

if(thereAreErrors()) {
  BActionError e;
  e.message = "There are errors!"; //global
  ret.errors += e;
} else if(mustRedirect()) {
  ret.location = "https://google.com?q=SIL";
} else {
  ret.disableRefresh = true;
}

return ret;

We recommend you to use the structure above whenever possible, although the old way is still available (i.e. old scripts do not need to change).

Example

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