Here you can find the transcript of Episode #134 of PiaSys TechBites.

Welcome back to PiaSys Tech Bites. Today, I want to talk with you about how you can leverage the Adaptive Cards technology in your custom developed solutions. The Adaptive Card, a technology by Microsoft, which allow us to create really effective, and user-friendly UI components and elements, which can be made of content and actions, and which are based on a JSON Reference schema.

With an Adaptive Card, we can create the content of a message sent by a BOT in Microsoft Teams, for example, or the content of a message sent by a message sent by a Microsoft 365 Connector or a message in the Teams chat, as well as the content of a SharePoint Framework component or web part, or the content of a message that we send through email. For example, a message with some actions to execute, which will be part of a flow defined in Power Automate, just to make a few examples.

Today, I want to explain you how you can use the Adaptive Cards to render the UI of a SharePoint Framework web part. We will use an SDK, the Adaptive Card SDK, which is available as an NPM package, and we will see that we can also subscribe to events in order to handle the actions defined in an Adaptive Card using TypeScript code like we do for events in any other React component that we have in the UI of our SharePoint Framework web parts and components. So, let me move to the new environment and let me show you how to do that in practice.

In order to work with the Adaptive Cards, first of all, you should go to the adaptivecards.io website provided by Microsoft, where you can find a definition of what Adaptive Cards are. You can find a reference to the official documentation, as well as to the Schema Explorer, to better understand how the JSON schema works. You will have access to some samples and some blog posts, as well as to the designer that we can use to design Adaptive Cards using a web-based UI to design them.

Just to give an eye to the documentation, we can see that we have a reference to all of the SDKs provided. In order to render Adaptive Card, we can use the JavaScript SDK, which is exactly the one I’m going to use in the demo that I’m going to show you. In the designer, you can see an out-of-the-box, ready to go, pre-designed card, which will be provided as a sample. But of course, you can use this designer to render your own JSON content here. You can use the web-based designer and you can leverage all of the elements meaning the containers, the actual content elements like TextBlock, RichTextBlocks, Image, Media, and ActionSet, as well as the Inputs if you want to collect the data from the user.

The user can then use actions like these buttons to provide feedback back to your own service. Through this designer, you can also see what the outline of your card is using this preview, as well as you can play with sample data that you can bind to the actual JSON content and defining the Adaptive Card. So, for example, if I click on Preview mode, we can see here the output of the card that we see in the definition right here in the JSON.

Now, we can also play, of course, with custom cards that we can define. Just to make an example here, I have a JSON file, which defines a sample Adaptive Card that I’m going to use in my demo. If I switch back to the Adaptive Card Designer, that will use the JSON of this card, we can see that we have the image of our PnP Parker, as well as a couple of actions: one to send the data and want to go to the PnP side. As you can see, the actions will be of type Action.Submit or Action.OpenUrl and I will have to provide the URL that I want to open by clicking on the Action.OpenUrl action that I have in my Adaptive Card.

So, let’s imagine that we want to use this card as the content of a SharePoint Framework web part. So, first of all, let me show you the output in the workbench, so I cannot my web part: Render Adaptive Card. I can click on this button to configure my web part and I can browse for a file. Of course, it will be the JSON file that I just showed you, so this one. I can open the file and we can see the output rendered in the UI of the SharePoint Framework web part. We can send data and using TypeScript, we can intercept the action of sending data, as well as we can open a URL in a different tab by handling the click event of the Go to PnP action that we have in our Adaptive Card. So, how can we do that in SharePoint Framework?

First of all, I included a reference to Adaptive Card SDK using npm in my solution. Then, we have a really common SharePoint Framework web part based on a React component. In fact, in our React component, we’ll simply render the web part using an external React component, which is this one, the RenderAdaptiveCard.tsx. In this component, we simply use the SDK to load the JSON content from a file stored in SharePoint Online.

It doesn’t really matter how we load the JSON file from SharePoint. This is a topic related to PnPjs and I don’t want to dig into that one right now, but I’m using the SDK of the Adaptive Cards and I simply create a new Adaptive Card object in the Adaptive Card namespace. Then, I configure the Adaptive Card to support such kind of settings and functionalities that I can configure using this object to setup my hosting environment for my Adaptive Card.

And then I can simply say, “Okay, whenever there will be the execution of an action, please rely on this handleCardActions method that I have in my TypeScript code.” Then I parse the content of the card that I loaded from the JSON file in my SharePoint Online document library, and I say render to the AdaptiveCard, so that the renderedCard will become the content that I will simply append to a div element that I have in the output content of my React component. And as such, in the content, I will render the actual UI of my Adaptive Card.

The handleCardActions method is just a method which will get an action as an input argument. And in the action, we have a propertyBag where we can see the type of the action. So, we can define if the action is a Submit action or an OpenUrl action, or whatever else. Based on the properties of the action, we can execute and we can handle the requested action requested by the user.

So, really simple and straightforward, but the overall solution is quite nice because you can leverage the Adaptive Cards in the UI of your SharePoint Framework work part and you can also eventually use input fields to collect information from the user using the already provided UI of Adaptive Cards provided by Microsoft with the whole set of capabilities of the Adaptive Cards.

Like always, thank you for watching this video. I hope you enjoyed it. Let me wish you a very Merry Christmas. Remember, subscribe to this channel. Thank you.