Control Add-ins in Business Central

What Is a Control Add-in?

Implementation in Business Central is not about enabling all modules at once. It is about deciding how the company wants to run its business inside the ERP system and then configuring Business Central to enforce that behavior.

A control add-in is a special AL object that acts as a bridge between Business Central pages and external JavaScript/HTML/CSS components. It allows a web-based UI component to be hosted inside a Business Central page and communicate with AL code.

A control add-in:

•Renders custom UI inside a page
•Uses JavaScript for behavior and interaction
•Communicates with AL through events and procedures
•Runs inside the Business Central web client

A control add-in does not:

•Store business data
•Replace tables or codeunits
•Execute posting or validation logic

It is strictly a presentation and interaction layer.

Why Control Add-ins Exist

Standard AL controls cover most business scenarios, but some requirements cannot be met with built-in UI elements alone, such as:

•Advanced visualizations
•Interactive maps or diagrams
•Barcode or camera integrations
•Custom dashboards or widgets

Control add-ins exist to:

•Extend UI capabilities safely
•Reuse web technologies
•Keep core ERP logic unchanged
•Preserve upgrade safety

They allow innovation without compromising system stability.

Basic Structure of a Control Add-in

A control add-in is defined using the controladdin object. It declares:

Required scripts
Startup script
AL-JavaScript communication points

controladdin 50400 "SimpleMessageAddIn"
{
    Scripts = 'simplemessage.js';
    StartupScript = 'simplemessage.js';
    RequestedHeight = 200;
    RequestedWidth = 300;

    event ControlReady();
    procedure ShowMessage(MessageText: Text);
}
    

This object defines the contract between AL and JavaScript.

JavaScript Side of a Control Add-in (Conceptual)

The JavaScript file implements the UI and logic referenced by the control add-in.

Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('ControlReady', []);

function ShowMessage(message) {
    alert(message);
}
    

This script:

•Signals when the control is ready
•Exposes functions callable from AL
•Handles UI behavior

Using a Control Add-in on a Page

Control add-ins are hosted inside pages using a usercontrol.

page 50400 "Add-in Demo Page"
{
    PageType = Card;
    ApplicationArea = All;
    UsageCategory = Administration;

    layout
    {
        area(Content)
        {
            usercontrol(MyAddIn; "SimpleMessageAddIn")
            {
                trigger ControlReady()
                begin
                    CurrPage.MyAddIn.ShowMessage('Control Add-in loaded successfully');
                end;
            }
        }
    }
}
    

This page:

•Hosts the control add-in
•Responds to add-in events
•Calls JavaScript logic from AL

Communication Between AL and JavaScript

Control add-ins communicate in two directions:

•JavaScript → AL using events
•AL → JavaScript using procedures

This communication is asynchronous and event-driven, ensuring UI responsiveness.

page 50130 PageWithAddIn
{
    layout
    {
        area(Content)
        {
            // The control add-in is placed on the page using the usercontrol keyword
            usercontrol(ControlName; SampleAddIn)
            {
                ApplicationArea = All;

                // JavaScript → AL communication
                // This trigger is raised from JavaScript using InvokeExtensibilityMethod
                trigger Callback(i: Integer; s: Text; d: Decimal; c: Char)
                begin
                    Message('Got from js: %1, %2, %3, %4', i, s, d, c);
                end;
            }
        }
    }

    actions
    {
        area(Creation)
        {
            action(CallJavaScript)
            {
                ApplicationArea = All;

                trigger OnAction()
                begin
                    // AL → JavaScript communication
                    // Calling a JavaScript-exposed method on the control add-in
                    CurrPage.ControlName.CallJavaScript(5, 'text', 6.3, 'c');
                end;
            }
        }
    }
}
    

What This Example Demonstrates

This page shows a complete control add-in interaction cycle:

•The control add-in is embedded using usercontrol
•JavaScript raises the Callback event
•AL handles the event using a trigger
•AL calls JavaScript using a public add-in procedure
•Parameters flow safely in both directions

Key Takeaways From This Example

•usercontrol is the only way to host a control add-in on a page
•JavaScript events map directly to AL triggers
•AL can invoke JavaScript methods using CurrPage.
•Control add-ins act as UI interaction layers, not logic holders
•All business logic must still live in AL (codeunits, tables)

Where Control Add-ins Fit in the Architecture

Control add-ins sit at the UI edge of the system:

•Pages host control add-ins
•Codeunits provide business logic
•Tables store data

Control add-ins should never contain business rules. They should only:

•Display data
•Capture user interaction
•Delegate logic to AL

Common Use Cases for Control Add-ins

Control add-ins are typically used for:

•Dashboards and charts
•Visual data exploration
•Hardware or browser integrations
•Custom user interaction components

They are especially useful when standard AL UI controls are insufficient.

Common Beginner Mistakes With Control Add-ins

Developers often:

•Put business logic in JavaScript
•Treat add-ins as data owners
•Ignore performance and loading behavior
•Forget browser security constraints

Control add-ins should remain thin UI layers.

Security and Deployment Considerations

When using control add-ins:

•Scripts must be packaged with the extension
•External resources should be used carefully
•Browser sandboxing applies
•Control add-ins run only in the web client

Security and performance must always be considered.

Summary

Control add-ins in AL provide a powerful way to extend the Business Central UI using web technologies. They enable rich interaction and visualization while keeping core business logic and data safely inside AL objects.

A well-designed control add-in:

•Focuses on presentation
•Communicates cleanly with AL
•Avoids business logic
•Preserves upgrade safety

Understanding control add-ins completes the advanced UI extensibility layer of AL development.