PCF Preview Image
Almost every day we see a new control or two developed by the community and available as open source. Controls that are published as open-source are generally developed and published in a really short period of time and lack some of the best practices. My last few posts around PCF were just about that.
How to make our controls better by following simple steps?
This time the topic is preview image that is most of the time first impression about the control when we see it in the controls tab.
Today our general source of PCF controls is PCF Gallery where we can find more than 200 controls that are open source. Most of the controls have some kind of screenshot that shows us the interface of this control. Those images are a great way to get our first impression of the control and can easily make us download it and try it at the end.
More than 80% of the controls out there stick with the preview image that is by default. It's time to change that!
Problem
The problem here is that people don't add some kind of picture to their controls to make them more visually attractive in the first place.
Maybe people are not that responsible for not including the preview image to the control because in the official examples there are no preview images at all. I personally think that those examples are really good in general, but of course, it should be included there at least in one example control that people see it on the road.
Next is that it's not presented in the template so people just skip that part.
Everyone can find it in the official docs but is it's kinda overlooked because it's one of the last parameters mentioned in the control node section.
How to add
Adding it to your control is really simple.
There is a preview-image attribute in the control node that needs to be defined. Prerequisite is, of course, that image is stored somewhere in the control folder so it can be caught by the webpack.
Let's have a look at the example!
// Your files here
The example shows us how we can add a preview.png image that is located in the img folder inside a root control directory. Simply add a preview-image attribute and assign img/preview.png value to it.
Easy as that and you have your preview image added.
Another misconception here is that you need to add it also to the resources node with all the other files. Actually, you don't need to add it there and it will render just fine if you add it just in the control node. The resource node is used only for the images that will be used inside your code.
Model-Driven Apps
Model-Driven App is a place where you will be able to see your preview image.
The preview image can only be seen when you are picking the control for your field/dataset in the form editor.
If you look at the preview image container when you set up your control it feels small and there is a catch in it. That container has fixed size and it will not scale with your image.
Container size is 170 x 130 pixels.
That's the biggest issue with it in my opinion. Why?
You must be really careful when designing the preview image if you don't want to be surprised by the weird shape at the end when you see it in the configuration page.
If you don't keep the 17:13 ratio you will eventually be surprised because the image will stretch in both directions horizontally and vertically to match the size of the container.
The key takeaway here is as long as you keep that strange 17:13 ratio you will have the expected result shown at the end.
The best way to present what your control is capable to do is by using a GIF as a preview image. Yes, it's possible to add it and I strongly encourage you to use it that way because it's really eye-catching to see the control is some action.
Canvas Apps
When it comes to canvas apps it's mentioned in the documentation somehow. A quick look over the Available for column gives you an answer that it's not available for those kinds of apps, but who knows what future will bring.
The other problem with canvas apps is that controls with preview images cause really critical issues while importing to the app.
When you try to import the PCF control that has preview image included it will just fail to import to the app.
I hope that it's just a temporary issue and that it will be fixed soon by the Microsoft guys and until then all you need to do is avoid using the preview images in your control.
Conclusion
Images are a great way of showing the features of the control in a quick and effective way. Saying that let's start including them in our control to help the makers easily choose the right control from the list.
Keep the 17:13 ratio to avoid unnecessary image stretching!
Use GIFs because they the best way of showing the features!
It's a shame that this feature limits our controls only to model-driven apps because of the issue with the canvas apps. If your control is supposed to be used on both types of apps try to include the preview image and comment that code for now, but hopefully, soon you'll be able to uncomment it release it the way it should be done.