Hosting custom WPF calendar control in AX 2012

The requirement

A couple of days ago, I needed to create a calendar like lookup but it had to be possible to block out dates for selection. In Dynamics AX, there is calendar lookup form available, but there are some minors to it:

  • It is not really (easy) customizable
  • It has limited functionality

What I needed the calendar form to do:

  • Visually block dates for selection
  • Easy navigation over longer periods
  • Support for different selection types (Single date, weeks, multiple selected dates, …)
  • Provide a custom range to display dates

So it is clear that Ax does not have a calendar like that, so I had the idea of creating a custom control for this. But due to time restriction ( isn’t there always a time restriction ! :-) ) I went looking for a WPF control that I could wrap around and integrate it with Ax. And then I found the following control that has all I need : http://www.codeproject.com/Articles/88757/WPF-Calendar-and-Datepicker-Final But having a working control in a WPF application is one thing, getting it to work with Dynamics AX is another. I noticed when I was using the control directly, the client crashed and some of the properties were not marshallable because Dynamics AX does not support generics. So wrapping the control in a control of my own was an option here. And there are two reasons why I did wrap the control:

  • When using the control directly, it crashed :)
  • When wrapping into your own control, you can decide which of the features you want to be available and which are omitted
  • It is possible to write some helper methods for generic properties since Ax does not support generics

Now let me show you how to do it.

Creating a custom WPF user control

First start of by creating a custom WPF user control. Open up visual studio and create a new project of the type WPF User Control Library. NewProject Since we are going to implement the vhCalendat control, add a reference to the vhCalendar dll file. (Found in the CodeProject post link above). Once the reference is in place and before going into XAML mode, let us take a look at the code behind file and put some things in place.

Control definition

First we have a partial class that defines the CalendarViewControl. Extending this later with your own stuff should be easy since it is a partial. public partial class CalendarViewControl : UserControl, INotifyPropertyChanged

Control properties

Now lets add properties for all of the calendar’s properties that we want to expose. (Here I will not show them all, just some examples)

/// <summary>
/// Gets/Sets the date that is being displayed in the calendar
/// </summary>
public DateTime DisplayDate 
{ 
    get 
    { 
        return (DateTime)theCalendar.DisplayDate; 
    } 
    set 
    { 
        theCalendar.DisplayDate = value; 
        RaisePropertyChanged("DisplayDate"); 
    }
} 
 
/// <summary>
/// Gets/Sets animations are used
/// </summary>
public bool IsAnimated 
{ 
    get 
    { 
        return (bool)theCalendar.IsAnimated; 
    } 
    set 
    { 
        theCalendar.IsAnimated = value; 
        RaisePropertyChanged("IsAnimated"); 
    } 
} 
 
/// <summary>
/// Gets/Sets the selection mode 
/// </summary>
public CalendarSelectionType SelectionMode 
{ 
    get 
    { 
        int i = (int)theCalendar.SelectionMode; 
        return (CalendarSelectionType)i; 
    } 
    set 
    { 
        int i = (int)theCalendar.SelectionMode; 
        theCalendar.SelectionMode = (SelectionType)i; 
        RaisePropertyChanged("SelectionMode"); 
    } 
}

The last property above shows a bit of ‘nasty’ code because I needed to translate the System.Windows.Visibility enum into a custom enum. This was because the CIL generator had a problem with the System.Windows.Visibility enum. CIL kept giving me the error : ‘Invalid cast’ until I used a custom enum.

Control events

Next to some properties, there are also a couple of events. The first one is to let Dynamics AX know that the selected date has changed.

public delegate void SelectedDateChangedEventHandler(object sender, EventArgs e); 
 
public event SelectedDateChangedEventHandler SelectedDateChanged; 
 
/// <summary>
/// Raised when the selected date changes in the calendar.
/// </summary>
public void RaiseSelectedDateChanged(object sender, vhCalendar.SelectedDateChangedEventArgs e) 
{ 
    if (SelectedDateChanged != null) 
    { 
        SelectedDateChanged(this, new EPSSelectedDateChangedEventArgs() { NewDate = e.NewDate, OldDate = e.OldDate }); 
    } 
}

Please note that the delegate is outside of the class but in the same namespace. Af of now, I’ve implemented single selection but there are also events in the calendar for when multiple selection changes.

Another important one is the RaisePropertyChanged event. This event will be useful to us when we are using binding in XAML. It will notify the control’s user interface that a property has changed and all of the UI elements that are bound to the corresponding property will be updated. (Note that the delegate PropertyChangedEventHandler is already known because our control implement INotifyPropertyChanged.

/// <summary>
/// Raised when one of the properties was changed in the WPF control
/// </summary>
public void RaisePropertyChanged(string propertyName) 
{ 
    if (PropertyChanged != null) 
    { 
        PropertyChanged(this, new PropertyChangedEventArgs(propertyName)); 
    } 
}

Implement the control in Dynamics AX

Now for the AX part, start with creating a form with a ManagedHost control so that we can host the control. When you add the ManagedHost control, a windows will popup to select the control type that you want to use. In that window, select the reference to the dll (or browse for your dll) and select the type of control to use.

WPFDLLReference

 Next we need a way to handle the events of the calencar control. When we choose a date in the control, we need to be notified in X++ so that we can do what we want with it.

To do that, you can right click the ManagedHost control and select events. In the events window, you can now select our selectedDateChanged event and add an X++ handler method to it.

ManagedControlEventSelection

  The following code was added to our form ( Note that you can also use the ManagedEventHandler class when you are consuming external services asynchronously! ):

_ManagedHost_Control = ManagedHost.control();
_ManagedHost_Control.add_SelectedDateChanged(new ManagedEventHandler(this, 'ManagedHost_SelectedDateChanged'));

So when we open our form and we select a date in the calendar, the ManagedHost_SelectedDateChanged method will be called. So let’s open up the form and see what it looks like.

InitialCalendarView

Nice! But are we satisfied yet? Not quite…

Imho when implementing things like this, you should always keep in mind that others want to use your control in other contexts. Today I want to use it when selecting delivery dates but if we make some modifications, everyone can use this in any context they want.

What I did to achieve this is to create two things:

  • A property bag class that contains all of the properties that can be passed to the control.
  • An interface that forms need to implement when they want to host the control.

So first let’s take a look at the property bag. This is in fact merely a class with some parm methods on it. No PhD required here :)

/// <summary>
/// Data container class containing the parameters that can be set on the WPF control from inside Ax.
/// </summary>
public class EPSWPFCalendarParameters
{
    // Selection type of dates (single, multiple, ...)
    EPS.AX.WPFControls.CalendarSelectionType selectionType;
 
    // Start view of the calendar (month, year, decade, ...)
    EPS.AX.WPFControls.CalendarDisplayType displayType;
 
    // Date being displayed in the calendar
    System.DateTime displayDate;
 
    // Date from where the calendar displays dates
    System.DateTime displayDateStart;
 
    // Date to where the calendar displays dates
    System.DateTime displayDateEnd;
 
    // Use animation and transitions in the calendar
    boolean isAnimated;
 
    // Show the footer
    EPS.AX.WPFControls.CalendarVisibilityType footerVisibility;
 
    // Color the today's date in the calendar
    boolean isTodayHighlighted;
 
    // Show week columns
    EPS.AX.WPFControls.CalendarVisibilityType weekColumnVisibility;
 
    // Dates that will be marked as blocked and will not be selectable in the calendar
    Map blockedDatesList;
}

Apart from the parm methods, there is also an initialization method present so that some defaults are set in case they are not specified by the caller.

public void initDefaults()
{
    ;
    this.parmDisplayDate            (systemDateGet());
    this.parmDisplayType            (EPS.AX.WPFControls.CalendarDisplayType::Month);
    this.parmFooterVisibility       (EPS.AX.WPFControls.CalendarVisibilityType::Visible);
    this.parmIsAnimated             (true);
    this.parmIsTodayHighlighted     (true);
    this.parmSelectionType          (EPS.AX.WPFControls.CalendarSelectionType::Single);
    this.parmWeekColumnVisibility   (EPS.AX.WPFControls.CalendarVisibilityType::Visible);
    this.parmBlockedDatesList       (new Map(Types::Date, Types::Date));
}

Now for the next part, let’s create an interface that simply asures that forms hosting the control have a method to construct parameters for the calendar control.

/// <summary>
/// Interface for defining what is needed to be able to host the EPS WPF Calendar control on that form.
/// </summary>
public interface EPSWPFCalendarFormHostable { } 
 
/// <summary>
/// Calendar parameter data bag.
/// </summary>
/// <returns>
/// An instance of EPSWPFCalendarParameters 
/// </returns>
public EPSWPFCalendarParameters calendarParameters() 
{ }

This interface needs to be implemented on the caller form. Below we have an example of just that. (Note that for this example the code is on the form, but this should be done in a form handler class)

class FormRun extends ObjectRun implements EPSWPFCalendarFormHostable
 
/// <summary>
/// Contains parameters for the WPF calendar
/// <summary>
/// <returns>
/// An instance of EPSWPFCalendarParameters. 
/// </returns> 
public EPSWPFCalendarParameters calendarParameters() 
{ 
    ; 
    // Create default instance of the parameters 
    calendarParameters = EPSWPFCalendarParameters::construct(); 
 
    // Set the calendar selection mode to a single date 
    calendarParameters.parmSelectionType(EPS.AX.WPFControls.CalendarSelectionType::Single); 
 
    // Set the default view to a month 
    calendarParameters.parmDisplayType(EPS.AX.WPFControls.CalendarDisplayType::Month); 
 
    // Passes a map of dates to be blocked for selection in the calendar
    calendarParameters.parmBlockedDatesList(this.parmBlockedDeliveryDates()); 
 
    return calendarParameters; 
}

For the last part, we need to glue these together. This is done in the form where we host the calendar control. When the form is called, it requests the calendar parameters from the caller and applies all of them to the control.

public void init()
{
    SysSetupFormRun formRun = element.args().caller();
    ;
    super();
 
    // Check if the managed host is even the right type
    if(ManagedHost.control() is EPS.AX.WPFControls.CalendarViewControl)
    {
        calendarViewControl = ManagedHost.control() as EPS.AX.WPFControls.CalendarViewControl;
    }
    else
    {
        throw error("@EPS6008");
    }
 
    // Initialize from the caller interface (The caller should have implemented the interface that contains the calendarParameters)
    if(formHasMethod(formRun, 'calendarParameters'))
    {
        hostable = element.args().caller();
 
        // The hostable should have the parameters defined
        calendarParameters = hostable.calendarParameters();
 
        // Initialize the calendar control based on the found parameters
        element.initControlParameters();
    }
    else
    {
        throw error("@EPS6009");
    }
 
    // Register an event handler that attached to the selected date changed event of the calendar control)
    calendarViewControl.add_SelectedDateChanged(new ManagedEventHandler(this, 'ManagedHost_SelectedDateChanged'));
}

Note the formHasMethod call. This is an extra safety check. When using classes, the compiler makes sure that you have implemented the interface’s methods. But with forms, you never have a constructor called so that the compiler can do the check for you.

/// <summary>
/// Initializes the control based on the parameters found in the caller.
/// <summary>
private void initControlParameters() 
{ 
    Map blockedDates = calendarParameters.parmBlockedDatesList(); 
    MapEnumerator mapEnum; 
    TransDate fromDate; 
    TransDate toDate; 
    ; 
 
    calendarViewControl.set_SelectionMode (calendarParameters.parmSelectionType()); 
    calendarViewControl.set_DisplayMode (calendarParameters.parmDisplayType()); 
    calendarViewControl.set_FooterVisibility (calendarParameters.parmFooterVisibility()); 
    calendarViewControl.set_IsAnimated (calendarParameters.parmIsAnimated()); 
    calendarViewControl.set_IsTodayHighlighted (calendarParameters.parmIsTodayHighlighted()); 
    calendarViewControl.set_WeekColumnVisibility (calendarParameters.parmWeekColumnVisibility()); 
 
    if(calendarParameters.parmDisplayDate()) 
    { 
        calendarViewControl.set_DisplayDate (calendarParameters.parmDisplayDate()); 
    } 
 
    if(calendarParameters.parmDisplayDateStart()) 
    { 
        calendarViewControl.set_DisplayDateStart (calendarParameters.parmDisplayDateStart()); 
    } 
 
    if(calendarParameters.parmDisplayDateEnd()) 
    { 
        calendarViewControl.set_DisplayDateEnd (calendarParameters.parmDisplayDateEnd()); 
    } 
 
    // Pass the blocked out dates collection to the control. 
    if(blockedDates) 
    {
        mapEnum = blockedDates.getEnumerator(); 
        while (mapEnum.moveNext()) 
        { 
            fromDate = mapEnum.currentKey(); 
            toDate = mapEnum.currentValue(); 
            calendarViewControl.addBlockedDate(fromDate, toDate); 
        }
    }
}

So when all of this is in place, the calendar form calls the calling form and requests the parameters, passes them to the control and renders the control. Everyone that want to have the same control hosted on their for only need to implement the calendar parameters method on the form and that’s it.

When all is in place, this is what it looks like when the calendar has blocked days:

CalandarFinished1

 

When clicking on the month title, you can easily navigate between months and years:

CalandarFinished2

 

CalandarFinished3

 

So that is the end of it. I hope you already have some ideas as to what controls you can now host within Dynamics AX 2012. It is possible to create your own, but you can host any other WPF control if you want. (Think of Infragistics controls, Telerik, …)

2 thoughts on “Hosting custom WPF calendar control in AX 2012

  1. Pingback: Axilicious » AX2012 DLL Deployment and how AX binds DLL’s at runtime

  2. Pingback: AX2012 DLL Deployment and how AX binds DLL’s at runtime - Kenny Saelen’s Microsoft Dynamics AX Blog - Microsoft Dynamics AX - Microsoft Dynamics Community

Leave a Comment Yourself

Your email address will not be published. Required fields are marked *