Dialog Buttons PCF

In my blog “Transform Forms into Dialogs and more…” I’ve described how it is possible to make dialogs out of standard form customizing using the SDK. In case you want to implement it, you might need some buttons to start the dialog actions. This PCF is about the Dialog Buttons PCF, which tries to implement these buttons.

Requirements

First, I have to find a name for this Dialogs made out of Forms. It’s so weird to write the whole explanation again and again. What about DiaForms?

There are already some Action Button PCFs in the https://pcf.gallery (for instance the Action Button made by Tanguy Touzard, the one I’ve used in my first blog about dialogs), which are great for forms. But for DiaForms, I would like to have a few more features.
Here is what I wanted to archive with the Dialog Buttons PCF:

The possibility to define more buttons at once. If there are more buttons needed, having a PCF for each button could be hard, because the positioning of fields on the form using sections is not accurate enough. The buttons have to be placed together, otherwise it might look weird.
The buttons should be translatable, without having an impact to the form scripting (the form scripting logic shouldn’t have to check the language id for implementing the logic)
The form shouldn’t get “dirty” if the button is clicked
Disabled: the buttons should be able to be individually disabled
Visible: the buttons should be able to get individually hidden/shown
Cancel buttons: in the standard dialogs (like the Assign Dialog) the Cancel button is white, while the other buttons have a background color.
The buttons should respect the theme “mainColor”, like the standard buttons
The possibility to define individual colors for the buttons
The possibility to define individual icons for the buttons
The customizer should be able to define the buttons alignment: left, center, right
The buttons should have a responsible design and adapt to the available place

PCF Design

Primary property is an OptionSet

Usually I think: “Show me your manifest, and I’ll know what’s about”. Of course, not exactly true, but it offers a good starting point. I’ve designed the DialogButtons PCF with the primary attribute bound to an OptionSet (given the latest naming changes, should I call it Choices?). I know, all of my OpenSource PCFs are about OptionSets. You will think that all I can do is OptionSets, but please don’t shoot. I’ve chosen the OptionSet since it offers two great possibilities:

Translation
- So the translation can be done using the standard translation process
- The translation doens’t have to be done as a PCF parameter
- The form scripting won’t have to check the label translated in the user language. It will just make a switch based on the value of the OptionSet
Colors
- I’ve already made a few PCFs based on the Option colors. This allows the maker to define for each button different colors. This way a “Delete” button, may be displayed in red, showing that the action cannot be undone

Disabled/Visible

In a PCF usually we don’t need to define parameters for disabled or visible state, because the platform offers the sdk for this. But since the DialogButtons is a container for more buttons, I had to design a way to disable or hide separate buttons. That’s why I have two parameters: disabledButtons (Disabled Buttons) and visibleButtons (Visible Buttons). They both work similar: are of type text and expect a concatenation of optionset values separated by semicolon (;). In case they are not set, all the options will be shown/no button will be disabled.

Static disabling/hiding

This makes sense the most for visibleButtons parameter: maybe the optionset has some options that shouldn’t be displayed for this dialog. Then you can set the “visibleButtons” to a static value, containing all the buttons that should be shown.

Dynamic disabling/hiding

If the buttons should be hidden or disabled at runtime, you can bind this parameter to a dummy attribute on your form (orb_disabled in my case). Then you can use Form-Scripting and set the value with the optionset values,

 formContext.getAttribute("orb_disabled").setValue("434350000;434350002")

There is a little bug with the platform at the moment, it seems that the PCFs rendering is not triggered when we try to set the value back to null. To work arround this, you can set the value to “,”, which would be ignored by this PCF.

formContext.getAttribute("orb_disabled").setValue(",");
//instead of formContext.getAttribute("orb_disabled").setValue(null);

Colors

Separate colors

By default the DialogButtons PCF takes care of colors by itself. It reads the color for buttons from the curren defined Theme, and it looks similar to the standard buttons (on hover or click, the buttons are getting darker)

But you are able to set the PCF to use the colors from the options corresponding to the optionset. For that you need to set the useOptionsColor (Use options color) on Yes.

Cancel Buttons

The standard dialogs have the “Cancel” buttons rendered with a white background. The PCF property “White Buttons” allows the definition of the buttons which should be displayed like this. It’s a text property. The content should be similar to disabledButtons: the value of the buttons separated with a semicolon.

For PCFs using the options colors, the white (#ffffff) will be rendered the same.

Icons

To define icons, use the property “Icons” and set a JSON content, defining for each option value the name of the icon from the FluentUI icons library.

Example for the calculate/cancel buttons:

{"434350000": "Calculator", "434350001" : "Cancel"}

Example for the forward/backward buttons in a wizard:

{
"434350000": "DoubleChevronLeftMed", 
"434350001" : "DoubleChevronLeftMedMirrored"
}

No “dirty” trace left behind

The buttons are taking care to clean up the dirty-state of the main property(OptionSet). In order to interact with the form scripting, it has to change the value of the bound property (OptionSet). But after a second, the PCF changes the value back to null. You don’t need to make that in the form-scripting. This way, if the same button is clicked again, a new OnChange will be triggered.

The form dirty state is reseted by itself

Helper function for form scripting

The github repository has also a helper function , a kind of library that you can use for your form scripting. For instance, using this helper function as a dependency, the form-scripting for my “Calculation” form is becoming something like this:

And the result:

Wizard

In my first blog about DiaForms, I’ve mentioned that I can imagine that we can make Wizards out of forms too. And that can be made in two ways:

Define more sections, and use form-scripting so that only one section is visible at a time.
- ∓ In that case the “Wizard-Buttons” can be placed on the bottom of the form, in another section, which stays visible.
Define more tabs, and switch the tab focus. Since the tab-header-area is hidden, only one tab is visible at a time.
- ∓ In that case you need to place the same PCF control on the bottom of each tab. They will be in sync, since they use the same attributes.
- ∓ In this case you don’t need that much code in form-scripting, since the disabled-state of the PCF can be set using static values (page 1 has a set of disabled buttons, page 2 another set)

In my github example, I’ve implemented the “more tabs” way.

It is important to customize all sections with the same height. Otherwise the buttons (which are on the bottom of the DiaForms) will change the position during the navigation.

Some thoughts to DiaForms

It seems that there are quite a few cases where the forms can be used as dialogs in this way. If using a dedicated entity for it, or using a dedicated form for the same entity, it saves effort to implement an own WebResource. We even get the chance to place subgrids, lookups or PCFs on the DiaForms.

On the other side, it’s not perfect.

There is a border around the whole dialog that is not shown in the standard dialogs (it’s because of the sections). Not very impactful, but still there
We have to take care to the dialog size when we open the dialog: if the form gets too long, the buttons will be visible only after we scroll down
If we try to implement a wizard, we have to take care that the button-position doesn’t change much

In my opinion, the DiaForms are still better than having to implement CanvasApps and use them as Dialogs (license reasons or performance because of the CanvasApps player, could be some considerations). And compared with the implementation of own HTMLWebResource, DiaForms are like a “LowCode” candy. But I’m pretty sure, that this is only a temporary solution. Maybe in the future the Custom Pages will offer a native way of implement this kind of DiaForms. I wonder which name will they have? Looking forward…