Features of a Dataset PCF – Extensibility

This is the second part of my blog about the dataset PCF features. The other ones are: Seamless integration, Multiple datasets

Dataset <property-set>

A dataset PCF has another nice feature: allows you to define properties inside the dataset. This attribute doesn’t have to be in the view itself, the framework will add this attribute at runtime for you.

In the example below, consider that the PCF needs an optionset attribute to render each row in another color, based on the colors defined in the optionset customizations. The customizer has the possibility to choose the attribute as he/she wishes, and the component has the chance to implement that in a generic manner. No hard-coded attributes. Nice feature.

To define this kind of properties, define <property-set> nodes inside the <data-set> node in the manifest.

<data-set name="dataset1" display-name-key="Dataset_Display_Key1" cds-data-set-options="displayCommandBar:true;displayViewSelector:true;displayquickfind:true">
      <property-set name="colorOptionset" display-name-key="Property_Display_Key" description-key="Property_Desc_Key" of-type="OptionSet" usage="bound" required="true" />      
</data-set>

This is the customizing experience for defining a “property-set”.

Configure properties inside a dataset

Note: Defining “property-set” parameters inside a data-set doesn’t mean that the attribute must be provided by the view. It means that the Framework Runtime will automatically add it to the dataset records for you.❤️

Other dataset sdk possibilities

Beside the manifest definitions, you can also interact with the data using code. You have access to:

• filtering – on top of the view that’s defined and on top of the filter resulted from the search-box, you can add more filters using code.
• addColumn – to add a column to a dataset
• openDatasetItem
• refresh

Below is an example of setting the filter. After that you need to call the “refresh” method; otherwise it won’t apply.

context.parameters.dataset1?.filtering.setFilter({
    filterOperator: 0,  //and
    conditions:[
	{
        attributeName: "subject",
	conditionOperator: 0, //eq
	value: "M1"
	}
    ]
});
context.parameters.dataset1?.refresh();

Setting this filter, I’ve got this fetch condition in the network protocol:

<filter type="and">
	<condition attribute="statecode" operator="eq" value="0"/>
	<condition attribute="ownerid" operator="eq-userid"/>
</filter>

<filter type="or" isquickfindfields="1">
	<condition attribute="subject" operator="like" value="abc%"/>
</filter>

<link-entity name="orb_pcftester" from="orb_pcftesterid" to="regardingobjectid" alias="bb">
	<filter type="and">
		<condition attribute="orb_pcftesterid" operator="eq" uitype="orb_pcftester" value="a1541409-7f68-ea11-a811-000d3a23cb53"/>
	</filter>
</link-entity>

<filter type="and">
	<condition attribute="subject" operator="eq" value="M1"/>
</filter>

In the fetch above you can find several filter nodes:

• lines 1-4 is the part that is defined in the view itself
• lines 6-8 was automatically added by the search box (I was searching on “abc”)
• lines 10-14 is the dependency to the parent entity (since this is a subgrid)
• lines 16-18 is the part I’ve added using the code.

Maybe is worth to say that the context.parameters.dataset1?.filtering.getFilter() reflects only the filter that was set using code. It doesn’t get mixed with the other filters added to the fetchXml. In the beginning it is null.

Disabled view

Similar to the field typed PCFs, in a dataset PCF you also have a parameter telling if the component should be disabled

context.mode.isControlDisabled === true

This can happen when the parent record (where the subgrid is hosted) was deactivated. In case the PCF component allows you to make changes directly inside the component, consider this indicator and switch to a read-only view. Of course the statecode of the records inside the dataset is also relevant.

Are dataset & properties combinations possible?

Here starts to get a little unclear, since I couldn’t find much in the docs.

I made some tests mixing <data-set> and <property> in the manifest, and here are my results:

1. Not supported: <data-set> & <property usage=”bound”>

Interesting was that the Harness didn’t had a problem with that. I could even import the solution, and define it in a model-driven app. I could even customize the parameters for my PCF component, both dataset and fields, but the I couldn’t save the form customization after that. The error message was pretty clear, so this seems unsupported:

Message: The form XML is invalid. The control ‘Tasks’ is declared as a dataset control, but its manifest XML declares it as a field-level control.

I wish we could have mixed datasets with bound properties. Then we could have implemented requirements like: make a list with records and calculate the sum in a field. My personal believe is that in the beginning it was designed to cover even this, because I’ve found an very interesting thread in the community: https://powerusers.microsoft.com/t5/Power-Apps-Pro-Dev-ISV/Dataset-control-Property-bound-to-form-attribute-is-not/m-p/319152#M567 But the reality is: it doesn’t work.

I guess, for covering this kind of requirements (like calculated sums) you need to make some webAPI requests, or use PlugIns, or try to use postMessage to send messages to another field-type PCF, like in my other blog: Can PCFs communicate each other?

2. Gray zone: <data-set> & <property usage=”output”>

Actually the parameter usage=”output” is not supported, since it’s not documented. In the documentation the usage is specified as “bound” or “input”. But the CanvasApps work with parameter usage=”output” and I could import a pcf with this combination in a CanvasApp.

3. Allowed: <data-set> & <property usage=”input”>

This combination worked both in ModelDriven and CanvasApps. The input parameters can be defined exactly with the same customizing experience as the field type PCFs: as Enums, static values, or can be linked to attributes from the parent Entity.

The input parameters can be used to allow the citizen developer to choose from more options. But it can also be used to link to some other fields from the parent entity. If the PCF is defined for a home grid (not a subgrid), it is only possible to define a static value or Enum.

This is also a nice feature. As an example, consider a subgrid on the account form. The subgrid should show different records, depending on the industrycode of the account. It depends on the kind of filter you need. Sometimes you can express the conditions inside the fetchXml. But sometimes it’s complicated. This “input” parameter allows you to inject different filter, depending on the industrycode value.

BUT, keep in mind that the dataset PCF won’t be refreshed after this field paramater changes. You need to refresh the subgrid, or wait for the autosave. And that’s only consequent, since the data is provided using a fetchXml, so the change to your parameter has to be saved first.

The linked blogs about Dataset PCF features: Seamless integration, Multiple datasets