What is the Custom Control Framework, and why should Dynamics 365 developers be excited about it?

The Custom Control Framework (CCF) is a new area of customisation in Dynamics 365 v9+. You will now be able to develop, or use existing controls, that provide new ways of both visualising and editing form data.

The controls can be added to forms to deliver a more engaging user experience and provide better ways to control and edit data. They are client-side components that are developed using TypeScript/JavaScript, HTML and CSS, similar to HTML Web Resources.

The first example of an out-of-the-box control built against the new framework is the Editable Grid that has been available since v8.2:

Editable Grid in v9
Form Control Properties window

In the Set Properties dialog shown above for a subgrid, the Editable Grid control can be added and selected for use against different device types. This is the same for any field and will show custom controls alongside the out of the box controls if any are available.

The area in the latter half of the dialog is where you can set input variables that can either be bound to a field or control (such as a grid), or a static value. This allows the controls to be reused as the data the control needs should ideally be provided in the input variables.

More examples of out-of-the-box CCF controls:

Out-of-the-box CCF Controls

Differences between CCF and HTML Web Resources

If this is your first time reading about CCF controls, you may be asking yourself what the differences between a CCF control and a traditional HTML Web Resource are?

This is an important question and there are a few things I’d highlight to summarise the differences and why in almost all cases, CCF controls will be better.

1. First class form citizens

For anyone familiar with developing HTML Web Resources, you’ll be aware they’re loaded asynchronously within an IFrame, meaning they often load long after the other form components leading to a disconnected user experience.

Being loaded in an IFrame means that scripts loaded in a HTML Web Resource are running in a different context/scope than other scripts on the form which can lead to scenarios where you have to reference the parent window object to access the form context object, this limits the reusability and adaptability of your Web Resources.

This changes with CCF controls, unlike HTML Web Resources, they’re rendered as part of the form in the same context/scope, they load at the same time as any other controls, providing a more seamless experience for users.

2. Bundled resources

Keeping track of all the Web Resources that make up a control rendered using a HTML Web Resource can be difficult. Typically, you’ll have HTML, JS and CSS files, with nothing grouping them together.

With Custom Controls, the files are packaged into a single Custom Control that are shown managed in Solution Explorer as a single solution component.

3. Performance

In the case of binding to a control like a grid, the data or at least an object capable of retrieving the data will be passed to the control, meaning there may be a performance benefit over a traditional Web API query as you would have to do in the case of a HTML Web Resource.

4. Reusability

The main advantage with Custom Controls is their reusability. The controls have variables that can be bound to fields or controls. If developed correctly, in most instances a control you create should be able to be used many times, across different forms and different entities.

5. TypeScript — Start as you mean to go on

Microsoft uses TypeScript to develop their Custom Controls and it is suggested to be the preferred language for anyone developing CCF controls. I believe is a first from Microsoft in the Dynamics 365 space. As a team, we’ve been using TypeScript to improve our development process and client-side code quality for a while, but it doesn’t seem to be as popular with other partners and developers.

There is nothing forcing developers to use TypeScript to develop CCF controls, but if you’re not already familiar with TypeScript this would be a great opportunity to learn.

Hopefully this will inspire a movement towards TypeScript for all client-side development in Dynamics, that would speed up adoption for Microsoft to release official type definitions for form libraries.

If you are already familiar with TypeScript, my colleague, Max Ewing recently published Writing TypeScript Packages for Dynamics 365, which gives a fantastic guide for setup and overview of considerations, specifically for Dynamics 365 development.

Great, when can I use them?

Although not yet officially released, a lot of the functionality to use the CCF controls is already available as of v9. Currently, the tooling to deploy CCF controls is not available, it is most likely that an update to the Developer Toolkit will be released that adds the functionality necessary to deploy CCF Controls. There is no documentation currently available.

There are blog posts starting to appear that show you how you can start developing controls now, such as Custom Controls Framework — with example which we featured in our recommended articles last month.

But at this point the features are currently in a preview state, and it would be unwise to use them for anything in anger, as they’re likely to change before they’re fully released.

Other considerations

Reusability

The main advantage of the new Custom Controls is their reusability. It should be a priority to write your logic in a way that means it doesn’t depend on a certain context, such as dependency on a particular field on the form being available, or even assuming that the control is only going to be added on forms for one entity. Ideally the context should be able to be gained through the input variables to the control.

External library dependencies

In an effort to improve performance, there are “dependency management” capabilities in the CCF to reuse libraries that are already loaded on the page. An example of this could be jQuery which is already loaded on Dynamics forms. In the manifest of the CCF controls you can specify the range of acceptable versions of the library you require, and if a matching version is already loaded, this will be used instead of making an extra request.

Don’t limit your controls

I have a suspicion that the CCF controls will become available in other areas of Dynamics such as Dashboards and PowerBI reports. For this reason, it is important to try to move away from using Dynamics form libraries to avoid dependencies on scripts that are only available on forms and instead utilise input variables as much as possible.

HTML

In the TypeScript/JavaScript, you must declare an init function that is automatically called when the control is initialised. Any HTML content should be appended to a container variable that is passed in as an argument to the init function.

Currently, it doesn’t seem possible to add a HTML file to a Custom Control and use that to define your HTML markup. This may be functionality that is added later when the framework is officially released.

Summary

Whilst Microsoft have not yet provided any official release date for the CCF controls or tooling, it is good to get an early view of what is coming and what benefits new functionality can bring. This overview has given you an idea of the advantages of the new CCF controls and how they should be able to improve Dynamics client-side development.