Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/huimiu/simplify-dashboard-template
https://github.com/huimiu/simplify-dashboard-template
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/huimiu/simplify-dashboard-template
- Owner: huimiu
- License: mit
- Created: 2023-04-06T08:42:05.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-09-02T05:16:24.000Z (over 1 year ago)
- Last Synced: 2023-09-03T06:45:20.076Z (over 1 year ago)
- Language: TypeScript
- Size: 296 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Overview
This repository designed to assist developers in quickly building a Teams dashboard tab application using the TeamsFx SDK.
# Introduction
This is a Teams tab app that uses the [Fluent UI](https://react.fluentui.dev/?path=/docs/concepts-introduction--page) to display multiple cards that provide an overview of data or content in Microsoft Teams.
When you open this app in mobile Teams, it will automatically switch to a mobile-friendly layout.
# Getting Started
### Prerequisites
- [NodeJS](https://nodejs.org/en/), fully tested on NodeJS 14, 16, 18
- A Microsoft 365 account. If you do not have Microsoft 365 account, apply one from [Microsoft 365 developer program](https://developer.microsoft.com/en-us/microsoft-365/dev-program)
- [Teams Toolkit Visual Studio Code Extension](https://aka.ms/teams-toolkit) or [TeamsFx CLI](https://aka.ms/teamsfx-cli). If you are using Teams Toolkit Visual Studio Code Extension, please make sure you have installed the pre-release version, you can switch to pre-release version by clicking the switch button in the Teams Toolkit VS Code extension page, or you can install the pre-release version from [here](https://marketplace.visualstudio.com/_apis/public/gallery/publishers/TeamsDevApp/vsextensions/ms-teams-vscode-extension/4.99.2023022208/vspackage).
### Try it out
Run your app with local debugging by pressing `F5` in VSCode. Select `Debug (Edge)` or `Debug (Chrome)`.
# Understanding the Code
This section walks through the generated code. The project folder contains the following:
| 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 provide the business logic for the dashboard tab. These files can be updated to fit your business logic requirements. The default implementation provides a starting point to help you get started.
| File | Contents |
| ------------------------------------------- | ------------------------------------------------- |
| `src/components/sample/listService.ts` | A data retrive implementation for the list widget |
| `src/components/sample/ListWidget.css` | The list widget style file |
| `src/components/sample/SampleDashboard.tsx` | A sample dashboard layout implementation |
| `src/widgets/ListWidget.tsx` | A widget implementation that can display a list |
The following files are project-related files. You generally will not need to customize these files.
| File | Contents |
| ------------------------- | ---------------------------------- |
| `src/index.css` | Application entry point style file |
| `src/index.tsx` | Application entry point |
| `src/components/App.tsx` | Application route |
| `src/internal/context.ts` | TeamsFx Context |
# How to Add a New Widget
You can use the following steps to add a new widget to the dashboard:
1. [Step 1: Create a widget file](#step-1-create-a-widget-file)
1. [Step 2: Add the widget to the dashboard](#step-2-add-the-widget-to-the-dashboard)
### Step 1: Define a data model
Define a data model based on the business scenario, and put it in `src/models` folder. The widget model defined according to the data you want to display in the widget. Here's a sample data model:
```typescript
export interface SampleModel {
content: string;
}
```
### Step 2: Create a data retrive service
Simplely, you can create a service that returns dummy data. We recommend that you put data files in the `src/data` folder, and put data retrive services in the `src/services` folder.
Here's a sample json file that contains dummy data:
```json
{
"content": "Hello world!"
}
```
Here's a dummy data retrive service:
```typescript
import { SampleModel } from "../models/sampleModel";
import SampleData from "../data/SampleData.json";
export const getSampleData = (): SampleModel => SampleData;
```
> Note: You can also implement a service to retrieve data from the backend service or from the Microsoft Graph API.
### Step 3: Create a widget file
Create a widget file in `src/widgets` folder. Inherit the `BaseWidget` class from [@microsoft/teamsfx-react](https://www.npmjs.com/package/@microsoft/teamsfx-react/v/3.0.1-alpha.ru6q1vrv0.0). 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 methods are optional. If you do not override any method, the default widget layout will be used.
Here's a sample widget implementation:
```tsx
import { Button, Text } from "@fluentui/react-components";
import { BaseWidget } from "@microsoft/teamsfx-react";
import { SampleModel } from "../models/sampleModel";
import { getSampleData } from "../services/sampleService";
interface SampleWidgetState {
data?: SampleModel;
}
export class SampleWidget extends BaseWidget {
async getData(): Promise {
return { data: getSampleData() };
}
header(): JSX.Element | undefined {
return Sample Widget;
}
body(): JSX.Element | undefined {
return
{this.state.data?.content};
}
footer(): JSX.Element | undefined {
return View Details;
}
}
```
### Step 4: Add the widget to the dashboard
1. Go to `src/dashboards/SampleDashboard.tsx`, if you want create a new dashboard, please refer to [How to add a new dashboard](#how-to-add-a-new-dashboard).
2. Update your `layout()` method to add the widget to the dashboard:
```tsx
protected layout(): JSX.Element | undefined {
return (
<>
>
);
}
```
> Note: If you want put your widget in a column, you can refer to the following code:
```tsx
const oneColumn = mergeStyles({
display: "grid",
gap: "20px",
gridTemplateRows: "1fr 1fr",
});
protected dashboardLayout(): JSX.Element | undefined {
return (
<>
>
);
}
```
# How to add a new dashboard
You can use the following steps to add a new dashboard layout:
1. [Step 1: Create a dashboard class](#step-1-create-a-dashboard-class)
2. [Step 2: Override methods to customize dashboard layout](#step-2-override-methods-to-customize-dashboard-layout)
3. [Step 3: Add a route for the new dashboard](#step-3-add-a-route-for-the-new-dashboard)
4. [Step 4: Modify manifest to add a new dashboard tab](#step-4-modify-manifest-to-add-a-new-dashboard-tab)
### Step 1: Create a dashboard class
Create a file with the extension `.tsx` for your dashboard in the `src/dashboards` directory, for example, `YourDashboard.tsx`. Then, define a class that inherits the `BaseDashboard` class from [@microsoft/teamsfx-react](https://www.npmjs.com/package/@microsoft/teamsfx-react/v/3.0.1-alpha.ru6q1vrv0.0).
```tsx
export default class YourDashboard extends BaseDashboard {}
```
### Step 2: Override methods to customize dashboard layout
The `BaseDashboard` class provides some methods that you can override to customize the dashboard layout. The following table lists the methods that you can override.
| Methods | Function |
| ----------- | ------------------------------------ |
| `styling()` | Customize the style of the dashboard |
| `layout()` | Define widgets layout |
Here is an example to customize the dashboard layout.
```tsx
import { mergeStyles } from "@fluentui/react";
import { BaseDashboard } from "@microsoft/teamsfx-react";
import ListWidget from "../widgets/ListWidget";
import ChartWidget from "../widgets/ChartWidget";
export default class YourDashboard extends BaseDashboard {
protected styling(): string {
return mergeStyles({
gridTemplateColumns: "4fr 6fr",
});
}
protected layout(): JSX.Element | undefined {
return (
<>
>
);
}
}
```
> Note: All methods are optional. If you do not override any method, the default dashboard layout will be used.
### Step 3: Add a route for the new dashboard
Open the `src/App.tsx` file, and add a route for the new dashboard. Here is an example:
```tsx
import YourDashboard from "./dashboards/YourDashboard";
export default function App() {
...
...
}
```
### Step 4: Modify manifest to add a new dashboard tab
Open the [`appPackage/manifest.json`](appPackage/manifest.json) file, and add a new dashboard tab under the `staticTabs`. Here is an example:
```json
{
"entityId": "index1",
"name": "Your Dashboard",
"contentUrl": "${{TAB_ENDPOINT}}/index.html#/yourdashboard",
"websiteUrl": "${{TAB_ENDPOINT}}/index.html#/yourdashboard",
"scopes": ["personal"]
}
```
# How to Override the Default Style
The Teams Toolkit provides some default styles for the dashboard and widget. You can customize the default style by overriding the `styling()` method in your dashboard or widget class.
## Override the default style for the widget
The `styling()` method in `BaseWidget` returns a `IWidgetClassNames` object that contains the following properties:
Property Meaning Default value
root The style of the dashboard or widget container.
```ts
{
display: "grid",
padding: "1.25rem 2rem 1.25rem 2rem",
backgroundColor: tokens.colorNeutralBackground1,
border: "1px solid var(--colorTransparentStroke)",
boxShadow: tokens.shadow4,
borderRadius: tokens.borderRadiusMedium,
gap: tokens.spacingHorizontalL,
gridTemplateRows: "max-content 1fr max-content"
}
```
header The style of the header.
```ts
{
display: "grid",
height: "max-content",
"& div": {
display: "grid",
gap: tokens.spacingHorizontalS,
alignItems: "center",
gridTemplateColumns: "min-content 1fr min-content",
},
"& svg": {
height: "1.5rem",
width: "1.5rem",
},
"& span": {
fontWeight: tokens.fontWeightSemibold,
lineHeight: tokens.lineHeightBase200,
fontSize: tokens.fontSizeBase200,
}
}
```
body The style of the body. none
footer The style of the footer.
```ts
"& button": {
width: "fit-content",
}
```
> Note: You can refer the [design tokens](https://react.fluentui.dev/?path=/docs/concepts-migration-getting-started--page#design-tokens) document from Fluent UI to learn more about `tokens`.
Each property can receive a string which is a css class name. You can use the [mergeStyles()](https://github.com/microsoft/fluentui/blob/master/packages/merge-styles/README.md) method from the `@fluentui/react` package to generate css classes. Here is an example:
```tsx
styling(): IWidgetClassNames {
return {
footer: mergeStyles({
"& button": {
color: tokens.colorBrandForeground1,
},
}),
};
}
```
## Override the default style for the dashboard
The Teams Toolkit provides a default style for the dashboard. The default style is as follows:
```ts
display: "grid",
gap: "20px",
padding: "20px",
gridTemplateRows: "1fr",
gridTemplateColumns: "4fr 6fr",
...(isMobile === true ? { gridTemplateColumns: "1fr", gridTemplateRows: "1fr" } : {}),
```
> Note: The `isMobile` variable is a boolean value that indicates whether the dashboard is displayed on a mobile device. You can use this value like `this.state.isMobile` in your dashboard class to customize the style for mobile devices. We assume that the dashboard is displayed on a mobile device if the screen width is less than 600px.
The `styling()` method in `BaseDashboard` returns a string which is also a css class name. Here is an example:
```tsx
styling(): string {
return mergeStyles({
gridTemplateColumns: "6fr 4fr",
});
}
```
# How to Add a New Graph API Call
Please follow these two steps:
1. Add SSO: Refer to How-to guides in Teams Toolkit by clicking Teams Toolkit in the side bar > `View how-to guides` > `Develop single sign-on experience in Teams`.
2. Refer to [this document](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teamsfx-sdk#microsoft-graph-scenarios:~:text=caught%20and%20transformed.-,Microsoft%20Graph%20Scenarios,-This%20section%20provides) to call a Graph API via TeamsFx SDK.