Edit

Share via

Control add-in object

  • Article

The control add-in object allows you to add custom functionality to Dynamics 365 Business Central. A control add-in is a custom control, or visual element, for displaying and modifying data within an iframe or a page. For example, a control add-in can display the content of a webpage, visualize data as a chart or on a map, or host a custom web application. Control add-ins can exchange data with the Dynamics 365 server on various data types and respond to user interaction to raise events that execute additional AL code.

Control add-in properties

In the control add-in definition, you must set the Scripts property to include scripts in the control add-in. The scripts could be local files in the package or references to external files using the HTTP or the HTTPS protocol. With the StartupScript property, you can call a special script that runs when the page you've implemented the control add-in on, is loaded. These settings initialize the control add-in. With the Images and StyleSheet properties, you can specify additional styling to the control add-in. For more information about some of the control add-in properties, see:

Sizing of the control add-in

Control add-ins can either have fixed dimensions or dynamically adapt to the available space on the screen. By controlling the sizing of an add-in, you ensure the add-in and the surrounding content on the page remain optimal on smaller display targets such as the phone or when users resize the browser. The following properties are available for you to specify how the sizing of the control add-in should behave.

Control add-in considerations and limitations

Designing control add-ins that provide the best possible experience can require some additional planning, design, and implementation. The following considerations and limitations will help you design add-ins that look and feel seamlessly integrated with both Dynamics 365 Business Central online and on-premises.

  • Respond to touch events so that mobile users or users on devices supporting touch input can also use the add-in.

  • Design content that is responsive and can flow, resize, or reorganize naturally based on the available space.

  • Consider the accessibility needs of users, for example by implementing keyboard access and support for screen readers.

  • Use the Style guidelines to apply a choice of colors, typefaces, and font sizes that match that of Dynamics 365 Business Central. For more information, see Control add-in style guide.

  • Provide language translation and other localizations that match the current user language in Dynamics 365 Business Central.

  • In extensions for Business Central online, don't reference font files in stylesheets, because the fonts won't display in client. Instead, do one of the following:

    • Reference the font files from some other source such as a public or private CDN.
    • Base64 encode the fonts and include the encoded fonts in the CSS file.

For more information about writing efficient code for control add-ins, see Control add-in best practices.

Control add-in syntax example

The following control add-in syntax shows how to implement small customizations of the layout and functionality of a page.

// The controladdin type declares the new add-in.
controladdin SampleAddIn
{
    // The Scripts property can reference both external and local scripts.
    Scripts = 'https://cdnjs.cloudflare.com/ajax/libs/knockout/3.4.2/knockout-debug.js',
                'main.js';
    // The StartupScript is a special script that the web client calls once the page is loaded.
    StartupScript = 'startup.js';

    // Specifies the StyleSheets that are included in the control add-in.
    StyleSheets = 'skin.css';

    // Specifies the Images that are included in the control add-in.
    Images = 'image.png';

    // The procedure declarations specify what JavaScript methods could be called from AL.
    // In main.js code, there should be a global function CallJavaScript(i,s,d,c) {Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('CallBack', [i, s, d, c]);}
    procedure CallJavaScript(i: integer; s: text; d: decimal; c: char);

    // The event declarations specify what callbacks could be raised from JavaScript by using the webclient API:
    // Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('CallBack', [42, 'some text', 5.8, 'c'])
    event Callback(i: integer; s: text; d: decimal; c: char);
}

The controladdin object is then invoked as a usercontrol on a page called PageWithAddIn.

page 50130 PageWithAddIn
{
    layout
    {
        area(Content)
        {
             // The control add-in can be placed on the page using usercontrol keyword.
            usercontrol(ControlName; SampleAddIn)
            {

                ApplicationArea = All;

                 // The control add-in events can be handled by defining a trigger with a corresponding name.
                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
                    
                    // The control add-in methods can be invoked via a reference to the usercontrol.
                    CurrPage.ControlName.CallJavaScript(5, 'text', 6.3, 'c');
                end;
            }
        }
    }
}

Loading static resources using AJAX requests

You can design a control add-in to load static resources from the add-in package by using AJAX requests. For example, the control add-in could load HTML content and inject it into add-in's HTML structure. In this case, you must use the withCrendentials property set to true in the AJAX request. Otherwise, the request won't contain the necessary context and important cookies required by the Business Central service, and it may fail in production. This concept is illustrated in the following examples.

Wrong:

$.get(url).done(function(response) { } );

Correct:

$.ajax({
     url: url,
     xhrFields: {
          withCredentials: true
    }
)).done(function(data) {
    $("#controlAddIn").text(data);
});

AL development environment
Developing extensions
Asynchronous considerations for control add-ins
Control add-in best practices
InvokeExtensibility method
GetImageResource method
GetEnvironment method
Pages overview
Page extension object
Page customization object