Skip to main content

Action Containers

  • 5 minutes to read

Action Containers are placeholders for Actions (several action may appear within a single container). Templates define the position of Action Containers on screen.

This topic explains how to customize existing Action Containers and implement your own.

XAF supplies a number of built-in Action Containers for automatic UI construction. Built-in Action Containers for ASP.NET Core Blazor, Windows Forms, and ASP.NET Web Forms applications ship with the DevExpress.ExpressApp.Blazor, DevExpress.ExpressApp.Win and DevExpress.ExpressApp.Web assemblies, respectively.

You can find the list of all Action Containers in the ActionDesign | ActionToContainerMapping node of the Application Model.

ASP.NET Core Blazor Action Containers

The following images show Action Container placement in ASP.NET Core Blazor application UI:

ASP.NET Core Blazor Containers

ASP.NET Core Blazor Containers

ASP.NET Core Blazor Containers in Grid Columns

ASP.NET Core Blazor Containers in Popup Windows

Tip

For more information about Actions in grid columns in ASP.NET Core Blazor and ASP.NET Web Forms application, refer to the following topic: How to: Add a Grid Column with an Action (ASP.NET Core Blazor and ASP.NET Web Forms).

Action Container Creation

When XAF creates a Template, it also creates all Action Containers that belong to this Template. The built-in FillActionContainers Controller determines Actions that populate each Action Container. That information comes from the ActionDesign | ActionToContainerMapping node of the Application Model. The FillActionContainers Controller calls the Action Container’s Register method to create a control for each Action. For example, in a Windows Forms application, the ActionContainerBarItem Action Container creates a BarButtonItem object for a SimpleAction and a BarEditItem control for a SingleChoiceAction.

Action Container Customization

You can customize the Actions of a particular Action Container in code, at design time, and at runtime.

In the Application Model

The Application Model contains the ActionDesign | ActionToContainerMapping node. This node contains information on what Actions a particular Action Container must display. You can customize the automatically generated information in the Model Editor at design time or at runtime (see How to: Place an Action in a Different Location). In this node, you can move an Action to another Action Container, delete an Action from a particular Action Container, etc. You can also add a new Action Container and add Actions to it, but such an Action Container only appears in a UI if it belongs to a Template. For more information about this Application Model node, refer to the IModelActions interface description.

In code

To customize an Action Container, handle the Frame.ProcessActionContainer event. You can customize an Action Container using its properties. You can also use the IActionContainer.Actions property to access Actions of a particular Action Container and customize these Actions. For example, you can toggle an Action’s ActionBase.Active property to deactivate this Action. You can also access an Action’s control and customize it.

To customize a toolbar item, handle the CustomizeActionControl event of the corresponding bar item factory. For additional information, refer to the following topic: How to: Customize Action Controls.

You can handle the ActionControlsSiteController.CustomizeContainerActions event to customize the action-to-container mapping in code.

In ASP.NET Core Blazor Application Template

In ASP.NET Core Blazor applications, you can group Actions into a drop-down menu and specify a default Action that serves as a root menu item.

ASP.NET Blazor SaveOptions Container

Create a custom Blazor application template and specify the following Action Container properties:

isDropDown
Specifies whether the container’s Actions are grouped into a drop-down list.
defaultActionId
Specifies the default Action’s identifier.
autoChangeDefaultAction
Specifies whether the last executed Action becomes the default one.
Toolbar.AddActionContainer("SaveOptions", ToolbarItemAlignment.Right, isDropDown: true, defaultActionId: "SaveAndNew", autoChangeDefaultAction: true);

If you specify a SingleChoiceAction as default, it is displayed in the main menu without child items.

The drop-down menu does not support ParametrizedAction and SingleChoiceAction with ItemType set to SingleChoiceActionItemType.ItemIsMode.

In ASP.NET Web Forms Application Template

In ASP.NET Web Forms applications, you can group Actions into a drop-down menu with the default Action placed as a root menu item.

WebActionContainer

You can customize an ASP.NET Web Forms application template to access certain Action Container settings that are not available in the Application Model. In the ASCX file, you can locate a required WebActionContainer item by its ContainerId value and set the following properties:

IsDropDown
Specifies if the container’s Actions are grouped into a drop-down list.
DefaultActionID
Specifies an identifier of the default Action for the group (placed as a root menu item).
DefaultItemImageName
Specifies the image name for the group’s root item (when DefaultActionID is unspecified).
DefaultItemCaption
Specifies text of the group’s root item (when DefaultActionID is unspecified).
AutoChangeDefaultAction
Specifies whether to make the last executed Action default.

The code below sets up a drop-down menu without a default Action. The root item expands the menu and is not associated with an Action:

<ActionContainers>
<xaf:WebActionContainer IsDropDown="true" ContainerId="Security" DefaultItemCaption="My Account" DefaultItemImageName="BO_Person" />
</ActionContainers>

The following code sets up a drop-down menu with a default Action:

<ActionContainers>
<xaf:WebActionContainer ContainerId="Save" DefaultActionID="Save" IsDropDown="true" AutoChangeDefaultAction="true" />
</ActionContainers>

Note

If you specify a SingleChoiceAction as default, it is displayed in the main menu without child items and in the drop-down menu with child items.

Implement Your Own Action Container

If you need to change controls used to display Actions, you can implement your own Action Containers. To do this, inherit from the required control and implement the IActionContainer interface. Alternatively, you can derive your custom container from one of the existing Action Containers. You may also need to specify the controls XAF should use for each Action type.

After you declared your own Action Container, create a new Template or customize an existing template as described in the following topics:

Add your Action Container to the Template and add your Action Container’s instance to the list returned by the Template’s IFrameTemplate.GetContainers method.

If you have XAF sources installed, you can see how built-in Action Containers are implemented in the following locations:

  • %PROGRAMFILES%\DevExpress 24.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Web\Templates\ActionContainers\
  • %PROGRAMFILES%\DevExpress 24.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Win\Templates\ActionContainers\
  • %PROGRAMFILES%\DevExpress 24.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Blazor\Templates\
See Also