Add-Ins in Dynamics NAV 2013 (1#3) – Interfaces for data binding and the OnControlAddIn trigger

Introduction

With the arrival of Dynamics NAV 2013 later this year we will introduce a few improvements on our Client Add-In story which we believe will be a great productivity improvement for partners who are in the business of creating and shipping Add-Ins as part of their solutions and projects.

The new additions are found in the following areas, which each will be covered in it’s own blog post:

  • Data binding through the Source Expression to more data types (covered in this blog post)
  • Add-ins exposing custom interfaces to C/AL
  • Improved layout support, upgrade support, current limitations,

Along the way I will provide my updated Add-in tools – the new Visual Studio Templates, Add-In registration tools and we will experiment with some new samples.

 

For the restless reader (“in a few words”)

GoldenCallerLight bulb NAV 2013 support data binding for all CAL data types by mapping CAL data to one of the .NET data types: Object, string, Boolean, Char, DateTime, Decimal, Guid, Int32, Int64, TimeSpan

Light bulb Data binding and firing of the OnControlAddIn C/AL trigger are enabled by implementing respective Interfaces.

Light bulb A set of  new NAV 2013 templates for Visual Studio 2010 make it easy to create a Visual Studio project with add-ins with the selected binding and event support. (Find the templates for NAV 2009 here)

 

Data binding and eventing basics

Data binding with the SourceExpr of the field that holds the add-in has one great advantage: the data are transferred together with the other data on the page. You do not need to find the right place in C/AL triggers and write any code in order to exchange data with the add-in. The add-in will be updated automatically and changed data be saved like for all other fields. 
(In a follow up post, I will talk about custom methods, properties and events exposed by the add-in in order to allow a very rich interaction on code level.)

Already in NAV 2009 R2 we had two interfaces to support data binding over the field’s source expression and eventing through the OnControlAddIn trigger in C/AL.

Pointing up Please note:  A valid add-in class is any class derived from the base class for the respective display target and optionally implements one or both of the interfaces IValueControlAddInDefinition<T> and IEventControlAddInDefinition.

 

The basic steps in the creation process of an add-in are:

  1. Use the base class for the display target – until now the WinForms based Windows RoleTailored client, which is the class WinFormsControlAddInBase.
  2. Add and implement the interface IValueControlAddInDefinition<T> for T being one one of the supported .NET types, in order for your AddIn to be able to exchange the data which the hosting field has been conned to though the C/AL property SourceExpr.
  3. Add and implement the interface IEventControlAddInDefinition if you like your AddIn to be able to fire the OnControlAddIn trigger in C/AL, which every field already has by default.

High five The addition in NAV 2013 is that now the data binding can be cover all most C/AL data types, not just Text types and Blob. for this purpose the set of data types supported when you implement the interface IValueControlAddInDefinition<T> has been increased to the following set of .NET data types: Object, string, Boolean, Char, Datetime, Decimal, Guid, Int32, Int64, Timespan

 

But watch out! If you dare to use a data type not in that list, you may very well experience an error like the following at runtime, when you try to load the add-in:

image

(Here I had created a class named ‘CooleKlasse’ and tried to use this when declaring the add-in class.)

In order to exchange a data for a data model maintained in a class over the Source Expression of a field, you should use an add-in that implements the interface IValueControlAddInDefinition<system.string>. Write a little code in C/AL and the add-in Value property getter / setter in order to serialize / de-serialize the data model to an from string.

 

Creating an add-in class with the Visual Studio 2010 templates for NAV 2013

The Templates for Visual Studio 2010 and the new Add-In Builder make it very easy to create a basic AddIn class:

image

image  image

image

 

Convenience interfaces in NAV 2013

Already in NAV 2009 R2 we had introduced a number of convenience interface and classes which combine above for typical use cases.

High five In NAV 2013 though we have completed the set C/AL data types an add-in bind to. For that purpose the below list of interfaces are ready to use in order to create an add-in that supports firing the OnControlAddIn trigger as well as binding from a C/AL data type to a corresponding .NET data type in the add-in code.

Interface

Use

IObjectControlAddInDefinition

Event support and data binding with type System.Object maps to binary C/AL BLOB data

IStringControl­AddInDefinition

Event support and data binding with type System.String maps well to C/AL string types.

Light bulbalso the Windows Forms add-in base class StringControlAddInBase implements this interface.

IBooleanControlAddInDefinition

Event support and data binding with type System.Boolean maps well to binary C/AL Boolean data

IByteControlAddInDefinition

Event support and data binding with type System.Byte maps well to binary C/AL Byte data

ICharControlAddInDefinition

Event support and data binding with type System.Char maps well to binary C/AL Char data. Please note: with NAV 2013 this is a Unicode character type.

IDateTimeControlAddInDefinition

Event support and data binding with type System.DateTime maps well to binary C/AL DateTime data

IDecimalControlAddInDefinition

Event support and data binding with type System.Decimal maps well to binary C/AL Decimal data

IGuidControlAddInDefinition

Event support and data binding with type System.Guid maps well to binary C/AL Guid data

IInt32ControlAddInDefinition

Event support and data binding with type System.Int32 maps well to binary C/AL Integer data

IInt64ControlAddInDefinition

Event support and data binding with type System.Int64 maps well to binary C/AL BigInteger data

ITimeSpanControlAddInDefinition

Event support and data binding with type System.TimeSpan maps well to binary C/AL Duration data

These interfaces make it little easier to declare a Control add-in, that is fully supported by NAV 2013.

If you utilize the Visual Studio templates and select both support for the OnControlAddIn trigger and data binding, the template wizard will be smart enough to pick the right interface.

image

image

 

Further steps

In order to return the control instance to the Windows RoleTailored client you will implement the method CreateControl, like in your add-ins for NAV 2009 R2.

In order to have the add-in respect the settings of the field context you will need to override the methods like OnCaptionChanged from the WinFormsControlAddInBase. Again no changes here compared to developing add-ins for NAV 2009 R2.

For the control of the size you had in NAV 2009 R2 make the control to return a proper MinimumSize, MaximumSize and PreferredSize and would sometimes also set the Dock property of the control. In NAV 2013 we have introduced the ApplySize method, which allows you to define the default sizing behavior on the add-in class. I will describe this in a follow up post, as well as the most interesting topic: custom interfaces exposed by add-ins to C/AL code.

 

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV