(updated: Sample project download: Sept 09)
(updated to SP1 CTP2 and release API: 07.June09)
Extensibility for the RoleTailored client also called “Add-ins”, is the feature which I personally love most in our SP1 release of Microsoft DynamicsNav 2009. Starting with this service pack partners have the possibility to add custom controls to the IU of the RoleTailored client.
These controls can be anything - from a static logo picture (not read from the database), to an edit control with rich formatting, to a web browser control pointing to sites relevant for the user or his role or to advanced data visualizations. These controls are truly hosted within the pages of the RoleTailored client and treated with the same respect as the build-in controls.
In this post I want to introduce the concept of Add-ins for the RoleTailored client and show the most basic code sample.
(We will have a few minor changes to the Interface when we release, and I will update my posts when it comes out.)
Using a control Add-in
Creating a simple control Add-In
[ControlAddInExport("MyFirstAddIn")]public class MyControlAddIn : WinFormsControlAddInBase
protected override System.Windows.Forms.Control CreateControl()
Add-ins are contained in a DLL file, which must be a managed assembly. They are discoverable artifacts, which follow certain standards. An Add-in is the provider of a control that can be rendered and hosted in the layout of the UI of the RoleTailored client. Controls from an Add-in can only be used on pages and not on forms for the Classic client.
The C/Side development environment must be made aware of an Add-In. All Add-Ins must be registered in Table 2000000069 (“Client Add-In”). The required information, such as the Control Add-in Name and Public Key Token, are typically delivered by the provider of an Add-in.
In an upcoming blog post I will make a tool available that allows you to select one or more assemblies and register all contained Add-ins.
The property ControlAddIn of a field on a page must set in order to select a certain Control Add-in.
Control Add-ins are supported for stand alone fields on a page. Please note the exception: Fields in a repeater are not supported yet.
But don’t worry, so much about all the options right now. In this post i will begin with a basic sample and you will see how simple it really is to create an utilize an Add-In.
My first Add-in sample is a simple static picture control. The special characteristic is that picture data has been embedded into the control instead of having to retrieve it through data binding from a table on the server. This could be used for a static Logo. Instead of embedding the data into the picture, the control could load pictures from a local store or a Web Service instead – but this out of scope of my goal for this blog post.
I start by creating a class library in Visual Studio. In Solution Explorer add a reference to the library above. Then, in the Project settings I create a new signature file. If I had created Add-ins before, I might choose to use the same signature for all and select an existing signature file from another project.
Please note: It is required that Add-in libraries are strong signed. This requires that all referenced libraries are also strong signed. This is not an issue for any of the .NET Framework libraries. But you might find 3rd party libraries that have not been signed. You can sign those yourself with the signing tool of the .NET Framework.
Now I add one code unit to the project. In it I declare a public class with the [ControlAddInExport("name")] Attribute. The chosen namespace and the name of the class do not matter as far as how the Add-in is exposed. However, is the name you have chosen is essential for theControlAddInExport attribute. This name together with the Public Key Token of the assembly signature will be used at runtime to identify the Control Add-in.
using System.Windows.Forms;using Microsoft.Dynamics.Framework.UI.Extensibility;using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms;namespace AddInSamples{ [ControlAddInExport("SampleControl1_StaticPicture")] public class MyStaticPictureControlAddIn : WinFormsControlAddInBase { }}
Next I need to provide an implementation for the abstract method CreateControl. This is the place where I instantiate a PictureBox control and load it with an image, that I had added to a resource file in the project.
[ControlAddInExport("SampleControl1_StaticPicture")]public class MyStaticPictureControlAddIn : WinFormsControlAddInBase{ protected override System.Windows.Forms.Control CreateControl() { PictureBox pic = new PictureBox(); pic.Image = StaticPictureResources.Logo; return pic; }}
[ControlAddInExport("SampleControl1_StaticPicture")]public class MyStaticPictureControlAddIn : WinFormsControlAddInBase{ protected override System.Windows.Forms.Control CreateControl() {
PictureBox pic = new PictureBox(); pic.Image = StaticPictureResources.Logo; return pic; }
}
After compilation of my project I already have a fully functional Add-in. But we still need to fine-tune it a bit until it looks good:
Two modifications should be applied:
Modification 1 is achieved by overriding the virtual property AllowCaptionControl
public override bool AllowCaptionControl{ get { return false; } }
Modification 2 is done by setting the MinimumSize and MaximumSize of the PictureBox control.
protected override System.Windows.Forms.Control CreateControl(){ PictureBox pic = new PictureBox(); pic.Image = StaticPictureResources.World; pic.MinimumSize = pic.MaximumSize = pic.Image.Size; return pic;}
Perfect ! Now we have a static picture, by default without a title and sized to the original size of the embedded picture.
You should take the tutorial in this blog as a sample of non-data bound content from any source on a page in the RoleTailored client of Microsoft Dynamics NAV 2009.
My next blog post will show how to create a custom text box, bound to data.
Stay tuned!
Christian Abeln Senior Program Manager Microsoft Dynamics NAV