[Model-driven apps – Client Scripting] How to interact the client API with a PCF control in a form using the OnOutputChange event?

In this blog, we will discover a new addition to the Client API. This event is the “OnOutputChange” that allows triggering a handler after a PCF control has notified the change of its outputs.

This event is valid for controls that live in model-driven app forms. The use of this event creates communication between PCF controls and the Client API. Using this event enables us to solve several problems, such as:

  • Avoid using unsupported code by the power apps component framework.
  • Decouple the form business rules from the component implementation.
  • Implement more generic controls that can be used in model-driven app forms and Custom Pages or Canvas apps.

Now let’s see what methods the Client API offers to use this event:

  • addOnOutputChange: Adds an event handler to the onOutputChange event for a given control.
  • removeOnOutputChange: Removes an event handler from the onOutputChange event for a given control.
  • getOutputs (*): Returns a dictionary of the output properties of the control.

(*) At the time of writing this blog, I believe that the current docs is not correct. We should use the getOutputs method instead of getOutput to get the output dictionary from the PCF.

We can summarize the communication flow between a Control PCF and the Client API with the following flow:

  • A PCF Control notifies the changes of its outputs with the notifyOutputChanged method.
  • If the OnOutputChange event is attached to this control. Then a handler is triggered.
  • The execution context is passed as a parameter to this Handler. This allows to give access to the control and to get the new values of the outputs with the getOutputs method.

Enough about the theory. Let’s try to implement the following scenario. Let’s take the example of a PCF Control that validates the text input according to a regular expression:

  • The PCF Control checks the text value while the user is typing.
  • When the input is changed, the PCF returns a boolean according to the regular expression test.
  • The output is named “isValid” and its value is equal to true if the regular expression is satisfied.

We will apply this PCF control to the “telephone1” column of the account table, and attach the OnOutputChange event to this control. The idea is to display a notification on this control while the user is typing and the regular expression is not satisfied.

Before going to the Script implementation. You can download and read more details about the PCF Control used for this use case in my GitHub. Below is the configuration used for this scenario:

Now let see the JS part. Remember that we want to display the notification while the user is typing and not change the value of the column. For this we will use the OnOutputChange event and not the OnChange event:

var MEA = window.MEA || {};
var accountForm = MEA.accountForm || {};
(function () {
this.OnLoad = function (onLoadContext) {
var formContext = onLoadContext.getFormContext();
var phoneControl = formContext.getControl('telephone1');
phoneControl.addOnOutputChange(this.OnOutputChangeHandler);
};
this.OnOutputChangeHandler = function (OnOutputChangeContext) {
let attribute = OnOutputChangeContext.getEventSource();
let formContext = OnOutputChangeContext.getFormContext()
switch (attribute.getName()) {
case 'telephone1':
let telephone1Control = formContext.getControl('telephone1');
let telephone1ControlOutput = telephone1Control.getOutputs();
let isValidTelephone1 = telephone1ControlOutput["telephone1.fieldControl.isValid"].value
if(!isValidTelephone1){
telephone1Control.setNotification('Telephone1 is not valid','telephone1ControlNotification');
}
else {
telephone1Control.clearNotification('telephone1ControlNotification');
}
console.log(this.isValid_telephone1);
break;
default:
break;
}
}
}).call(accountForm);
view raw AccountForm.js hosted with ❤ by GitHub

Let’s focus on the extraction of the outputs. The method “getOutputs” returns a dictionary. According to my analysis, we need to use a specific key pattern to extract the value of the output “OutputName” for a control “ControlName”:

Key Pattern: {ControlName}.fieldControl.{OutputName}
Example: telephone1ControlOutput["telephone1.fieldControl.isValid"]

Finally, I share with you this tweet that discusses the same topic of this blog where the exchange is very instructive. Hope it helps …

One thought on “[Model-driven apps – Client Scripting] How to interact the client API with a PCF control in a form using the OnOutputChange event?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s