Actions

• Feb 24, 2022
• 8 minutes to read

Many features of a typical business application require end-user interaction. For example, end-users may delete a record, save changes, refresh data, apply a filter, etc. In the eXpressApp Framework, such features are implemented via Actions. In this topic, you will learn what Action types are supplied by XAF and how to use these Actions properly.

Action Overview

Actions are abstract UI elements that allow you to perform specific operations in response to an end-user’s manipulations. They are displayed in a UI via specified Action Containers. Thus, an Action can be represented by a toolbar button, a context menu item, an editor, a simple button, etc. To access all Actions in a particular Action Container, use the container’s IActionContainer.Actions property.

Actions are contained within Controllers in their Controller.Actions lists. To create a new Action, you will need to create a new Controller or customize an existing one. An Action’s presence on a particular Window (Frame) depends on whether the corresponding Controller is registered in it or not. Note that you can also specify the availability context for individual Actions via their properties.

The base class for all Action types is the ActionBase class. This class provides events, properties and methods that support the common Action behavior. They are:

• ActionBase.Executing and ActionBase.Executed events

  Occur when an end-user performs a specified manipulation: clicks a button, selects an item in a combo box, etc. These event handlers implement the actual Action functionality.

• ActionBase.Active property

  Provides access to a collection of reasons detailing why an Action was activated/deactivated. The Action is active (visible) if the collection does not contain a reason for deactivation. Use this collection’s methods to add/remove reasons for changing the Action’s active state. To determine whether an Action is active (visible) in the current context, use this property in a conditional expression. Alternatively, use the BoolList.ResultValue property of the object returned by this property.

• ActionBase.Enabled property

  Provides access to a collection of reasons why an Action was enabled/disabled. The Action is enabled (its control is enabled) if the collection does not contain a reason for disabling it. Use this collection’s methods to add/remove reasons for changing the Action’s enabled state. To determine whether an Action is enabled in a current context, use this property in a conditional expression.

• ActionBase.TargetViewType, ActionBase.TargetViewNesting, ActionBase.TargetViewId, ActionBase.TargetObjectType, ActionBase.TargetObjectsCriteria, ActionBase.TargetObjectsCriteriaMode and ActionBase.SelectionDependencyType properties

  Specify the conditions (view type, view ID, object type, etc.) for activation of an Action in a particular controller. These conditions are checked only for Actions from View Controllers.

• ActionBase.Category property

  Specifies one of the predefined categories. The category specifies the Action Container that will display this Action.

• ActionBase.ConfirmationMessage property

  Specifies the text of the confirmation message invoked before executing the Action.

• There are many other events, properties and methods (such as ActionBase.Caption, ActionBase.ImageName and ActionBase.TargetObjectsCriteria, etc.) that you can find in the Reference help section.

Action Types

The eXpressApp Framework supplies several Action types derived from the ActionBase class. Each type is intended for different requirements, and Action Containers use different controls to display them (buttons, editors, combo boxes, etc.). All these Action types are defined in the following table.

Action	Description
SimpleAction	In most cases, this Action is displayed as a button and the SimpleAction.Execute event is raised when the button is clicked. This event handler’s parameters provide access to the ISelectionContext object, which specifies current and selected objects.
PopupWindowShowAction	Used to invoke a pop-up window with a View. When the pop-up window is being generated, the PopupWindowShowAction.CustomizePopupWindowParams event is raised. Handle this event to set the View to be displayed within the pop-up window. In addition to the View, the pop-up window contains the accept and cancel buttons. If you need to display more controls or need to perform other modifications, you can customize the pop-up window’s template by handling the PopupWindowShowAction.CustomizeTemplate event. On clicking the accept button, the Action’s PopupWindowShowAction.Execute event is raised. To access data customized within the View, use the handler’s parameters.
ParametrizedAction	In most cases, this Action is represented by a text editor control. It is used to execute operations that depend on a parameter value typed into the control. When an end-user types and submits the parameter, the ParametrizedAction.Execute event is raised. You can access the entered value via the handler’s ParametrizedActionExecuteEventArgs.ParameterCurrentValue parameter.
SingleChoiceAction	Allows end-users to select an item from a predefined list. Listed items can represent modes or operations specified by the Action’s SingleChoiceAction.ItemType property. If modes are listed, the Action control will indicate the current selection. Operation lists do not provide such functionality. The predefined items are specified by the ChoiceActionBase.Items collection. Each item can have child items. The ChoiceActionBase.IsHierarchical method is intended to detect if there are items containing child items. The items can be displayed as a tree if this method returns true. If this method returns false, the items will be displayed as a one-level list. When an end-user selects an item, the Action’s SingleChoiceAction.Execute event is raised. You can access the selected item via the handler’s SingleChoiceActionExecuteEventArgs.SelectedChoiceActionItem parameter.
ActionUrl	Used to display links in ASP.NET Web applications. When clicking the Action’s control, the page specified by the Action’s ActionUrl.UrlFormatString property is loaded. The ActionUrl.OpenInNewWindow property specifies whether to load the page in a new window. In Windows Forms applications, the Action’s control is displayed, but the target page cannot be loaded. In Mobile applications, this Action is not supported, but you can display and process a business class property value as a hyperlink as it is shown in the How to show a hyper link (URL, email, etc.) for a business class property example.

How to Add an Action

There are two ways to add an Action to an application. You can add an Action to a Controller or apply a specific attribute to a persistent object’s method.

• Add an Action to a Controller

  Since Controllers are containers for Actions, an Action can be added to the required Controller. The easiest way to do this is to use the Controller’s Designer. Expand the XAF Actions section in the Toolbox. There, you can find all the Action types listed above. Drag the required Action to the Designer and specify its properties via the Properties window. In the Controller’s code, the Action will be initialized and added to the Controller.Actions collection. Handle the Action’s events as required. In addition, set the Action’s ActionBase.Id to a friendly value, because a GUID value is set by default. Make sure the new value is unique.

  Note

  Do not forget to rebuild your solution after making changes in the Designer. Otherwise, you will not see them in the Model Editor.

  Alternatively, you can add an Action to a Controller in code. In a Controller’s constructor, instantiate the Action in the following manner.

  C#

  public class ViewController1 : ViewController {
      public ViewController1() {
          SimpleAction action1 = new SimpleAction(this, "Action1", DevExpress.Persistent.Base.PredefinedCategory.View);
      }
  }
  

  VB.NET

  Public Class ViewController1
      Inherits ViewController
      Public Sub New()
          Dim action1 As New SimpleAction(Me, "Action1", DevExpress.Persistent.Base.PredefinedCategory.View)
      End Sub
  End Class
  <para>Then, you can access the Action's properties and handle Action's events.</para>
  

• Apply the Action attribute to a business class method

  A SimpleAction or a PopupWindowShowAction can be implemented in a persistent class declaration. To do this, apply the ActionAttribute attribute to a method that will be called when executing the Action. If a method is parameterless, then a SimpleAction is created. If a method takes a non-persistent object as a parameter, then a PopupWindowShowAction is generated and a Detail View of this non-persistent object is shown in a pop-up. Actions implemented in this way are added to the special ObjectMethodActionsViewController View Controller and their TargetObjectType properties are set to the container object type. The Category property is set to the RecordEdit value by default. This means that these Actions are displayed in the RecordEdit Action Container. You can specify the Action’s remaining properties via the attribute parameters: Caption, Category, Tooltip, ImageName, and so on. Otherwise, default values will be set. You can change some of the Action’s settings via the Application Model‘s ActionDesign | Action node.

  For more details, please refer to the How to: Create an Action Using the Action Attribute topic.

How to Customize an Action via the Application Model

The information on Actions is loaded to the ActionDesign node of the Application Model. In particular, the following child nodes are available:

• ActionDesign | ActionToContainerMapping node

  Use this node to change the Action Container that will display the required Action. By default, the Action Container is specified by the Action’s Category property.

• ActionDesign | Actions node

  Use this node to change the required Action’s settings.

• ActionDesign | DisableReasons node

  Use this node to define action disabled reasons that you use in code. The specified reason descriptions are used to construct hints for disabled Actions.

You can also add a Views | ListView | HiddenActions node to the Application Model to set Actions that should be hidden when displaying the current List View.

Note

In the XAF documentation, built-in Actions are referred to by their identifiers (see ActionBase.Id). To find out what caption is assigned to a particular Action, use the Model Editor.