Adding actions to a page

This topic shows how to create new actions, how to add actions to a page, and how to preview them in the Dynamics 365 web client. In Dynamics 365, actions can be displayed in the action bar of all pages and grouped together under the following actions menus:

• Promoted action categories (legacy)
• Actions
• Navigate
• Report

Note

With Business Central 2022 release wave 2, the way that you promote actions on pages or page extensions has changed. Promoting actions is defined in a specific section of the page definition and contains a reference to the action. For more information, see Promoted actions.

Before putting an action on a page you should think about the business processes that the action supports. For example, on page 42, the Sales Orders list page, the Actions button contains actions for all tasks related to processing sales orders. Creating these actions can make it easier for the order processor to perform their daily tasks, such as posting sales orders and creating new customer orders.

For more information about different types of actions and where to use them, see Actions overview.

Tip

After you have added actions to a page, you can use Designer to alter the actions, like moving an action to or from a promoted category, hiding and action or action group, and more. For more information, see Use Designer.

To add actions to a page

The page actions are displayed on the header section. There are multiple tabs to help navigate to the right item.

In order to add actions to the action bar, you must use the keywords with Anchors or Targets. These keywords are used to place and move the actions around in the tab groups. For more information about adding, moving, and modifying actions, see Using keywords to place actions and controls.

Note

Actions can only be linked to a page, or to a group control. Actions cannot be linked to fields, or parts on a page.

Set an icon to an action

Dynamics 365 Business Central includes images that you can use on actions in command bar menus and promoted actions on the ribbon. To add an image to an action, you add the Image property and you must provide the name of the image you that want to use from the Dynamics 365 Business Central Action icon library. By default, the size of images is 16 pixels high by 16 pixels wide. For promoted actions, you can choose to display larger images that are 32 pixels high and 32 pixels wide. For more information, see Image property.

Tip

In Visual Studio Code, you can get a list of available icons using Ctrl+Space (when the cursor is located on the line with the Image property).

For an overview of all available icons, see aka.ms/bcicons.

Example

The following example shows how to use different action areas on a page object of the PageType Card. These actions will display in the following menus in the action bar. The following example uses the legacy syntax for promoted actions. For more information, see Promoted actions.

1. Actions menu: The area(Processing) action area is used to display the action in the Actions menu. This action uses the Promoted and PromotedCategory properties in order to display the action in the promoted actions menu called Process.
2. New Document group: The area(Creation) action area is used to display the action in the New document group in the Actions menu. Also, this action uses the Image property to display a form icon instead of a default icon.
3. Navigate menu: The area(Navigation) action area is used to display the action in the Navigate tab. This action and other actions in this example uses the RunObject property to assign a page to the action.
4. Report menu: The area(Reporting) action area is used to display this action in the Report menu, and also a Group control is added as a submenu to this menu. It sets the Caption property to make the action group visible in the Reports menu.

page 50110 PageName
{
    PageType = Card;

    actions
    {
        // Adds the action called "My Actions" to the Action menu 
        area(Processing)
        {
            action("My Actions")
            {
                Promoted = true;
                PromotedCategory = Process;
                ApplicationArea = All;
                trigger OnAction()
                begin
                    Message('Hello World');
                end;
            }
        }

        area(Creation)
        {
            // Adds the action "My New document" to the New Document group in the Actions menu. 
            action("My New document")
            {
                ApplicationArea = All;
                RunObject = page "Customer Card";
                Image = "1099Form";
            }
        }
        
        area(Navigation)
        {
            // Adds the action called "My Navigate" to the Navigate menu. 
            action("My Navigate")
            {
                ApplicationArea = All;
                RunObject = page "Customer Card";
            }
        }

        area(Reporting)
        {
            // Adds a submenu called "My Label" to the Report menu. 
            group(NewSubGroup)
            {
                Caption = 'My label';
                group(MyGroup)
                {
                    // Adds the action "My Report" to the My Label submenu. 
                    action("My Report")
                    {
                        ApplicationArea = All;
                        RunObject = report "My Report";
                    }
                }
            }
        }
    }
}

Note

Actions can be assigned to a page by setting the RunObject property, or by adding a trigger to a Codeunit. For more information, see RunObject Property and Codeunit Triggers.

The promoted action menus are always displayed first so the promoted actions provide quick access to common tasks, and users don't have to browse through a menu to access them. Add the Promoted property to add actions to the promoted action menu. For more information on how to add promoted actions, promoted categories, and examples, see Promoted Actions.

You can assign different icons for your actions from the Dynamics 365 image library. For more information, see Image property.

Note

Specifically for the PromptDialog page type, there are only two types of actions that can be defined; SystemActions and PromptGuide. For more information, see PromptDialog page type.

Set up a keyboard shortcut on an action

You can use the ShortcutKey property to add a keyboard shortcut to an action. Selecting the key that you set up with this property provides the same result as selecting the action. For example, the following code adds the shortcut Shift+Ctrl+D to an action:

action(DoThisAction)
{
    ApplicationArea = All;
    ShortCutKey = 'Shift+Ctrl+D';

    trigger OnAction()
    var
    begin
        DoThis();
    end;
}

Note

Actions are used in different contexts to drive different experiences in the user interface. Be aware that keyboard shortcuts are not supported across all contexts. For example, the ShortcutKey property is not supported for actions defined in area(sections) or area(embedding).

To help you design shortcuts, keep the following information in mind:

• Some shortcuts have default assignments, either defined by the platform or in the base application. Don't reuse shortcuts that are already assigned for different purposes. For a list of these shortcuts, see Keyboard Shortcuts for the Dynamics 365 Business Central Web Client. Try to be consistent with shortcuts used across pages, reusing shortcuts for similar actions.

• Web browsers also support a set of default shortcuts. The shortcuts that you set with the ShortCutKey property take precedence and will override the similar shortcuts of the web browser.

• You can also set up shortcuts on actions of pages contained in parts of the main page. In this case, the shortcuts only work when the user has focus on the part that contains the page. Consider the following behavior when a user presses a shortcut while a page part's in focus:

  • If a shortcut's not defined on the page in the focused part but is defined on the main page, the main page's action will be triggered.
  • If a shortcut's defined on the page in the focused part and the main page, the focused part's action is triggered. Shortcut's defined in the part take precedence.
  • Be careful when defining shortcut keys that might already be defined in the context of the page being developed. If a duplicated shortcut is found, only the first defined shortcut will be respected, even if the action, which the shortcut is defined on, isn't enabled. If the action isn't visible, the visible action with the same shortcut key is triggered. This consideration is only relevant when defining duplicated shortcuts within the same main page or the same part, like when there is a shortcut defined in the main page and also defined in a part, the above behavior applies with focused parts.

See also

Actions overview
Pages overview
Promoted actions
Available icons