Pages Overview

In Dynamics 365 Business Central, pages are the main way to display and organize data. Pages are the primary object that a user will interact with and have a different behavior based on the type of page that you choose. Pages are designed independently of the device they are to be rendered on, and in this way the same page can be reused across phone, tablet, and web clients.

A page is defined in code as an object composed of controls, properties, actions, and triggers. You can also use Designer in Dynamics 365 Business Central to create a page. For more information, see Using Designer.

Whether you are creating a new page, or extending an existing page, you will add a new .al file to your project and describe the page object in code. The difference is basically that for a new page, you need to define the entire page, whereas when modifying an existing page, you only add the extra functionality or modify the existing.

The structure of a page is hierarchical and breaks down in to three sections. The first block contains metadata for the overall page. The metadata describes the page type and the source table it is showing data from. The next section; the layout, describes the visual parts on the page. The final section details the actions that are published on the page.

Furthermore, the page has properties. Properties work in the same way for pages as they do for other Dynamics 365 Business Central objects. For more information, see Page Properties.

Page Metadata

For a new page object, you must at least specify the type of page; PageType and the data source; SourceTable of the page. And you can also set other metadata at the beginning of the declaration of the page object.

page 50102 PageName
{
    PageType = List;
    SourceTable = TableName;
    Editable = true;
    ContextSensitiveHelpPage = 'feature-overview';
    ...
}

Types of Pages

Which page type you choose depends on the application task that you want to support, the content that you want to display, and how you want to display it. The Role Center page is the main or home page and it helps the user focus on the most important daily tasks and activities. Other types of pages, such as list pages or card pages are typically linked from the home page for easy access. The following page types are available:

Page type Description
RoleCenter The Role Center page is the main page.
Card A Card page is used to view and edit one record or entity from a table.
CardPart A Card Part page is used in a FactBox on another page to view or edit additional fields associated with a selected entity in the page.
List A List page displays content from a table in a list format.
ListPart Similar to a List page, a List Part page displays content from a table in a list format. The difference is that you use the List part page as another page in a FactBox or as a part of the Role Center page.
ListPlus Similar to a List page, a List Plus page displays content from a table in a list format. The difference is that the List Plus page type can contain two lists in one page, and can be used as a two-dimensional matrix.
Document A Document page usually consists of two separate pages combined into one, with one page nested in the other. A Document page is suitable for use when you want to display data from two tables that are linked together.
WorkSheet You use a Worksheet page type for creating worksheet or journal task pages.
ConfirmationDialog You use the ConfirmationDialog page to display messages or prompt users with a confirmation before they continue with the task that they are working on.
StandardDialog The StandardDialog is a simple page type that you use when users only need to input data and do not need to perform other actions from the page.
NavigatePage You use a Navigate page type to create a wizard that leads the user through a sequence of steps for completing a task.
HeadlinePart You use a HeadlinePart page type to display a set of changing headlines on a Role Center. For more information, see Creating a Role Center Headline
API Pages of this type are used to generate web service endpoints and cannot be shown in the user interface. This page type should not be extended by creating a page extension object. Instead, create a new API by adding a page object.

Note

For backwards compatibility we continue to support adding non-part pages as parts. We do, however, recommend that you redesign your page to only use Card part or List part, as we may remove support in a future update.

Page Layout

The page layout of the page object determines what the page will look like and is specified in the layout section. The layout contains one or more area sections that define a certain placement on the page.

You can choose between the following area categories:

Area type Placement on the page
Content The content area displays the content of a RoleCenter or a List page.
FactBoxes The factbox area is placed to the right-most side of a page.
Displays content related to an item on the main content page.
RoleCenter The RoleCenter is the main page of the application and is used for quick access to frequently used information and tasks.

Page Actions

All pages contain menu items and navigation controls called actions. In Dynamics 365 Business Central, actions are displayed at the top of each page in the ribbon or in the navigation pane. The actions section of the page describes what the user is able to do on a page and must be designed with the user's need for process support in mind.

Actions can be displayed in the ribbon of all pages and grouped together under the following actions tabs:

  • Home
  • Actions
  • Navigate
  • Report

Creating actions can include adding activity buttons/cues to a page, configuring navigation items on a user role center, or adding Reports to a page. To learn how you can enable users to quickly locate the actions they want to use, see Actions.

Using Keywords to place Actions and Controls

You can use the following keywords in the layout section to place and move fields and groups on the page. Similarly, in the actions section, you use these keywords to place actions in the ribbon.

Keywords Syntax Applies to
addfirst addfirst(Anchor) Anchor: areas and groups
addlast addlast(Anchor) Anchor: areas and groups
addafter addafter(Anchor) Anchor: controls, actions and groups
addbefore addbefore(Anchor) Anchor: controls, actions and groups
movefirst movefirst(Anchor; Target1, Target2) Anchor: area, group
Target: list of actions or list of controls
movelast movelast(Anchor; Target1, Target2) Anchor: area, group
Target: list of actions or list of controls
moveafter moveafter(Anchor; Target1, Target2) Anchor: controls, actions and groups
Target: list of actions or list of controls
movebefore movebefore(Anchor; Target1, Target2) Anchor: controls, actions and groups
Target: list of actions or list of controls
modify modify(Target) Target: controls, actions and groups

Example

To modify the existing fields and groups on a page, you use the modify keyword. See the code snippet below for addlast, modify and action syntax. In the following example, action creates a new group in the ribbon and places it last in the Creation group.

pageextension 70000020 CustomerCardExtension extends "Customer Card"
{
    layout
    {
        // Adding a new control field 'ShoeSize' in the group 'General'
        addlast(General)
        {
            field("Shoe Size"; ShoeSize)
            {
                Caption = 'Shoe size';

                trigger OnValidate();
                begin
                    if ShoeSize < 10 then
                        Error('Feet too small');
                end;
            }
        }

        // Modifying the caption of the field 'Address 2'
        modify("Address 2")
        {
            Caption = 'New Address 2';
        }

        // Moving the two fields 'CreditLimit' and 'CalcCreditLimitLCYExpendedPct'
        // to be the first ones in the 'Balance' group.
        movefirst(Balance; CreditLimit, CalcCreditLimitLCYExpendedPct)
    }
    actions
    {
        // Adding a new action group 'MyNewActionGroup' in the 'Creation' area
        addlast(Creation)
        {
            group(MyNewActionGroup)
            {
                action(MyNewAction)
                {
                    Caption = 'My New Action';

                    trigger OnAction();
                    begin
                        Message('My message');
                    end;
                }
            }
        }
    }
}

tableextension 70000020 CustomerTableExtension extends Customer
{
    fields
    {
        // Adding a new table field in the 'Customer' table
        field(50100; ShoeSize; Integer) { }
    }
}

Adding Help to the page objects

The Business Central user assistance model expects your solution to include tooltips and links to context-sensitive Help. For more information, see User Assistance Model.

Context-sensitive Help

To apply context-sensitive Help to your app, you specify a URL to your Help library in the app.json file, and you then set the relevant target Help files as property values for each of your page objects and page extension objects. Between them, these two settings then give users access to context-sensitive Help for the features in your app at runtime. For more information, see Configure Context-Sensitive Help.

Tooltips

In combination with descriptive captions and instructional text, tooltips are our current implementation of embedded user assistance, which is an important principle in today’s world of software design. The tooltips are there to help users unblock themselves by providing an answer to the most likely questions the users might have, such as “What data can I input here?” or “What is the data used for?”.

The base application has set the Tooltip property for all controls on (almost) all page objects. Most system actions also include tooltips so that users get a consistent experience. Your extensions are expected to also include tooltips for the same reason. For more information, see ToolTip Property.

Instructional text

The base application has applied instructional text to setup guides and certain other types of page objects. Your extensions are expected to also include instructional text to setup guides for the same reason. For more information, see InstructionalText Property.

Example

The following example shows how you can apply user assistance and link to Help in a page object:

page 50101 "Reward Card"
{
    PageType = Card;
    SourceTable = Reward;
    ContextSensitiveHelpPage = 'sales-rewards';

    layout
    {
        area(content)
        {
            group(Reward)
            {
                InstructionalText = 'Fill in the fields so that you can reward customers with discounts.';
                field("Reward Id"; "Reward ID")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the unique ID of the reward.';
                }

                field(Description; Description)
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies what this type of reward is used for.';
                }

                field("Discount Percentage"; "Discount Percentage")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the impact of the reward on the customer''s price.';
                }
            }
        }
    }
}

In this example, the app.json file has specified a link to where the sales-rewards target file is published, such as "contextSensitiveHelpUrl": "https://mysite.com/documentation".

Best practices for designing pages

We recommend that you simplify the user experience by reducing what users see by default. You can promote the information that the users most frequently need to see and hide the less important information. For example:

  • Place common tasks in the ribbon

  • Organize information pages under FastTabs and, by default, hide the FastTabs that are infrequently visited.

  • Use one to three FactBoxes on a page to provide supplementary information and a place for adding notes

  • Add a target Help file for context-sensitive Help for the feature that the page object supports

See Also

Page Properties Overview
Actions Overview
Using Designer
Adding a Factbox to a Page
Designing Role Centers
Configure Context-Sensitive Help