Action Containers

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

Panel

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

ASPxPanel

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

WebControl

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

Panel

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

Panel

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.

    WebActionContainer

    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.

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.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Web\Templates\ActionContainers\
  • %PROGRAMFILES(x86)%\DevExpress 18.1\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Win\Templates\ActionContainers\

See Also