Skip to end of metadata
Go to start of metadata

Cprime Apps has been rebranded as Anova Apps. Please note the only effect is the company name - all of our products’ names, logos, functionalities, support, etc. is exactly the same. The new location to our documentation space is https://anovaapps.atlassian.net.


On this page:


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.

CategoryUsed withRoutineReturn 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.
  • file upload
    (available in v. 2.5 and above)
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.

These methods are only available in versions 1.0.1 and 2.0.1 and above.


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

See also

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels