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.

Category	Used with	Routine	Return value
Single value fields	text text area select list radio group single checkbox(optional)	BA_getSingleValue(argv, label)	String representing the value entered or the selected option for the given label. For a checkbox it will return "checked" if the checkbox was selected or an empty string if not.
Multi value fields	multi select list checkbox group	BA_getMultiValues(argv, label)	String array representing the selected options.
Multi value fields	file upload (available in v. 2.5 and above)	BA_getMultiValues(argv, label)	String array containing pairs of original filename and uploaded path. Even indices will contain original filenames, while odd indices will contain an uploaded path. See Examples for usage.
Checkbox	single checkbox	BA_isChecked(argv, label)	A method for checking whether a checkbox is selected or not. Returns a Boolean: true if the box was checked, false otherwise.
Date (since v2.0.8 and 2.6.1)	date picker date time picker	BA_getDateValue(argv, label)	This will retrieve a date value from the argv array. Note that for the date time picker, the value in the argv variable uses the user's time zone. BA_getDateValue will convert this value from the user's time zone to the server time zone.

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:

errors, array of BActionError (see below)
location, string, represents the potential URL to redirect to, leave empty if you want to avoid redirection
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:

field, string, the field in question, leave empty if you want a global error message
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.

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:

Contents

1 Basic Usage
2 Action Script
- 2.1 Generic Errors
  - 2.1.1 Field Validation Errors
3 Redirecting and Preventing Refresh
4 Example

See More