Define actions on a page and its properties
Actions are displayed at the top of each page in the ribbon. These actions are RoleCenter actions because they are defined on a RoleCenter page. This location is called the navigation bar.
Under the navigation bar is the command bar. These actions are defined on the Card page or List page.
Define actions in AL
You can define actions in AL by creating an actions section under the layout section of a page.
Within the actions section, you need to create actions within an area, just like fields in the layout section. The four available areas are:
Navigation - Corresponds with the Navigate menu.
Creation - Corresponds with the New Document menu in the Actions menu.
Reporting - Corresponds with the Report menu.
Processing - Corresponds with the Process menu.
These four areas correspond with menus in the command bar
that appear after the separator. The following image shows
the menus selected in red. If you don't see the menus, select
the More options button.
The available menus are fixed in Business Central. If you want to create submenus, you must define groups within an area and then define actions within that group.
To show actions in the first part of the command bar, before the separator, you must promote your actions by using the Promoted property.
Action properties
Just like tables, fields, pages, and controls, the actions on a page also have some properties. All actions have an ID, a Name, a Caption, and an Image property. The Image property is used to display an image in the action.
Promoted, PromotedIsBig, PromotedOnly, and PromotedCategory properties
The Promoted property is used to push the action in the first part of the command bar, before the separator. The promoted actions should always be promoted in a certain category. Therefore, you must set the PromotedCategory property. A PromotedCategory will result in a menu being displayed that contains the action.
The PromotedCategory has fixed values. You can choose between New, Process, Report, and Category4 through Category20. Certainly, you don't want the name of the menu showing as Category5. Therefore, you need to use a page property called PromotedActionCategories.
In the next example, the action with the name Comments is promoted in Category7, meaning that it will be displayed in a Customer menu.
If you only want to have your action promoted and don't want it showing up in one of the normal menus (Actions, Navigate, Report, New Documents), then you can use PromotedOnly, which is a Boolean property.
The PromotedIsBig property is used to change the order of the displayed actions. With PromotedIsBig, the action will appear before other actions.
Promoted Actions
Pages and page extensions can now contain a new action group for promoted actions. These groups can contain references to existing actions. It's possible to add to already existing groups or add new groups in page extensions. Users can personalize their experience by promoting actions themselves. The platform and client will stay backward compatible by keeping the existing promoted actions property, but a page or page extension must be consistent in using either the old or the new model. There will be a code action to convert from the old model to the new.
You can promote actions that are used more often than others and thereby ensure quick access to them. This type of actions is called promoted actions. Promoted actions are set up on the Actions, Navigate, or Report menus in the action bar, but are also configured to display on the Home tab. You can, however, choose to hide them on the Actions, Navigate, or Report menus and only show them on the Home tab.
Promoted actions can be used on Card, Document, List, ListPlus, and Worksheet pages to provide quick access to common tasks that appear under the Home tab.
As of 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 code for a page and it contains a reference to the action. The new syntax provides more visibility in code because the promoted actions are grouped in a separate section. And to the end user, the personalization experience is improved, adding options for promoting actions.
In Business Central the new action bar is enabled when the feature flag Modern Action Bar on the Feature Management page is set to Enabled. The flag can be switched off to simulate legacy behavior, but the promoted action code in the base application uses the actionref syntax.
To define promoted actions, you specify an area(Promoted) in the actions section of a page or a page extension. Inside the area(Promoted) section, you can specify one or more actionref sections. An actionref is an object type that references an action on the page, and by adding it in the promoted area section, it's promoted in the UI. An actionref can only be defined in the area(Promoted) section. You can either create groups in the area(Promoted) for the actionref references, or you can add actionref sections directly. An actionref inherits the properties of the referenced action. For page extensions, you can add to existing groups and you can add new groups.
As part of the new programming model for promoted actions, you can combine multiple actions into a split button to help organize the actions that you're promoting, thereby reducing clutter and improving coherence and closeness of related actions. A split button can be defined for a page action group, which renders as a combination of a button and a menu. Use the ShowAs property to specify that a certain page action group should render as a split button. For more information, reference the ShowAs property in the documentation.
The following example illustrates a page with the promoted area syntax. In the example the area(Processing) section defines the MyBaseAction action for the page, which triggers a Hello world message. The MyBaseAction will be available from under the Processing group in the action bar and it will be promoted because it's added to the area(Promoted) section, which defines the actions to promote. The example illustrates that you can group your actionref sections, or specify them ungrouped. The actionref(MyPromotedActionRef; MyBaseAction) promotes the defined MyBaseAction so that it, in addition to being placed in the Processing group, also is promoted for easy access on the page. Also, the example illustrates using a split button for Group2 with two actionrefs.
al-languageCopy
page 50105 ActionRefPage
{
actions
{
area(Promoted)
{
actionref(MyPromotedActionRef; MyBaseAction)
{
}
group(Group1)
{
actionref(MySecondPromotedActionRef; MyBaseAction)
{
}
}
group(Group2)
{
ShowAs = SplitButton;
actionref(MySplitButtonPromotedActionRef; MyBaseAction)
{
}
actionref(MyOtherSplitButtonPromotedActionRef; MyBaseAction)
{
}
}
}
area(Processing)
{
action(MyBaseAction)
{
Visible = true;
trigger OnAction()
begin
Message('Hello world!');
end;
}
}
}
}
Switching over to use the new promoted actions syntax can be done gradually as legacy and new syntax will co-exist for a while. We do, however, encourage you to switch over as soon as you can. As you refactor the code, there are a couple of things to be aware of in that process:
It's not allowed to use both legacy and new syntax for promoted actions on the same page or page extension. This means that if you add actionref syntax to your code, the Promoted properties (Promoted, PromotedOnly, PromotedActionCategories, and PromotedCategory) won't be allowed.
Across a project you can mix legacy and new syntax and you can implement the new actionref syntax on a page without breaking any existing page extensions. You can also write a page extension with the new actionref syntax based on a page that uses the legacy syntax.
A code action for converting pages using legacy syntax is available with Business Central 2022 release wave 2. The code action can be applied to a narrow or broader scope of code.
RunObject, RunPageView, and RunPageLink properties
When you want to open a page or run code when a user selects an action, you can write AL code in the OnAction trigger. You can also use the RunObject property.
With the RunObject property, you can run the following objects:
Page
Report
XMLPort
Codeunit
The RunPageLink, RunPageMode, and RunPageView properties
are all related to pages, so you'll use them if you run a page.
The RunPageLink is used to create a connection between two source tables of two pages. For example, if you want to view all sales orders for a specific customer from an action on the Customer Card, you need to link the customer with the sales orders. As a result, the Sales Orders page will be filtered on the selected customer. You can also set extra filtering.
The RunPageMode indicates in which mode that the page you are running should open. It can be opened in a View, Edit, or Create mode. However, if you configured your page and its InsertAllowed property is set to No, running your page in Create mode won't work.
The RunPageView property allows you to put a table filter on your page and to have a filtered result.
The ShowAs property specifies how an action group should be rendered:
Standard - Specifies that an action group should be rendered as a standard group.
SplitButton - Specifies that an action group should be rendered as a split button.
By specifying that the group should be rendered as SplitButton, the group is rendered as a combination of a button and a menu. This type of control gives you a fast one-click access to the first action, which is set to Visible and to Enabled in a menu using the left button part and access to other related actions using the right dropdown part.
Be aware of the following design guidance:
Split buttons aren't supported on sub form action bars or in context menus. When the feature key ModernActionBar is turned off, then it isn't supported if the ShowAs property is set to SplitButton on a promoted action category group.
Mobile clients don't support split buttons. If the ShowAs property is set to SplitButton, it'll be ignored.
Any tooltip, caption, or image property set on a group, isn't rendered, if the group is defined as a split button. It's still a best practice to set these properties, because they're used, if the group is rendered as a regular group, for example, on mobile clients.
A split button can be nested inside another split button.
For personalization from the UI, it's possible to drop an action into a split button and the action will then become the primary action, if the action is enabled and visible. During personalization it's also possible to reorder the child actions, which will dynamically update the primary action as necessary.
In the following example, the group MyGroup will be rendered as a split button, which gives you a one-click access to the action MyAction:
al-languageCopy
group(MyGroup)
{
ShowAs = SplitButton;
action(MyAction)
{
}
...
The following example illustrates split button behavior if you use a promoted action category with the ShowAs property:
al-languageCopy
...
area(Promoted)
{
// Not rendered as a split button when the feature flag is OFF
group(Category_New) // This is a promoted action category
{
Caption = 'New';
ShowAs = SplitButton;
actionref(TestAction1_Promoted; TestAction1)
{
}
actionref(TestAction2_Promoted; TestAction2)
{
}
}
// Rendered as a split button (whether feature flag is ON or OFF)
group(Test)
{
ShowAs = SplitButton;
actionref(TestAction1_Promoted2; TestAction1)
{
}
actionref(TestAction2_Promoted2; TestAction2)
{
}
}
}
Define custom actions in AL code
Pages in Business Central can have actions that are used to run objects such as other pages, reports, or codeunits. All of these objects are native to Business Central. However, there's an increasing need to be able to invoke external targets. To support this, a new custom action has been added. For now, it is possible to invoke Power Automate flows only, but potentially custom actions could be used to invoke things such as Power BI reports, Power Apps, or websites in the context of a given Business Central page.
al-languageCopy
customaction(MyFlowAction)
{
CustomActionType = Flow;
FlowId = '<the-GUID-identifying-the-Power-Automate-Flow>';
FlowEnvironmentId = '<the-GUID-identifying-the-Power-Automate-environment>';
}