The AL developer preview is still evolving with frequent updates. Follow us on the Dynamics NAV Team Blog for the announcements.

Control Add-In Object

The control add-in object allows you to add custom functionality to Dynamics 365 for Finance and Operations, Business edition and Dynamics NAV. 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 and Dynamics NAV server on various data types and can respond to user interaction to raise events that execute additional AL code.

Note

AL tools functionality is supported in Dynamics 365 for Finance and Operations, Business edition and Dynamics NAV, but in some cases, there are limitations. These limitations are marked clearly in the specific topic.

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.

Property Value type Description
VerticalShrink Boolean Specifies that the control add-in can be made smaller vertically. This setting is optional.
HorizontalShrink Boolean Specifies that the control add-in can be made smaller horizontally. This setting is optional.
MinimumHeight Integer Specifies the minimum height that the control add-in can be shrunk to. This setting only applies if the VerticalShrink setting is specified.
MinimumWidth Integer Specifies the minimum width that the control add-in can be shrunk to. This setting only applies if the HorizontalShrink setting is specified.
MaximumHeight Integer Specifies the maximum height that the control add-in can be stretched to. This setting only applies if the VerticalStretch setting is specified.
MaximumWidth Integer Specifies the maximum width that the control add-in can be stretched to. This setting only applies if the HorizontalStretch setting is specified.
VerticalStretch Boolean Specifies that the control add-in can be made larger vertically. This setting is optional.
HorizontalStretch Boolean Specifies that the control add-in can be made larger horizontally. This setting is optional.
RequestedHeight Integer Specifies the initial height of the control add-in.
RequestedWidth Integer Specifies the initial width of the control add-in.

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