Action Containers
- 6 minutes to read
To display an Action in a UI, the eXpressApp Framework uses Action Containers. An Action Container is a control that either displays an Action in a UI, or contains several controls displaying a specified set of Actions. Action Containers are located on Templates. There are several types of Action Containers in the eXpressApp Framework. This topic defines all of them, and provides information on how to customize Action Containers and implement your own.
Action Container Types
An Action Container is a control that implements the IActionContainer interface. This interface provides access to the Action collection, and declares the IActionContainer.Register method to create controls that represent Actions. The eXpressApp Framework supplies a number of built-in Action Containers for automatic UI construction in Windows Forms and ASP.NET Web applications. Built-in Action Containers for Windows Forms and ASP.NET Web applications are located in the DevExpress.ExpressApp.Win and DevExpress.ExpressApp.Web assemblies, respectively. The following tables list all these Action Containers:
Windows Forms Action Containers
| Action Container | Base Class | Description |
|---|---|---|
| ActionContainerBarItem | XafBarLinkContainerItem | A toolbar ItemLinks container. Displays Actions as toolbar items. |
| ActionContainerMenuBarItem | ActionContainerBarItem | Differs from the ActionContainerBarItem Action Container in the control used for the SingleChoiceAction type Actions when their SingleChoiceAction.ItemType property is set to the ItemIsMode value, and the ChoiceActionBase.IsHierarchical method returns false. In this case, the ActionContainerMenuBarItem uses BarSubItem bar items to display these Actions as sub-menu entries. |
| ButtonsContainer | LayoutControl | A layout control. Creates a layout item containing a button for each Action. |
| NavigationActionContainer | Panel | A navigation control. Displays the ShowNavigationItem Action’s items as navigation control links. Uses the NavBarNavigationControl and TreeListNavigationControl controls. |
ASP.NET Web Action Containers
Action Container | Base Class | Description |
|---|---|---|
ActionContainerHolder | A set of links, a set of buttons or a toolbar. The visual representation is defined by the ContainerStyle property which can be set to ActionContainerStyle.Links, ActionContainerStyle.Buttons or ActionContainerStyle.ToolBar. The ActionContainerHolder class has an important property that affects its behavior: Orientation - when this property is set to ActionContainerOrientation.Horizontal, Actions are arranged horizontally from left to right. When this property is set to ActionContainerOrientation.Vertical, Actions are arranged vertically, top to bottom. | |
NavigationActionContainer | A navigation control. Displays the ShowNavigationItem Action from the ViewsNavigation category. The Action’s items are displayed as navigation control links. Used in the built-in DefaultVertical Template. Uses the NavBarNavigationControl and TreeListNavigationControl controls. | |
NavigationHistoryActionContainer | Used to display Actions from the ViewsHistoryNavigation category. Displays the Action’s items as links, delimited by separator characters. Not available in the new web UI. | |
NavigationTabsActionContainer | A tabbed navigation control. Used to display the ShowNavigationItem Action from the ViewsNavigation category. The Action’s first-level navigation items are displayed as tab pages, and their child navigation items - as links. | |
QuickAccessNavigationActionContainer | Used to display the ShowNavigationItem Action from the ViewsNavigation category. Displays the Action’s items as links, delimited by separator characters. |
Action Container Creation
When a Template is created, all its Action Containers are created as well. Then, the built-in FillActionContainers Controller uses the Application Model to determine the Actions to be displayed within Action Containers. In particular, the ActionDesign | ActionToContainerMapping node provides this information. Then, this Controller calls the Action Container’s Register method for each Action to create the corresponding control. Action Containers create specific controls for each Action type. For example, the ActionContainerBarItem Action Container creates the BarButtonItem object for a SimpleAction Action, and the BarEditItem control, for a SingleChoiceAction Action, etc.
Action Container Customization
You can customize the Actions set of a particular Action Container in code, at design time and 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 runtime (see 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 this Action Container will only be displayed in a UI if it is contained in a Template. For information on 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 access Actions of a particular Action Container using the IActionContainer.Actions property, and customize the required Action. For instance, you can deactivate an Action, calling its ActionBase.Active property. In addition, you can access an Action’s control and customize it.
You can customize a toolbar’s bar item by handling the CustomizeActionControl event of the corresponding bar items factory. To learn how to do this, refer to the How to: Customize Action Controls topic.
You can handle the ActionControlsSiteController.CustomizeContainerActions event to customize the action-to-container mapping in code.
In the ASP.NET template markup
In ASP.NET 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 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.
A drop-down menu with no default Action (the root item only expands the menu and is not associated with an Action):
<ActionContainers>
<xaf:WebActionContainer IsDropDown="true" ContainerId="Security" DefaultItemCaption="My Account" DefaultItemImageName="BO_Person" />
</ActionContainers>
A drop-down menu with the default Action:
<ActionContainers>
<xaf:WebActionContainer ContainerId="Save" DefaultActionID="Save" IsDropDown="true" AutoChangeDefaultAction="true" />
</ActionContainers>
Note
If a SingleChoiceAction is default, it will be displayed in the main menu (with no child items) and within 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. Another approach is to derive your custom container from one of the existing Action Containers listed above. Note that you may also need to specify the controls to be used for each Action type.
After declaring your own Action Container, create a new Template or customize an existing one, as described in the following topics.
- How to: Create a Custom WinForms Standard Template
- How to: Create a Custom WinForms Ribbon Template
- How to: Customize an ASP.NET Template
Add your Action Container to the Template, and then 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(x86)%\DevExpress 18.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Web\Templates\ActionContainers\
- %PROGRAMFILES(x86)%\DevExpress 18.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Win\Templates\ActionContainers\