Getting started with ACE in SPFx

What is ACE?

• ACE stands for Adaptive card extension.
• Adaptive Card Extensions (ACEs) are a new SharePoint Framework component type that is provided in SPFx from version 1.13.
• Adaptive cards are simple JSON objects which will render the UI in a consistent and direct way on all the devices as it is portable and automatically styled.
• We can render it on multiple platforms with different screen sizes and devices.

For more details refer to this article.

Prerequisites:

• Node - v14 or v12
• SPFx version - 1.13 and onwards

How to create ACE:

1. Create a directory where you want to create a project.

md ACE_SPFx

 2. Move to the directory

cd ACE_SPFx

3. Now we have to execute the below command:

yo @microsoft/sharepoint

4. It will ask configuration questions as below so you can set it up as your requirement.

Note: In the component types question when you select Adaptive card extensions, it will provide 3 options.

After the successful creation of the project, you can use any code editor to modify your code. Here I am using VS code so will execute the below command to open the project.

code .

Project Structure:

After you will open your code in any editor your src folder structure will be looks like the below,

Let's see the importance of some files:

assets We can add some assets like images and then we can use them for our web part.

loc localizing it for different languages

BasicCardAceAdaptiveCardExtension.ts Export and declare card view, register it, and render card view.

BasicCardAcePropertyPane.ts Configurations for property pane.

cardView/CardView.ts

Which renders on Dashboard. 

Available methods are cardButtons, data, and onCardSelection.

quickView/QuickView.ts

Quick view will open a popup to display the quick view component.

quickView/template/QuickViewTemplate.json It renders data in quick view and for this, we have to use JSON.

Render ACE

The virtual renderCard() method returns the string identifier to the registered view. This method is invoked during the initial render of the Card view.

protected renderCard(): string | undefined {
    return CARD_VIEW_REGISTRY_ID;
}

Register View for ACE

• The view must be registered within a constructor or onInit() before we use it.
• To use views, it must be registered with its respective ViewNavigator.
• Two ViewNavigators are exposed on the ACE: cardNavigator and quickViewNavigator.

public onInit(): Promise<void> {
    this.state = { };

    this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
    this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());

    return Promise.resolve();
}

Types of View:

Let's see more about the card and quick views.

Quick view

• Can have image, form, text, button, and so on.
• We can create multiple quick views like rendering data, error handling, and so on.
• Quick views extend the BaseAdaptiveCardView base class.

• There are three optional generics that can be defined:

  • TData: The type returned from the data() getter method.

  • TProperties: Similar to the Card view, this is the same interface used by persisted properties of the ACE (a property bag).
    TState Similar to the Card view, this is the set of stateful data the View needs to render. TState must share properties with the ACE's state interface.

Card View

• Three views and two sizes.
• The card views for Adaptive Card templates are fixed and cannot be changed.
• Can have a single card view. 

• There are two generics for the properties and state objects shared between the view and the ACE.

  • TProperties: The View's properties interface, is the same interface used by persisted properties of the ACE (a property bag).

  • TState: Unique to ACEs and can optionally define the set of renderable data.

• data() -  The data getter is the only method that must be implemented by a Card view.

• cardButtons - This property determines the number of buttons that appear on the Card and actions to perform when clicked.

• onCardSelection -This method determines what will happen when the Card is clicked.

Types of card view:

• Basic card template:
  • It extends from the BaseBasicCardView base class.
  • It manages the primary text, Title, and Icon configuration.

• Image card template:

  • It extends from the BaseImageCardView base class.

  • It manages the primary text, Title, Icon, and Image configuration.

• Primary card template:

  • It extends from the BasePrimaryTextCardView base class.

  • It Manages the primary text, Title, Description, and Icon configuration.

Execution:

Update the initial page property within the ./config/serve.json to point to your SharePoint Online tenant.

And then execute the below command,

gulp serve

this command will open the page that we have used in initialPageon the localhost server to verify the ACE.

Deployment: 

If the project is working properly on a local server without any error, We can deploy it on the app catalog. We can deploy it using the following two commands.

gulp bundle --ship

gulp package-solution --ship

After successful execution of the above commands, it will create a .sppkg file to sharepoint/solution. Now add the package file to the app catalog.

Then move to the communication site.

Setup viva connection if you haven't done it.

Or you can directly move to the /SitePages/Dashboard.aspx and add ACE.

References:

Build your first SharePoint Adaptive Card Extension 

Advanced Card View Functionality 

Advanced Quick View Functionality 

Summary

In this article, we have seen what is ACE, How to create ACE, the importance of files, types of views, render and register ACE, and different card templates.

I hope this helps, if this helps you then share it with others.

Sharing is caring!