Microsoft 365 Community Create Adaptive Card Extensions (ACE) for Microsoft Viva Connections, 11 Jan 2023

Previous Meeting

⏯

youtube image

►

From YouTube: Update the component to display SharePoint list data - Exercise 1

Description

In this video, you'll create an ACE with the Basic Card template that displays items in a SharePoint list and enables the user to add items to the list.

This video is part of a series in a playlist and is associated with a Microsoft Learning module: 'Create Adaptive Card Extensions (ACE) for Microsoft Viva Connections'.

⬅️ Previous video on this series - https://www.youtube.com/watch?v=plIXeRPR92Y&list=PLR9nK3mnD-OUjNKUMsWJwYnRnsmxXojYs
➡️ Next vide on this series - https://www.youtube.com/watch?v=plePKkwZU-c&list=PLR9nK3mnD-OUjNKUMsWJwYnRnsmxXojYs&index=3

Microsoft Learning Module
• Microsoft Learning article - https://learn.microsoft.com/en-us/training/modules/sharepoint-spfx-adaptive-card-extension-card-types/3-exercise-ace-basic-card-rest
• Create Adaptive Card Extensions (ACE) for Microsoft Viva Connections learning module - https://learn.microsoft.com/en-us/training/modules/sharepoint-spfx-adaptive-card-extension-card-types/

Demo Presenter
• Andrew Connell (Voitanos) | @andrewconnell

Supporting materials
• YouTube playlist for this video series - https://www.youtube.com/playlist?list=PLR9nK3mnD-OUjNKUMsWJwYnRnsmxXojYs
• Overview on Viva Connections extensibility - https://aka.ms/viva/connections/extensibility
• Design guidance for Viva Connections cards - https://learn.microsoft.com/en-us/sharepoint/dev/spfx/viva/design/design-intro
• Sample ACEs with code - https://adoption.microsoft.com/en-us/sample-solution-gallery/?product=Viva&sortby=creationDateTime-true

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

Sharing is caring! You are awesome! 🧡

A

Now, let's look at a demo where we're going to create a SharePoint framework, adaptive card extension using the basic card template that displays items in a SharePoint list and enables the user to also add items to that list. Developing adaptive card extensions for Viva connections requires a Microsoft, 365, tenant, SharePoint, online and Viva connections that are all set up in your tenant. You're, also going to need the necessary developer tools installed on your workstation.

A

This includes everything you need for creating SharePoint framework components for the SharePoint framework that includes the Yeoman generator for SharePoint and it all which has two dependencies: the LTS version of node.js, the gulp CLI and Yeoman installed. You can refer to the Microsoft learning module, that's associated with this screencast for links on where you can set up your environment, you're, also going to need a text editor and we'll be using visual studio code.

A

In this example, the first step that we're going to need is to create a new SharePoint list to hold some data that we're going to display in our component. So I'm going to do this by going to my SharePoint site I'm, going to then select, add and create a new list, I'm going to name my blank list. My Ace data.

A

And then I'm just going to add another column to it for a description.

A

Now, once I've created this item on this list, let's add a couple items to it. So we'll just add: let's do this in the grid. View, so we'll just say: item one and the color will be blue. We'll have item two green and then item three will be purple description.

A

Now that I've got some data that I can work with. Let's now go set up a create a project that we can use so I'm going to go ahead and open up vs code and I'm going to jump to a folder where I want to create my project.

A

And I'll jump into that folder.

A

Now, I'm going to run the SharePoint Yeoman generator by executing the following command yo at Microsoft, slash SharePoint. Now when prompted it's going to ask me a couple, questions I'm going to accept the default solution name, but for the client-side component type to create I'm, going to choose an Adaptive card extension and then I'm going to choose the template. I want to use.

A

Is the base card template I'm, going to name my extension SharePoint rest, because what I'm going to do is build an Adaptive card extension that is going to get data from a SharePoint list and display it in the Ace as well as give me the option to create data in the Ace. So I'll go ahead and let this finish now after the Yeoman generator provisioned the folders and the files that are required for the project.

A

It then installed all the dependency packages by running npm install automatically and when npm completed downloading all the dependencies I went ahead and opened up the project in Visual Studio code.

A

Now, let's take a minute and let's explore the default adaptive card extension project experience and understand how the project works. So in the console I'm going to open up a new console here and run gulp serve no browser. What this will do is this will build our project and spin up a local web server. That's going to serve up our adaptive card extension, now I'm, going to jump over to my SharePoint site and let's go ahead and duplicate this and I'm going to go to our hosted workbench.

A

That's at underscore layouts, slash, workbench, dot, aspx in the existing site that we're in so I'm going to go ahead and add the Adaptive card extension by clicking on the plus icon in the toolbar and select my SharePoint rest now, just like a SharePoint framework web part, I can take my mouse and I can hover over it and select the pencil icon to open up the Adaptive card. Extensions property. Pane I can close the property pane by just clicking on this little X in the top right corner.

A

But unlike SharePoint framework, webparts Aces behave a little differently when the page is in edit or display mode So. Currently, the page is in edit mode. I can switch it over to the display mode to interact with it in display mode by clicking on the preview button in this top right corner of the navigation, and this is what my user would see when everything is rendered notice. All the edit tools on the side of the canvas and the ace component. Those are no longer visible, Now.

A

The default view of an ace is the card View and it's selectable and can have. It can contain also contain buttons, the default Ace. If I jump back over to the preview mode, the default Ace is going to open up a link in a new tab. When it's selected, you can see it's just popping up the Bing search engine.

A

This is implemented in a specific file. So let me jump back over to my project and, let's open up the cardview.ts file.

A

So here, if I look at the on card selection method, you can see that what this does. It says that when I, when I click on the card or select the card, it's going to fire this method, which is going to return an object back, which is the action that I want it to perform, and in this case, I wanted to perform the action of external link.

A

And then the parameter I'm passing in is the URL where I wanted to go ahead and what page I want it to open up to Now card views can also contain one two or no buttons. Two buttons are only going to show when the card size is set to large the buttons on a card view are implemented using the card actions method that you see here. This method can return one or two buttons and then the object.

A

That's returned by this method determines what happens when the button is selected so like, for example, in the Project's default code, you notice that it's opening up a quick view. So it's open, the action says open up a quick view and the parameter I'm passing in the view is pointing to the quick view ID that I want it to open and I can see it.

A

If I come back over to the browser, if I click this button, you can see the quick view is opening up now, quick views are implemented using two files and registering it with the ace component. The rendering of the quick view is defined in a Json file that you see right here in this template in this template subfolder.

A

This contains the definition of an Adaptive card and the Json file for the default. Project's quick view is what you see here: notice that I have a text block showing up at the top and then I've got a column set that just has a single column listed of a single item. That says is just the title or the subtitle of the item of the current adaptive card. So this is one objects being passed in and there's another object, that's being passed in this is using the templating capability.

A

We have in adaptive card extensions, so we can see the titles being rendered at the at first there's the title called SharePoint rest, which is also in the card View, and then the subtitle is not being shown here because we're going to pass in a different value when we in the and the data and one of the methods, it's going to return. That back. We'll look at that in just a few minutes now the quick view is actually defined. The one that we're looking at here is defined in this quickview.ts file.

A

So let's take a look at this. This file gives the SharePoint framework the Json for the Adaptive car, that's used in the rendering, and you can see that here from the template method, it's pointing to that specific Json file or the contents of that Json file, which are read in when I call the required method, all card views and quick views. They must be registered with their respective Navigators in the Ace component, and this is typically implemented using the on init method in the Ace component.

A

So if I go over to my adaptive card extension, which is right here in the Adaptive card extension file, what you can see here is I've got my two IDs, that I'm defining one for the card View and one for the quick view and then inside of the on init method. For my adaptive card extension I'm, then registering those two views and I'm doing that within the on a net. Now, I want to take this project, make it a little more Dynamic where I can read and write data to a SharePoint list.

A

So, let's add a SharePoint rest service to the project. This can handle all reading and writing to the SharePoint list that I've just created so I'm going to go into my um SharePoint rest folder right here and create a new file called SP service, dot, TS and just paste in some code. Now this code's got a few methods here.

A

I've got an interface that I'm defining at the very top, so one called I list item and then I've got a method, I'm returning called Fetch list title and then another method that I'm going to return, called Fetch list items and then I have a couple. Other ones I'm going to use a little bit later, one for adding a list item and then one for getting an entity. Id we're just pasting this in because reading and writing to a SharePoint list has there's nothing unique about it.

A

When it comes to working with an adapter card extension you're going to use all the same Concepts and capabilities that we have and requirements that we have when I'm working with any other kind of um component inside the SharePoint framework.

A

Now that the project has some core dependencies that have been added, let's now implement the initialization of some core features when the Adaptive card extension is going to first load on the page- and this involves configuring, the state of the ace and enabling the user to set the ID of the SharePoint list to read and write uh from and two so I'm first going to go through and update the Adaptive card extension to enable the user to set the SharePoint list, ID.

A

So I'm going to do that by coming over to the Adaptive card extension and end the interface for the extension I'm going to go to the list, ID and I'm, going to go to the interface and add in a new property called list. Id now I'm next going to go over to our property, paying class.

A

So if I scroll down a little bit, you can see that when my I go get the property paying configuration, I'm getting um I'm going to be returning back, a method called get property, paying configuration it's coming from this deferred property Pane and if I scroll up. You can see that my private member here called deferred property pane, is of type SharePoint, rest property, Pane and that's defined right here in this file. Sharepoint rest property pane.

A

So what I'm going to do is I'm going to add in another property here, and this is going to be set to the list ID and the label, for it will be set to list ID. Do it when I set the list, ID I'm going to want to go fetch all the items out of the SharePoint list. So let's go set up a little placeholder method that we're going to update in a little bit.

A

So what I'm going to do is add a new method here or a new event handler here called on property, own property, paying field changed, and what this does is that the SharePoint framework is going to raise this event when the value of a property in the property pane changes, we're going to come back and we're going to update this method in a little bit later. Now. The next thing I need to do is I need to update the state of the Adaptive card extension and the initial view.

A

So what I'm going to do is come up to the top here and, let's add in an import statement.

A

And we're going to want to import from our SharePoint list service, so we want to pull in the fetch title, the fetch items and the I list item as well. Now we're getting some warnings here because we're not using any of these and that's okay, we'll come back to that in just a little bit now, if I come down here to the state, let's go set a few things: I want to set a state property for the title of the list.

A

I'm going to want to set one for the items in the list.

A

And the current index in the list I'm going to initialize the state property in the existing on init method and I'm, going to do that by replacing my existing state uh assignment here. The reason for that is because this object no longer represents what a state looks like.

A

So what I'm going to do is I'm going to set the current index equal to zero? The list title is going to be equal to an empty string and the list items is going to be equal to nothing. Now the current index we're going to use this to kind of cycle through all the items we get back from the SharePoint list and know which one we're supposed to be looking at uh in the card view or in the quick view we're going to do that in a little bit now.

A

The next thing I want to do is I'm going to want to add in some code um before we complete the initialization to go, try and fetch the values out of our SharePoint list. If we have a list, ID so I'll say if the properties, if the property on our adaptive card extension list ID. If it's set, then what I'm going to do is I want to go. Do two things: I'm going to go, run I want to run two methods, they're, both asynchronous and so to make sure that this is asynchronous.

A

I'll have to set this up to add the async keyword to use my promises here and what I'm going to do is I'm going to say, I'm, going to call this dot set, State equal to and I'm going to set the list title uh equal to a weight, the fetch list, title method and I'm going to pass in the context of the current um the page context, which is how I'm going to get a reference to the uh SharePoint HTTP client that the SharePoint framework has to be able to make my call to the SharePoint rest, API and then I'm also going to pass in.

A

The list ID in fact I'll just make this I'll put all this on one line like this and then I'm. Basically, I want to do the exact same thing, but instead of for the list, title I want to set it for the items on the list and I'm going to say fetch the list items and pass in the exact same value.

A

Okay. So now, when my component initializes, it's going to start by initializing this, the the state to nothing I'm going to register my two card views, my card View and my quick view, and then, if I've got the list, ID set I'm going to want to go, update um the go fetch the title of the list and go fetch the state of the list as well.

A

So now, all the public properties in the state are all configured for the ace component. I need to handle one more case, such as when the user updates the list ID property in the property pane. So what I'm going to do is come back down to that method that we created earlier.

A

In fact, I'm going to go grab these two lines here. The set State we're going to use those in a second and what I'm going to do is I'm checking to see if the list ID is the property that was updated and if it was then what I want to check to see is if I have a new value, that's divine.

A

Then what I'm going to do is I want to run a I'm going to run my async methods, so I'm going to do that by wrapping them up in this iffy and I'll just paste them in like this and then otherwise I'm going to want to set those two State values.

A

Actually, I don't need to do it for both of them, like this I'll just say like list title is going to be nothing and the list items will be set to an empty string or an empty array that, like that, and we don't need to close our if State RL statement. So at this point our Ace component is rendering is reading the title and the items in the SharePoint list. So the last step to be able to see this work is to display the information that it's going to render.

A

So let's do this by coming over to our card View and I'm, going to make some changes to our card View. So I want to update the existing data method right here to do some additional things with this. So how am I going to do this? Well, what I want to do is I'm going to change the title of our of our card View instead of it showing um I'll leave.

A

Actually I'll leave the title the same, but for the for the primary text I'm going to want to change this I want to say um check to see. Is the state list title? Is this defined and if it is then I want to say view items in the let's just write out the title, this dot state DOT list title.

A

List otherwise, if it's not then I'm going to say I'm missing the list, I'm missing the list ID, so you have to go through and specify uh the list ID as in the property pane, so that my user has a little bit of context on what they're supposed to do now in the card selection method. I'm going to change this to go, launch a quick view instead of what I'm currently doing so the way I'm going to do.

A

This is I'm going to set this to a quick view and I'm going to pass in The View parameter of a quick view. Registry right here, that's being imported so at the top here, I'm actually importing this um kind of hard to see without this wrapping. But let's get so let's go fix that there we go so what you can see here is I'm pulling in the quick view ID from our component. That is where it was being registered now.

A

The last thing I want to do is because I'm not I, don't think I'm using the strings anywhere. I guess I'm using it right here right now, um yeah! So we'll just leave this, as is now that we've done this. Let's go update our adaptive card for the quick view to display the data from the SharePoint list as some sort of a carousel, so I'm going to come over here to my quick view.

A

Actually, let's go to the Json template and what I'm going to do is I'm, going to replace everything in this with some uh different Json with some different code here, and so what I'm going to do here is I'm, going to set up in a column, set I'm going to display an image so I'm going to have like a a previous and next image on either side. So this is just um a um an SVG image that is a vector graphic.

A

That's going to have like an arrow pointing to the left and then for a previous button or there you go previous button and then I'll have one a little bit farther down for pointing to the right. So that's just a different image. Both of these you can see are both set to when they're selected I'm actually going to call the action.submit and set the ID to one.

A

What that's going to do is I'm going to use that number as a way to increment the current index of the item I'm looking at and when I go previous I'm going to come back over here and just use the negative one to go back one item in my index and that current index we're going to keep track of notice.

A

Also I've got this property here called, is visible I'm setting it to be bound to a a property called previous enabled and then farther down I'm going to check to see if next is enabled, because, if I'm at the beginning of my array, there should not be a previous button and if I'm, at the end of the collection of all the items, I've retrieved, there should not be a next button. We're not going to do like a wrap around kind of a capability here and then in the main part of my card.

A

Here you can see where I'm writing out the ID and the title of the SharePoint list item and the description of the SharePoint list item as well. So now that I've got the rendering defined I now need to go update the class that defines my quick view so I'm going to go first up to the top and update my import statement.

A

So one of the first things I'm going to need I need to break these up on separate lines to make it easier to read this. What I'm going to need is an I actions, arguments that are passed in and then I'm also going to need a reference.

A

To my interface for a list item, okay, now that we have both of those the next thing I want to do, is I'm going to want to go through and Define the data, that's going to be returned back to the um or used to bind uh to my adaptive card. So if you recall, we've got a title and a description of the ID property.

A

Well, all those are defined on my list items so I'm just going to have this extend my I list item then next up I want to go through and add in a couple properties here, take away the subtitle in the title, because we're not using those anymore, but what I do want to do is I want to have my previous enabled property and.

A

My next enabled property, because what that's going to do is those are the two buttons I was talking about earlier now. The next thing I need to do is update the data method, because the data method is what's going to return. The currently selected item, that's retrieved from the SharePoint list and those two properties to the Adaptive card, rendering engine and the properties on this object are going to be bound to those specific elements in the Adaptive card, template that I just referenced.

A

So what I'm going to do in here in this return statement, I'm going to set the previous enabled and I'm getting the intellisense, because I'm, inheriting from my interface that I Define that implements the ilist item so I'm going to set this equal to the this dot State and one thing I get access to is the entire state of the component, which I defined in my adaptive card extension?

A

And you remember, we had one called current index so I'm going to set the previous enabled his a Boolean property I'm set to be equal to if it's equal to zero. So if the current index is equal to zero, then that means we're at the beginning of the the collection of items and I don't want to have a previous button enabled for the next enabled the condition is a little bit different I'm going to want to check to see if the current index is not equal to the list items length, minus 1.

A

and then finally, I'm also going to add an extra comma there. Finally, the last thing I want to do is I'm just going to want to add all the properties on my on the current item in the array that we're on using that current index, so I say this dot state dot list items this dot, State DOT current index just like that. Oh this should be length there. We go now.

A

Let's add in a new method at the end of our component, and what this is going to be is our on action method, because what this is going to do is this is going to define something that happens when a submit action happens. If you remember, we have two submit actions. We have one for going to the previous uh item in the in the collection and one going to the next item in the collection.

A

So here what I'm doing is I'm getting a reference to the current index and I'm just going to take the current index, use the current index and I'm just going to convert the string that was in that ID property for our action I'm going to convert that to a number, and if you recall that ID the actions ID that's going to be either a negative one or a positive one, to indicate we're going forward or backward now. In this case, we should be able to test out our component okay.

A

So what we need to do is we need to stop our web server and then restart it to get everything, make sure that everything gets built and displayed and I saw an error pop up a second ago, and this one is uh strings declared, never using our quick views. Let's come back over to our quick view and that's right. We stop we're no longer using our Dynamic string.

A

So we'll just remove this from our method and let's go back over to the browser and let's remove the existing web part, that's on the page or adaptive card extension. That's on the page. I will then go back and re-add it and notice here we're now seeing we don't have a list ID, so I need to go through and paste in the list. Id. So I'm, going to put this in edit mode I need to go fetch. My list, ID I, can do that by coming back over to my list.

A

Let's go to our list settings page and in the URL we can see where we have a list, and that starts right after the percent 7B and goes all the way up to the percent 7D, because that is a URL encoded good with the curly brackets on either side of it.

A

So I'm going to grab the ID for my list and we'll paste it in there we go and we can see that we made a call to the SharePoint rest API, because it whenever this property changed, we actually went and got the item or the the title for our SharePoint list. So now, if I put this into display mode, I should be able to select it and there we can see. We can see our item. One item two. So the item three.

A

So there's our three items that we have listed here in our SharePoint list that we're just going back and forth through and we're triggering this because we're using the on item selected. We are, you can see that we still have our button here for displaying the same things we're using the we're using the button to display the same information. But um that's not really all that important right here now.

A

The next thing I want to do is I want to add a new quick view to the items uh to um the SharePoint list, and this is going to give us show us how to demonstrate how we can use the quick view to collect data from a form. So what I'm going to do is come back over to my my project and we'll stop the um the web server and I'm going to add in a new file to my project.

A

This is going to be a brand new, quick view, so I'll go to the quick view, folder and say new file and it'll, be the new item, quick view and let's just go ahead and let's paste in some code. So what does this have so this code here I've got a data method. That's going to return nothing because we're not going to pass any data back to this one. The template we're going to create that in just a minute.

A

So let's go through and get ready to create that copy that that the file name and then I have an on action method in there as well. You'll notice that the on action method, what it does is, it gets some information uh from the input controls that are passed in so I'm. Doing that like right here with the title and description that are passed in I'm, also using the data property and then I'm going to go.

A

Save the item by just calling add add list item then, once that happens, I'm then going to refresh the state to go, get all the items in the SharePoint list, which will include the one that I just added as well as any other ones that someone else has added during this time and then I'm just going to close out my quick view. Navigator. So now, I'll come over here to my template.

A

Let's add in the Json file that we're going to need to implement the form I'll just save my changes there and then to be able to use this I need to go back in red. I need to register this with my um quick view, Navigator, so I'm going to do that by coming back over to the page here, I'm going to say we're going to go over to our extension I'm going to import the quick view navigator that we just created I'm then going to come down and we'll add in a new export statement.

A

So I'll put that right here. So this is basically just giving us a ID for our new item, quick view that we're creating and then the last step is going to be to then register it so I'll do that right here.

A

Just like this.

A

Now the last thing we want to do now that we've now we've registered our quick view is I want to change the card view so that the card view will be able to import this or be able to use this when someone clicks the button, instead of just when they click the actual card, so I'm going to do that by coming back over here and we're going to import our new quick item registry and then I'll add in the view that we want to load using our quick view here.

A

Actually, I only want to show this. Let's, let's change this up a little bit, I want to say actually we'll just let's change the quick view here on strings, we'll, say, add: item now that I don't think we're using yeah we're not using strings anymore, so we're going to remove that strings reference, and what I want to do here is I want to say if this dot properties dot list ID, if that's not defined, then I want to return undefined, so no buttons show up otherwise.

A

I want to there we go. Do it like that? Okay now! So, let's now test this out so I'm going to rerun my the web server and everything range is fine. So now we're going to refresh the page okay, so we got our items we'll go into display mode. Now we see our our add item button that we changed it to when I select it I've got new items. So this is I, think item four and another color will be um black description like that. I'll save my changes.

A

If I go back to my SharePoint list, let's just confirm that we actually uh have our data sure enough. We just got a new item that just got created and now, if I go back and select, my adaptive card I should have item number four showing up as the black description item. So in this demo you we, you saw how we had created a SharePoint framework, adaptive card extension with the basic card template that displayed items in a SharePoint list and enabled the user to add items to the list using a quick view.