Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Expand]Application Model
  [Expand]UI Construction
  [Collapse]Extend Functionality
   [Expand]Built-in Controllers and Actions
    Controllers
    Actions
    Customize Controllers and Actions
    Add Actions to a Popup Window
    Dialog Controller
    Activate a Controller for the Logon Form
    Determine Why an Action, Controller or Editor is Inactive
    Determine an Action's Controller and Identifier
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Expand]Extra Modules
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Actions

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.

Expanded 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:

Expanded 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.

Expanded 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. Simply 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.

  • 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.

Expanded 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.

Expanded See Also

How would you rate this topic?​​​​​​​