5.3: Page Extensions & Page Customizations

5.3 Page Extensions & Page Customizations

In modern Business Central development, modifying existing user interfaces is achieved without altering base Microsoft code. Developers use Page Extensions (pageextension) to additively introduce new fields, controls, actions, views, and AL triggers to standard pages across the entire tenant. For role-specific UI tailoring without code, developers use Page Customizations (pagecustomization) bound to user Profiles (profile). Understanding the strict architectural differences between these objects, defining custom page views, and mastering the page trigger execution lifecycle is heavily tested on the MB-820 exam.

1. Page Extensions: Additive UI and Logic Enhancement

A pageextension object targets an existing page and applies non-intrusive modifications.

Layout and Action Placement Directives

When adding controls to the layout or actions to the ribbon, AL provides four placement keywords:

• addfirst(AnchorControl; ...): Inserts the new element as the first child of the specified container.
• addlast(AnchorControl; ...): Inserts the new element as the last child of the specified container.
• addbefore(AnchorControl; ...): Inserts the new element immediately preceding the target control or action.
• addafter(AnchorControl; ...): Inserts the new element immediately following the target control or action.

Modifying Existing Controls: modify()

Existing base application controls and actions can be modified using the modify() block:

• Permissible modifications: Visible, Enabled, Editable, Importance, ToolTip, Style, StyleExpr.
• Restrictions: You cannot change the underlying field data type, field length, or primary key bindings.

Moving Existing Controls

Elements can be rearranged without redefining them using move keywords: movefirst(), movelast(), movebefore(), and moveafter().

Adding Predefined Views via views Block

In page extensions targeting List pages, developers can introduce permanent, predefined filter and sort views using the views container:

pageextension 50121 "Customer List Views Ext" extends "Customer List"
{
    views
    {
        addfirst
        {
            view(HighBalanceCustomers)
            {
                Caption = 'High Balance (> 10,000)';
                Filters = where("Balance (LCY)" = filter(> 10000));
                OrderBy = descending("Balance (LCY)");
                SharedLayout = true;
            }
        }
    }
}

Full Page Extension Code Example

pageextension 50120 "Customer Card Loyalty Ext" extends "Customer Card"
{
    layout
    {
        // Add loyalty field immediately after General -> Name
        addafter(Name)
        {
            field("Loyalty Tier Code"; Rec."Loyalty Tier Code")
            {
                ApplicationArea = All;
                ToolTip = 'Specifies the customer loyalty membership tier.';
                Importance = Promoted;
            }
        }
        // Modify standard credit limit field to always be highlighted
        modify("Credit Limit (LCY)")
        {
            Importance = Promoted;
            Style = StrongAccent;
        }
    }

    actions
    {
        addlast(processing)
        {
            action(RecalculateLoyaltyPoints)
            {
                ApplicationArea = All;
                Caption = 'Recalculate Points';
                Image = Refresh;
                ToolTip = 'Recomputes loyalty points based on posted sales history.';

                trigger OnAction()
                var
                    LoyaltyMgmt: Codeunit "Loyalty Management";
                begin
                    LoyaltyMgmt.UpdateCustomerPoints(Rec."No.");
                end;
            }
        }
    }
}

2. Page Customizations vs. Page Extensions

While a pageextension applies modifications to all users globally across the tenant, a Page Customization (pagecustomization) applies layout alterations exclusively to a specific user Profile (Role Center persona).

Architectural Rules & Constraints of pagecustomization

1. Declarative Only (No Code): A pagecustomization cannot declare AL variables, custom global procedures, or page triggers (OnOpenPage, OnAfterGetRecord, etc.). It can only contain layout and action structural modifications (modify, move, add).
2. Only Existing Fields: You can only add fields that already exist on the underlying SourceTable of the target page.
3. Profile Association: A page customization is inactive until referenced by a profile object via the Customizations property.

pagecustomization "Sales Agent Customer Card" customizes "Customer Card"
{
    layout
    {
        // Hide credit limit from junior sales agents
        modify("Credit Limit (LCY)")
        {
            Visible = false;
        }
        // Move phone number to the very top of the General FastTab
        movefirst(General; "Phone No.")
    }
}

profile "Sales Agent"
{
    Caption = 'Sales Representative';
    RoleCenter = "Order Processor Role Center";
    Customizations = "Sales Agent Customer Card";
    Promoted = true;
    Enabled = true;
}

3. The Runtime Execution Lifecycle of Page Triggers

Understanding when triggers execute is vital for performance optimization and bug prevention. Heavy calculations placed in the wrong trigger can cause severe UI lag across the entire tenant.

Validating Page Dismissal: OnQueryClosePage

Developers frequently need to enforce document completeness before a user closes an editing card. The OnQueryClosePage trigger receives a CloseAction parameter indicating how the user closed the window:

trigger OnQueryClosePage(CloseAction: Action): Boolean
begin
    if CloseAction in [Action::OK, Action::LookupOK] then begin
        if Rec.Status = Rec.Status::"In Progress" then begin
            if Rec."Assigned Inspector" = '' then begin
                Message('You must assign an inspector before completing the audit.');
                exit(false); // Cancels page closure and leaves page open
            end;
        end;
    end;
    exit(true); // Allows page closure
end;