Add-ins for the RoleTailored client of Dynamics NAV 2009 SP1 (part2)

Yesterday afternoon, a colleague from Italy send me an IM asking for help on a customer scenario. The customer wants his users to see a strong warning sign attached to the item availability in the Item FactBox. The warning shall only be shown if the availability drops under a certain level. He had already experimented with the new Style property on NAV fields in SP1. He was able to show conditional formatting on the item availability field. But what the customer really wants is a more visual indication – yeah, a screaming warning icon!

On my way home in the train (public transport is just great for such tasks) I could not stop me from creating two little Add-ins as samples for that purpose. And because these two Add-ins nicely continue on the topics I have covered in part1, I decided to share this with you. 

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

A Control Add-in may listen to its context (“context binding”) The context for a control Add-in is provided through the Site. The Style is one of the properties of the Site, and the respective change event is also available. An Add-in can listen to changes in the context (Site) and reflect it in its visual appearance. I call this “context binding”. And the result might look like this: Combine simple data binding with context binding A control Add-in inherits the data binding of the field through the source expression in page designer. By implementing the properties Value and HasValueChanged it participates in data binding. An Add-in can combine data binding with context binding for maximum data awareness. And it might trigger custom events in business logic, for example an advanced lookup. And the result might look like this: Download the full source code project here

A train ride on the “Notification Icon Add-in”

First stop – “Vedbæk”: Check the requirements Requirements

The requirements for these Add-ins have been given to me:

1. Used to show a notification icon in a FactBox.
2. Show the standard field title
3. Add-in number 1: If a certain condition as defined in Business Logic fulfilled then show a LARGE notification icon. Otherwise, show no icon.
4. Add-in number 2: Render nicely in the flow of other fields, render the value aligned with other values, support the same field click and DrillDown capabilities as standard fields. If a certain condition as defined in Business Logic fulfilled then show a notification icon in front of the value. Otherwise, show no icon.

Let translate those requirements into the world of Add-ins:

1. FactBoxes are read-only. Therefore I will only need to implement read-only data binding. And I only need to provide rendering support for the icon and a value for number 2. – a PictureBox and a Label control will do.
2. A field title is shown be default unless we actively suppress them in code by implementing the AllowCaptionControl and making it return false. Therefore nothing needed here.
3. Of course, a couple of icons are needed in the Add-in resources - not problem either. 
   However, we need a mechanism that communicates the condition. In a second version of the Add-in, we also want to show the value. Therefore, we reserve data binding for for the value and utilize the Style property of the field for the warning condition.
   (A field can be bound through the StyleExpr field property to a Boolean variable which decides whether the Style as specified in the Style field property will be applied or not. The Add-in subscribes to the StyleChanged event and shows one of the notification icons based on the style it sees. Nothing simpler than that…)
4. For the last requirement we need to adjust the height of the control properly, align the controls nicely to the right, be sure that we draw the value in blue and finally switch underlined on and off as the mouse hovers in and out of the field. Moreover, we should not forget to set the “Hand” cursor and listen to the click event plus trigger C/AL code.

That should be doable in one train ride. Let’s code it!

Next stop – “Kokkedal”: Build a simple Notification Add-in with “context binding”

A read only Add-in showing a right aligned Icon from the resources, based on the Style property of the Site - nothing simpler than that.

What is worth to mention here is the use of a Panel control as the layout container, which I return as the Add-in control. In the Panel I can easily dock the icon to the right such that it appears nicely aligned under the other values in the Factbox. A PictureBox control renders the Icon, and the Add-in must specify a proper maximum and minimum size.

The “context binding” is achieved by overriding the OnStyleChanged method which already delivers the new style. Please note: if the variable to which the NAV field property StyleExpr is bound to is false, then the Style will be “None”, otherwise it is the value of NAV field property Style.

 [ControlAddInExport("SampleControl_NotificationIcon")]
[Description("Notification icon based on Style property")]
public class MyNotificationIconAddIn : WinFormsControlAddInBase
{
    private PictureBox _picture;

    protected override System.Windows.Forms.Control CreateControl()
    {
        Panel panel = new Panel();
        Bitmap icon = StaticPicturHelper.StyleToPicture(Style.Attention);
        panel.MinimumSize = new Size(icon.Size.Width, icon.Size.Height);
        panel.MaximumSize = new Size(int.MaxValue, icon.Size.Height);

        _picture = new PictureBox();
        _picture.Visible = false;
        _picture.SizeMode = PictureBoxSizeMode.AutoSize;
        _picture.Dock = DockStyle.Right;
        _picture.Parent = panel;
        return panel;
    }

    protected override void OnStyleChanged(Style style)
    {
        _picture.Visible = (style != Style.None);
        _picture.Image = StaticPicturHelper.StyleToPicture(style);
        base.OnStyleChanged(style);
    }
}

Now, that was easy – wasn’t it? Take a look at the Add-in Project in the download for this blog post. This also contains a modified “Sales Line FactBox” 9087 with little integration code.

Next stop – “Humlebæk”: Show the value, read only data binding and click with drill down

Now I want to show also the value for Availability in a similar way as a standard field does. I shall look and behave like a link, with mouse over effect and all that. As mentioned above, I just need to add a Label into the layout container and handle the mouse events.

More interesting is the data binding. I decide for a different base class (StringControlAddInBase), which has some support already built in, override the Value and HasValueChanged properties, and reroute the value that arrives at the Add-in to the Label control.

And what about the click event? A mouse click event handler for all the controls (Panel, Label & Picture) triggers the ControlAddIn trigger in the Business logic on Page 9087, which in turn asks for the Drill down.

 void DoOnMouseClick(object sender, MouseEventArgs e)
{
    this.RaiseControlAddInEvent(0, "");
}

The ControlAddIn event allows me to send a message ID with text data. But for this Add-in I really don’t need any discriminator for different events, therefore I can specify whatever parameters here.

And this is the code that handles the event in the server side business logic. It is the standard code that executes drill down on availability.

Last stop – “Helsingør”:  Integration

It is time to utilize the Add-ins on the “Sales Line FactBox”. As usual, I copy the Add-in library to the Add-ins directory of the RoleTailored client and register them once with the Registration Tool.

In Page 9087 (“Sales Line FactBox”) I add a new field at the bottom for the simple Warning notification field and specify the first Add-in in the Control Add-in Property. The existing “Availability” field gets the second Control Add-in configured. Both fields get “

The variable “styleActive” is declared as a global Page variable and reflects is set by the business code for each record based on the item availability.

The fob files 9087.fob / .txt in the download material contain all changes for your review.

Ferry ride home and Wrap Up

The last ride home on the ferry gives me time to write up this little document package the project files so I can make them available to my colleague in Italy and to you through this blog post.

I hope this information is somewhat useful and gives you a little more insight into Control Add-ins for the RoleTailored client in Dynamics NAV 2009 (SP1).

You can download the project here.

And what have I learned from this small exercise? There are a few improvements needed for the future of our Add-in model in Dynamics NAV:

• An Add-in should be able to find out about the sizing of a standard field. Look at the distance between the fields “Availability:”, “Substitutions:” an “Sales Prices:” and you know what I mean.
• An Add-in should be able to trigger the default behavior for Lookup, Drilldown and Assist Edit such that it does not need to raise the ControlAddIn trigger for the same purpose and force the Business Logic developer to move respective code.

However, do not worry about changes in the future now. We have one important design goal for the Add-in framework: Existing Add-ins shall be usable without changes in later releases of the NAV product.

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

Ps: If you have other suggestions for useful control Add-ins, don’t hesitate to contact me – I have a train ride and a ferry home every day ;-)