Action Definition: General Information

To provide users with functionality that is specific to their business needs, you can create actions and make the associated buttons and commands available on the UI. You implement the actions in a graph. You can configure the availability and visibility of the buttons and commands based on specific criteria.

In this chapter, you will learn how to create an action with a corresponding button on the form toolbar and the table toolbar.

Learning Objectives

In this chapter, you will learn how to do the following:

Create an action, the associated button on the form toolbar, and the equivalent command on the More menu
Configure the availability and visibility of the button and command depending on field values on the form
Create actions and the associated buttons on the table toolbar of multiple tabs
Configure the location of the buttons on the table toolbar of each tab

Applicable Scenarios

You implement an action in the following cases:

You want to redirect a user to a specific form or report.
You want to modify or validate data records and save changes to the database.
You want to start a background operation, which is executed on a separate thread.

Action Declaration in a Graph

The declaration of an action in a graph consists of the following:

A field of the PXAction<> type, which is declared as follows.
```
public PXAction<Shipment> CancelShipment;
```
In the PXAction<> type parameter, you should specify the main DAC of the primary data view. Otherwise, the button corresponding to the action cannot be displayed on the form toolbar (and the corresponding command cannot be displayed on the More menu).
A method that implements the action; this method has the PXButton and PXUIField attributes. This method has the following forms of declaration:
- Without parameters and returning void: This standard form of declaration is shown in the following code example.
```
[PXButton]
[PXUIField(DisplayName = "Cancel Shipment")]
protected virtual void cancelShipment()
{
    ...
}
```
  This type of declaration is used for an action that is executed synchronously and is not called from a processing form.
- With a parameter of the PXAdapter type and returning IEnumerable: You can see an example of this form of declaration in the following code.
```
[PXButton]
[PXUIField(DisplayName = "Release")]
protected virtual IEnumerable release(PXAdapter adapter)
{
    ...
    return adapter.Get();
}
```
  This type of declaration should be used when the action initiates a background operation or is called from a processing form.

The field and the method should have the same name, differing only in the capitalization of the first letter.

Tip: A graph includes the Actions collection of all PXAction<> objects defined in the graph.

Callback on the Action

When a user invokes an action through a button or command on the UI, the page sends a request to the server side of the application (that is, it executes the callback). By default, for a button or command, the callback is always executed—that is, the CommitChanges property of the PXButton attribute is true. If you do not need the form to send the recent changes made on the form, set the CommitChanges property of the PXButton attribute to false as follows.

[PXButton(CommitChanges = false)]

The CommitChanges property must be always set to true for the actions that cause changes to be saved to the database.

Configuration of the Button and Command Associated with an Action

You can adjust the availability and visibility of a button or command (or both, if applicable) on the UI that is associated with an action at runtime (for example, to make the button or command unavailable or hidden) by using event handlers, attributes, or the workflow API. For details, see Action Customization: Disabling or Enabling of an Action and Action Customization: Visibility of an Action.

The following code example show how to set the availability of a button inside an event handler. To do this, you should use the methods of the PXAction<> class, as the following code example shows.

// Disabling the CancelShipment action
CancelShipment.SetEnabled(false);

You do not use the static methods of the PXUIField attribute, because these methods work only with the attribute copies stored in PXCache objects.

For more information about actions and how to customize them, see Action Customization: General Information.