The Action script contains instructions that will be executed when calling an action. If you're not yet familiar with SIL, read see Simple Issue Language Usageusage.
If the action required some 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 immediately followed by the value entered. For multi value fields, if you selected no value was selected, the label is immediately followed by an empty value. If you selected one or more values were selected, 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 plugin-specific SIL routines.
| Category | Used with | Routine | Return value |
|---|---|---|---|
| Single value fields |
| 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 otherwiseif not. |
| Multi value fields |
| BA_getMultiValues(argv, label) | String array representing the selected options. |
| 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 |
| BA_isChecked(argv, label) | Convenience 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) |
| BA_getDateValue(argv, label) | Will 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. |
...
| Note |
|---|
These methods are only available in versions 1.0.1 + and 2.0.1 +and above. |
For example, Let's take the following Screen Script :as example.
| Code Block |
|---|
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 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 might can also use these in conjunction with array-specific routines like arrayGetElement and arrayElementExists. See Array Routines for For a list of available routines that manipulate arrays, see Array Routines.
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Once you have a screen that requires an additional user input, it is necessary to validate that input and let the user know if s/he they did something wrong. This can be done by returning values from the script.
...
Generic errors show up in the upper part of the screen, as demonstrated shown below.
To do this, all you have to do is return the error message. Like this, like the following one for instance:
| Code Block |
|---|
string fruit = getElement(argv, 1);
if( isNull(fruit) ){
return "What? You don't like fruits?";
} |
...
If you have multiple input fields on the screen, it would be nice we recommend 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.
| Code Block |
|---|
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; |
...
Example
...
Iterating over uploaded files:
| Code Block |
|---|
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";
} |
...