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:
Tip
For more information about Actions in grid columns in ASP.
#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.
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.
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 Single
#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.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\