This template showcases an app that embeds a canvas containing multiple cards that provide an overview of content in Microsoft Teams. Start with this template you can:
- Use widgets to display content from apps and services within your dashboard tab.
- Integrate your app with Graph API to visualize details about the implementation of the selected data.
- Create customizable dashboards that allow your business to set specific goals that help you track the information you need to view in multiple areas and across departments
Prerequisites To run the dashboard template in your local dev machine, you will need:
- Node.js, supported versions: 16, 18
- A Microsoft 365 account for development
- Set up your dev environment for extending Teams apps across Microsoft 365 Please note that after you enrolled your developer tenant in Office 365 Target Release, it may take couple days for the enrollment to take effect.
- Teams Toolkit Visual Studio Code Extension version 5.0.0 and higher or Teams Toolkit CLI
- First, select the Teams Toolkit icon on the left in the VS Code toolbar.
- In the Account section, sign in with your Microsoft 365 account if you haven't already.
- Press F5 to start debugging which launches your app in Teams using a web browser. Select
Debug in Teams (Edge)
orDebug in Teams (Chrome)
. - When Teams launches in the browser, select the Add button in the dialog to install your app to Teams.
Congratulations! You are running an application that can now show a dashboard in Teams:
Folder | Contents |
---|---|
.vscode |
VSCode files for debugging |
appPackage |
Templates for the Teams application manifest |
env |
Environment files |
infra |
Templates for provisioning Azure resources |
src |
The source code for the dashboard Teams application |
The following files can be customized and demonstrate an example implementation to get you started.
File | Contents |
---|---|
src/services/chartService.js |
A data retrieve implementation for the chart widget |
src/services/listService.js |
A data retrieve implementation for the list widget |
src/dashboards/SampleDashboard.jsx |
A sample dashboard layout implementation |
src/styles/ChartWidget.css |
The chart widget style file |
src/styles/ListWidget.css |
The list widget style file |
src/widgets/ChartWidget.jsx |
A widget implementation that can display a chart |
src/widgets/ListWidget.jsx |
A widget implementation that can display a list |
src/App.css |
The style of application route |
src/App.jsx |
Application route |
The following are project-related files. You generally will not need to customize these files.
File | Contents |
---|---|
src/index.css |
The style of application entry point |
src/index.jsx |
Application entry point |
src/internal/context.jsx |
TeamsFx Context |
The following are Teams Toolkit specific project files. You can visit a complete guide on Github to understand how Teams Toolkit works.
File | Contents |
---|---|
teamsapp.yml |
This is the main Teams Toolkit project file. The project file defines two primary things: Properties and configuration Stage definitions. |
teamsapp.local.yml |
This overrides teamsapp.yml with actions that enable local execution and debugging. |
Follow the steps below to add a new widget to the dashboard:
- Step 1: Create a data retrive service
- Step 2: Create a widget file
- Step 3: Add the widget to the dashboard
Typically, a widget requires a service to retrieve the necessary data for displaying its content. This service can either fetch static data from a predefined source or retrieve dynamic data from a backend service or API.
For instance, we will implement a service that returns static data and place it under the src/services
directory.
Here is a sample service for retrieving static data:
//sampleService.js
export const getSampleData = () => {
return { content: "Hello world!" };
};
Create a widget file in the src/widgets
folder. Inherit the BaseWidget
class from @microsoft/teamsfx-react
. The following table lists the methods that you can override to customize your widget.
Methods | Function |
---|---|
getData() |
This method is used to get the data for the widget. You can implement it to get data from the backend service or from the Microsoft Graph API |
header() |
Customize the content of the widget header |
body() |
Customize the content of the widget body |
footer() |
Customize the content of the widget footer |
styling() |
Customize the widget style |
All method overrides are optional.
Here's a sample widget implementation:
//SampleWidget.jsx
import { Button, Text } from "@fluentui/react-components";
import { BaseWidget } from "@microsoft/teamsfx-react";
import { getSampleData } from "../services/sampleService";
export class SampleWidget extends BaseWidget {
async getData() {
return getSampleData();
}
header() {
return <Text>Sample Widget</Text>;
}
body() {
return <div>{this.state.data?.content}</div>;
}
footer() {
return <Button>View Details</Button>;
}
}
Open the src/dashboards/SampleDashboard.jsx
file and add the widget to the implementation of the layout
method. If you want to create a new dashboard, please refer to How to add a new dashboard.
layout() {
return (
<>
<ListWidget />
<ChartWidget />
<SampleWidget />
</>
);
}
Optional: If you want to arrange multiple widgets in the same column, you can refer to the following code snippet:
.one-column {
display: grid;
gap: 20px;
grid-template-rows: 1fr 1fr;
}
layout() {
return (
<>
<ListWidget />
<div className="one-column">
<ChartWidget />
<SampleWidget />
</div>
</>
);
}
Congratulations, you've just added your own widget! To learn more about the dashboard template, visit the documentation. You can find more scenarios like:
- Customize the widget
- Customize the dashboard layout
- Create a data loader
- Refresh data based on the schedule
- Handle empty state
- Add a new dashboard
- Use Microsoft Graph Toolkit as widget content
- Embed Power BI to dashboard
- How to add a new Graph API call
- Enable the app for multi-tenant
- Preview the app on mobile clients