Action scripts

Action scripts are scripts that are run when an action button is selected on a node edit form. They are standard scripts run in execute mode, defined on the type of the node being edited.

An action button is simply an extra submit button on a form. Action buttons can be created using Display properties or using edit Extension scripts. Extension scripts are more flexible and powerful, and are the generally preferred method for anything other than very simple action scripts.

Action scripts are passed the request attribute of the SetNode request that triggered them, allowing them to access any field. 

Action scripts can return any combination of the fields described in Scripting basics.

This section provides some typical scenarios.

Additional validation

Use application.getContext() to access the node and to retrieve the values. If there are any errors, use application.setUserError() to pass these back to the edit screen. List the node references or the node version references of the members in error in the error fields (the third parameter to application.setUserError()).

Generally validation should be performed using the normal validation methods. Action scripts should only be used for additional validation prior to performing additional actions.

This rather daft example validates that the node is not named BINGO.

var context = application.getContext();
var nodeName = context.getValue('system.NODE_NAME');
if ( nodeName == 'BINGO' ) {
  application.setUserError('Invalid name','You can not call this node BINGO','system.NODE_NAME');
}

Updating the node

Use application.getNodeWritable() to get a writable version of the node. Set it and apply the changes as normal.

Then set the redirect back to this node with a method of edit. This will force the updated node data to be re-read before the edit screen is displayed.

In the example below, the node name is converted to upper case, and the user is given a message to indicate that this has been done. The processing is bypassed if the node is already in upper case.

var context = application.getContext();
var nodeName = context.getValue('system.NODE_NAME');
if ( nodeName != nodeName.toUpperCase() ) {
  // Make node name upper case
  var thisNode = application.getNodeWritable(application.getContext().getNodeVersionIdentifier());
  thisNode.setValue('system.NODE_NAME',nodeName.toUpperCase());
  thisNode.apply();
  var response = application.newServiceResponse('Response');
  response.put('redirect','${rootPath}' + application.nodeURL(thisNode) + '?method=edit');
  response.put('message','Node name changed to upper case');
}

Extension scripts

Simple actions can be coded using the Action Button display properties. However, creating action buttons using extension scripts provide much greater flexibility.

The generated buttons should have a name of the form

execute:method:parameters

Where method is the reference or identifier of the method to be executed, and parameters are the parameters to be passed. Within the action script, the parameters can be read using application.get('request').getString('actionParameter');

If the extension script that created the button also creates other fields, the values of these are available in the request. This allows the action script to interpret extra user input.

Standalone action scripts

Member types can use a Member Type Node Type Derivation Script (library.core.MemberTypeNodeTypeDerivationScript) method to add the method to be executed to the node type. For example, the script below shows how to add a method to a node type that then calls a standalone script, using the standalone script as the method.

var scriptEditAction = application.getBinding('scriptEditAction');
application.getContext().setValue(scriptEditAction,
"application.include('" + scriptEditAction + "');\n");

The expression to create an execute for this within an extension script would be something like:

'<button type="submit" class="btn btn-primary" name="execute:' + 
scriptEditAction + ':' + actionParameter + '">Edit</button>'

This would result in the standalone script scriptEditAction being called as an executed method when the Edit button is pressed.

Member type callbacks

The prototype Questionnaire Prototype (library.question.QuestionnairePrototype) defines a Member Type Callback Method (library.question.MemberTypeCallbackMethod). The parameters to this are the identity of a member type and further parameters, i.e. the whole execute is:

execute:callback method:member type:member type method

Where callback method the reference or identifier of Member Type Callback Method, member type is the reference or identifier of a member type (which must be defined for the node type), and member type method is a method on the member type.

This can be used to call a method on the member type itself, allowing member types to code their own action scripts.

Standalone action scripts (see above) are a newer and more preferred method.