Name: microsoft-teams-sample-todo
Owner: Office Developer
Description: Sample that shows how to adapt an existing web app into a tab app for Microsoft Teams
Created: 2016-10-19 19:06:51.0
Updated: 2018-05-08 01:44:41.0
Pushed: 2018-04-18 22:11:35.0
Homepage: https://dev.office.com/microsoft-teams
Size: 293
Language: TypeScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
This is an example tab app for Microsoft Teams. The point of this sample to illustrate how simple it is to convert an existing web app into a Microsoft Teams tab app. The existing web app, TodoMVC for React, provides a basic task manager which integrates with your personal Outlook Tasks. With only a few minor modifications, this web view can be added to a channel as a tab app. Take a look at the code diff between the 'before' and 'after' branches to see what changes were made.
Note: This is not a realistic example of a team collaboration app. The tasks shown belong to the user's individual account and not to a shared team account.
For more information on developing experiences for Microsoft Teams, please review the Microsoft Teams developer documentation.
As the tab configuration and content pages are web apps, they must be hosted.
First, we'll prepare the project:
npm install
(included as part of Node.js) from the command line.To host the app locally:
npm start
to start the webpack-dev-server
to enable the dev app to function.Optionally, to build a deployable app, which you can host in your own environment:
npm run build
to generate a deployable build.Note: To re-upload an updated package, with the same
id
, click the 'Replace' icon at the end of the tab's table row. Don't click 'Upload' again: Microsoft Teams will say the tab already exists.It is advisable to have multiple configs, one per environment. The names of the zip files can be anything such as
todo.dev.zip
,todo.prod.zip
etc. but the zip must contain amanifest.json
with a uniqueid
. See Creating a manifest for your tab.
While the master
branch shows the latest state of the sample, take a look at the following code diff between:
Going through this step by step:
We have added a new config.html
and config.tsx
page which is responsible for the the application to allow the user to manipulate any settings, perform single signon Authentication etc. during the first launch. This is required so that the team administrator can configure the application/settings. See Create the configuration page.
We have added the same config.html
file to our webpack.common.js
configuration so that it can inject the right bundles during runtime.
We add a reference to MicrosoftTeams.js
in our index.html and added MicrosoftTeams.d.ts
for Typescript intellisense.
We have added a manifest.dev.json
, manifest.prod.json
and two logos for size 44x44 and 88x88. Remember to rename these as manifest.json
in your zip files that you upload to Microsoft Teams.
We have added some styles to our app.css
.
Finally we have modified the authentication
in outlook.tasks.ts to depend instead on 'useMicrosoftTeamsAuth', a new feature from the beta version of OfficeHelpers referenced in this sample.
When the user adds the tab, the configuration page is presented (config.html). In this case, the code authenticates the user if possible.
Authentication leverages a new Teams-specific function in the latest (>0.4.0) version of the office-js-helpers library. This helper function will attempt to silently authenticate, but if it cannot, it will call the Microsoft Teams specific auth dialog for you. For more information on the full Authentication process in Microsoft Teams, please review Authenticating a user in the Microsoft Teams developer documentation.
In outlook.tasks.ts:
urn this.authenticator.authenticate('Microsoft')
.then(token => this._token = token)
.catch(error => {
Utilities.log(error);
throw new Error('Failed to login using your Microsoft Account');
});
After successful sign-in, the user will Save the tab into the channel. The following code enables the Save button, and sets the SaveHandler, which will store what content to display in the tab (in this case, just the project's index.html).
In config.tsx:
initialize({ groupId, upn}) {
this.setState({ groupId, upn });
console.log(this.state);
/** Enable the Save button */
microsoftTeams.settings.setValidityState(true);
/** Register the save handler */
microsoftTeams.settings.registerOnSaveHandler(saveEvent => {
/** Store Tab content settings */
microsoftTeams.settings.setSettings({
contentUrl: `${location.origin}/index.html`,
suggestedDisplayName: "My Tasks",
websiteUrl: `${location.origin}/index.html`
});
saveEvent.notifySuccess();
});
}
This sample uses the following stack:
React by Facebook
as the UI Framework.TypeScript
as the transpiler.TodoMVC
base for TodoMVC functionality.Webpack
as the build tool.Note that this will not be necessary if you use the local Dev option above, but if you choose to host this tab in your own environment, you must register the application in order to authenticate.
Application ID
.Add Platform
and choose Web
.Allow Implicit Flow
and configure the redirect URL to be https://<mywebsite>/config.html
.For more information on hosting your own tab pages, see the Microsoft Teams 'Get Started' sample README.
Note: By default, your organization should allow you to create new apps. But if it doesn't, you can get a developer test tenant, a one-year trial subscription of Office 365 Developer at no charge. Here's how.
This project is based on the TodoMVC Typescript - React template located here.
Please read Contributing for details on our code of conduct, and the process for submitting pull requests to us.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
We use SemVer for versioning. For the versions available, see the tags on this repository.
This project is licensed under the MIT License - see the License file for details