In this video, I explain how and when to use the different page types, and explain the difference between them.
More information can be found here: https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-page-types-and-layouts
In this video, Erik walks through the different page types available in AL for Business Central, explaining when to use each one, how they relate to each other, and how the rendering engine interprets your layout requests. If you’ve ever been unsure whether to use a Card, Document, List, Worksheet, or one of the other page types, this guide will clear things up.
Understanding Pages as Abstract Layout Requests
Before diving into specific page types, Erik makes an important conceptual point: when you define a page in AL, you’re not creating a pixel-perfect layout. You’re making a request to the rendering engine, asking it to present your fields and controls in a usable way.
This means the same source code can render differently depending on:
- The client being used (browser, phone, tablet)
- The screen size and DPI settings
- The Business Central version (the rendering engine may change between versions)
This is why trying to micromanage layout — for example, by using the grid control — generally leads to poor results. The best pages in Business Central are built without forcing layout, allowing the rendering engine to adapt naturally.
The Two Principal Categories
All page types in Business Central fall into two broad categories:
- Entity-based pages — focused on a single record (Card, Document, ListPlus)
- Collection-oriented pages — focused on displaying multiple records (List, Worksheet)
Entity-Based Page Types
Card
The Card page type is the most basic entity page. If you don’t specify a page type at all, Business Central defaults to Card. It displays a single record with navigation arrows to move between records.
page 50100 "Page Type Demo"
{
PageType = Card;
SourceTable = Customer;
layout
{
area(Content)
{
field("No."; Rec."No.")
{
ApplicationArea = all;
}
field(Name; Rec.Name)
{
ApplicationArea = all;
}
}
}
}A Card is appropriate when you have an entity with fields and no prominent sub-list (lines). It shows the record’s primary key or designated title fields in the header, along with navigation to move to the next or previous record.
Document
A Document page type is used when your entity has a prominent list of lines — like a Sales Order with its Sales Lines. The standard Sales Order page in Business Central uses PageType = Document.
The key difference from Card is that Document tells the rendering engine that the list part (subpage) should have a dominant place on the page. The lines get more space and visual priority.
The Sales Order page, for example, includes a part that references the Sales Order Subform — which itself is a ListPart page type. The term “subform” is a legacy name from the classic client days when pages were called “forms.”
ListPlus
ListPlus is often misunderstood. It is not a “better version of List.” A ListPlus page is an entity-based page where the list part is the primary element. It’s critical to understand that you should not put a repeater on a ListPlus page — that breaks things. The list part is what defines the content.
Use ListPlus when you have an entity page where a list part is the most prominent citizen on the page.
Collection-Oriented Page Types
List
The List page type uses a repeater control to display multiple records. The repeater defines each row in the list. You place your fields inside the repeater:
page 50100 "Page Type Demo"
{
PageType = List;
SourceTable = Customer;
layout
{
area(Content)
{
repeater(Rep)
{
field("No."; Rec."No.")
{
ApplicationArea = all;
}
field(Name; Rec.Name)
{
ApplicationArea = all;
}
}
}
}
}A List page is all about the repeater. You can optionally have a single group at the bottom for totals or summary information. If you have both a repeater and a list part, they get equal spacing.
Be careful not to put a repeater on a Card page — it may appear to work in some cases but can produce strange behavior and crazy margins.
Worksheet
The Worksheet page type is used for journal-style pages, like the General Journal. The key difference from List is the layout flexibility:
- List: Repeater is the focus, with optionally a group below it
- Worksheet: You can have groups above and/or below the repeater
If you need fields or filters above the repeater, use Worksheet. If you only need the repeater and perhaps something at the bottom, List works fine. If you need content both before and after the repeater, Worksheet is required.
Page Areas: Content, Header, and FactBoxes
A normal page in Business Central has three areas:
- Header area — controlled by the page type, largely out of your control
- Content area — what you define in
area(Content) - FactBox area — what you define in
area(FactBoxes)
The FactBox area only accepts parts — you cannot place fields directly in it. FactBoxes on entity-based pages are always related to the main record of the page.
Creating a Custom FactBox Part
You can create your own FactBox parts using the CardPart page type:
page 50101 "Page Type Part"
{
PageType = CardPart;
SourceTable = Customer;
ModifyAllowed = true;
layout
{
area(Content)
{
field(Name; Name)
{
ApplicationArea = all;
Editable = true;
}
field(Address; Address)
{
ApplicationArea = all;
Editable = true;
}
}
}
}Then reference it in the FactBox area of your main page:
area(FactBoxes)
{
part(Stat; "Page Type Part")
{
SubPageLink = "No." = field("No.");
ApplicationArea = all;
}
}An important thing to know: FactBox pages are always read-only, even if you set Editable = true and ModifyAllowed = true. The compiler won’t complain, but the fields will remain read-only at runtime. There are workarounds using HTML add-in controls, but by default, FactBoxes cannot be edited.
Also note that when you’re inside a part type page, the only available area is Content — there’s no FactBox area inside a FactBox.
Other Page Types
ConfirmationDialog
This creates a simple yes/no dialog page. It renders your fields in a dialog with confirmation buttons. FactBoxes are ignored even if defined — there’s no place for them in a confirmation dialog.
NavigatePage
The NavigatePage type is used for wizards. It allows you to place action buttons at the bottom of the page (Next, Previous, Back, Cancel, Finish) to guide users through a multi-step process. Erik mentions having a particular fondness for this page type due to its flexibility. Don’t put a repeater in a NavigatePage — Erik tried it once and it produced broken results with two separate pages rendering simultaneously.
StandardDialog, ReportPreview, ReportProcessingOnly, XmlPort
These are specialized page types. The StandardDialog type (also rendered when specifying XmlPort as the page type) creates a simple OK/Cancel dialog — useful when you need to prompt the user for input. The report-related types and API type are special-purpose and behave differently from regular UI pages.
Erik’s Personal Preferences
For day-to-day development, Erik shares what he reaches for most often:
- Card and List — the workhorses, used most frequently
- Document — whenever there are lines involved
- ListPlus — used less often, but has its place
- Worksheet — a fair amount of use for journal-style pages
- NavigatePage — a personal favorite for its flexibility as a wizard-style page with bottom actions
Summary
Choosing the right page type comes down to understanding what you’re presenting to the user:
- Single record, no sub-lines → Card
- Single record with prominent lines → Document
- Entity page where a list part is the main content → ListPlus
- Multiple records in a flat list → List
- Multiple records with fields above/below → Worksheet
- Wizard-style step-by-step flow → NavigatePage
- Simple yes/no prompt → ConfirmationDialog
- Simple OK/Cancel input → StandardDialog
Remember: you’re defining an abstract layout, not a pixel-perfect design. Trust the rendering engine to present your page appropriately across different devices, screen sizes, and Business Central versions. Microsoft provides an excellent reference page on page types and layouts — check the link in the description for the full documentation.
