Action Containers

• Oct 18, 2024
• 6 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:

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 in a drop-down menu. You can display the root item as a split button (specify one of included Actions as default). You can also enable a traditional sub-menu UI (specify a caption and/or image for the root item).

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 root menu Action’s identifier.

autoChangeDefaultAction

Specifies whether the last executed Action becomes the default one.

imageName

Specifies the image used as the root menu item.

caption

Specifies the caption used as the root menu item.

Image and caption are not mutually exclusive. You can use both as the root item at the same time.

using DevExpress.Blazor;
using DevExpress.ExpressApp.Blazor.Templates;
namespace YourSolutionName.Blazor.Server
{
    public class CustomApplicationWindowTemplate : ApplicationWindowTemplate
    {
        public CustomApplicationWindowTemplate()
        {
            // Action as the root item
            Toolbar.AddActionContainer("SaveOptions", alignment: ToolbarItemAlignment.Right, isDropDown: true, defaultActionId: "SaveAndNew", autoChangeDefaultAction: true);
            // Image as the root item
            // Toolbar.AddActionContainer("SaveOptions", alignment: ToolbarItemAlignment.Right, isDropDown: true, imageName: "Save");
            // Caption as the root item
            // Toolbar.AddActionContainer("SaveOptions", alignment: ToolbarItemAlignment.Right, isDropDown: true, caption: "Save Options");
        }
    }
}

If you omit defaultActionId, imageName, and caption parameters, XAF displays the first Action as the root item.

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.

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:

ASCX

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

ASCX

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

• How To: Create a Custom Blazor Application Template
• How to: Create a Custom WinForms Standard Template
• How to: Create a Custom WinForms Ribbon Template
• How to: Customize an ASP.NET Web Forms Template

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.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Web\Templates\ActionContainers\
• %PROGRAMFILES%\DevExpress 24.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Win\Templates\ActionContainers\
• %PROGRAMFILES%\DevExpress 24.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Blazor\Templates\