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. 

GoldenCallerFor 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:

 image

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: Screen2
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.

image

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.

image 

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 “

image

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.

imageI 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 ;-)

Comments

  • Anonymous
    December 02, 2009
    Dear Christan, This is very informing and helpfull many Thanx. One question. What would be the preferred way in making data available in an Add-in when multiple records and/or tables are involved. This could be a Webservice but then wat if one of this needs data to be modified in NAV again a Webservice? regards, Rick Blom

  • Anonymous
    December 02, 2009
    Binding an Add-in to multiple records - indeed this is a popular wish. And you can write an Add-in that does this, but you have to take some manual steps for serializing & de-serializing.

  1. Bind an Add-in to a global page variable of type BigText.
  2. Write C/AL code that aggregates the rows into an XML stream, you might even use a XML port. Write the XML into the global var.
  3. When the XML arrives through data binding at the Add-in side, consume it.
  4. The Add-in can return changed XML, that C/AL code needs to process or it could send information through the OnControlAddIn trigger. This is the common approach for "Business Data Visualizations". The Treemap Business data Visualization for Microsoft Dynamics NAV 2009 will be available as a "Partner Community Release" these days. It is a sample for this best practice.

  • Anonymous
    August 19, 2010
    Hi Christian -I was intrigued by this statement in your blog:   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.Can you elaborate on that?

  • Anonymous
    August 19, 2010
    Hi Rob,with this statement I wanted to say: If you build an Add-in for the Add-in API that was available with a certain NAV release (e.g. NAV2009 SP1), your Add-in will also work without changes in a later release of NAV (NAV 2009R2, NAV7.0, ...).But your Add-in (e.g. for NAV 7.0 which will have extended API capabilitis in the Add-in API) this will not work in earlier releases of NAV.So a good idea is to evaluate which Add-in API level you require as a minimum for your Add-in and build the Add-in for that version to maximize compatibility with multiple versions of NAV.Hope this explains.

  • Anonymous
    March 19, 2012
    The comment has been removed

  • Anonymous
    March 19, 2012
    Hello Moe,The only context that an AddIn receives is the Information provides through the ControlAddInSite.Yet this information contains only properties the field which the AddIn might want to take into account for interaction and rendering purposes:Caption, Editable, Enabled, Style, ValidationResultIf you want to show information like database, page name, it seems this is more like data you want the AddIn to display. You should send them in a data document bound through through the source expression to the AddIn.Hope this helps.Christian

  • Anonymous
    September 02, 2012
    Hi Christian!I’m in charge of developing a payroll employee’s module and other functionalities about human resources management using .Net and integrate them into the NAV 2009 R2 roletailored client. But I’m inexperienced about this. So I’d like to know:Which tools should I have?How can I proceed to achieve this? Thanks for any helpful answers!!!

  • Anonymous
    September 02, 2012
    Hello Jean-Philippe,a payroll employee module for NAV is certainly a task that will involve mainly application logic, that should be build with application programming tools, by designing respective tables, transaction and validation logic and pages representing the UI - all this is typically done in C/AL code, within the NAV Development environment.(If you are not an ISV partner yourself, there are quite a number of partner solutions already existing in this domain which you could use, or NAV partners being able to support you in this development task.)Client Add-Ins and .NET interoperability are technologies that may help you, for examplewhen you have the need for custom data presentationwant to use advanced algorithmic provided by a .NET module want to communicate with external systems and services. Good luck!

  • Anonymous
    May 22, 2014
    This is fine for read-only databinding - however there doesn't seem to be any explanation of read-write databinding available anywhere?