The AL developer environment is evolving with frequent updates. To stay up to date on the latest information and announcements, follow us on the Dynamics NAV Team Blog.

Control Add-In Object

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 on pages. Control add-ins can exchange data with the Dynamics 365 server on various data types and can 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 have 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. The layout properties are set to define the size of the control add-in. It is recommended to apply some size to the add-in using these properties. The properties VerticalStretch and HorizontalStretch determine how the control add-in behaves in the client when the window it is displayed in is resized. The default value is false which means that the control add-in is not resized vertically, or horizontally. The value true means that the control add-in is resized vertically, or horizontally. The values set by the RequestedHeight and RequestedWidth properties determine the minimum resize value of the control add-in. Read more about the sizing of control add-ins in the next section.

Sizing of the control add-in

To control that the sizing of the control add-in is always optimal, even on smaller display targets, such as the phone, some settings are available when you write the control add-in. The settings make sure that resizing of the control add-in works on all client types. The properties that allow you to obtain this are the following:

Control add-in syntax example

The following control add-in example syntax defines a chart that can show how customers are represented per country on a map. The control add-in is implemented as a usercontrol on a page called CustomersMapPage.

// The controladdin type declares the new add-in.

controladdin CustomersPerCountryChart
{
    // The Scripts property can reference both external and local scripts.
    Scripts = 'https://code.jquery.com/jquery-2.1.0.min.js',
              'js/main.js';

    // The StartupScript is a special script that the webclient calls once the page is loaded.
    StartupScript = 'js/chart.js';

    // Images and StyleSheets can be referenced in a similar fashion.

    // The layout properties define how control add-in are displayed on the page.
    VerticalShrink = true;

    // The procedure declarations specify what JavaScript methods could be called from AL.
    // In JavaScript code, there should be a global function LoadData(data) {}
    procedure LoadData(Data : JsonArray);

    // The event declarations specify what callbacks could be raised from JavaScript by using the webclient API:
    // Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('CountryClicked', [{country: 'M}])
    event CountryClicked(Country: JsonObject);
}

page 50100 CustomersMapPage
{
    layout
    {
        area(Content)
        {
            // The control add-in can be placed on the page using usercontrol keyword.

            usercontrol(ControlName; CustomersPerCountryChart)
            {
                // The control add-in events can be handled by defining a trigger with a corresponding name.

                trigger CountryClicked(Country : JsonObject)
                var Data : JsonArray;
                begin

                    // The control add-in methods can be invoked via a reference to the usercontrol.

                    CurrPage.ControlName.LoadData(Data);
                end;                  
            }
        }
    }
}

See Also

AL Development Environment
Developing Extensions
Asynchronous Considerations for Control Add-ins
InvokeExtensibility Method
GetImageResource Method
GetEnvironment Method
Pages Overview
Page Extension Object
Page Customization Object