- 5 minutes to read
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:
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
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.
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:
- Specifies whether the container’s Actions are grouped into a drop-down list.
- Specifies the default Action’s identifier.
- 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.
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:
- Specifies if the container’s Actions are grouped into a drop-down list.
- Specifies an identifier of the default Action for the group (placed as a root menu item).
- Specifies the image name for the group’s root item (when
- Specifies text of the group’s root item (when
- 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>
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 23.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Web\Templates\ActionContainers\
- %PROGRAMFILES%\DevExpress 23.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Win\Templates\ActionContainers\
- %PROGRAMFILES%\DevExpress 23.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Blazor\Templates\