### Install and Build Teams SDK, then Start SSR App Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md Steps to install dependencies, build the Teams JavaScript client SDK, and then start the SSR Test App from the monorepo root. ```bash cd {monorepo root} // Ensuring you have installed and built the Teams JavaScript client SDK pnpm install pnpm build pnpm start-ssr-app ``` -------------------------------- ### Install and Build SDK, then Build and Start Perf App Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-perf-test-app/README.md Commands to install dependencies, build the Teams JavaScript client SDK, build the perf test app, and start it. Assumes you are in the monorepo root directory. ```bash cd {monorepo root} // Ensuring you have installed and built the Teams JavaScript client SDK pnpm install pnpm build-sdk pnpm build-perf-app pnpm start-perf-app ``` -------------------------------- ### Install and Build Teams SDK Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/README.md Commands to install dependencies, build the Teams JavaScript client SDK, and start the test app from the monorepo root. ```bash cd {monorepo root} // Ensuring you have installed and built the Teams JavaScript client SDK pnpm install pnpm build pnpm start-test-app ``` -------------------------------- ### Install and Build Teams JavaScript Client SDK Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/README.md Commands to install dependencies, build the Teams JavaScript client SDK, and start the Blazor test app. ```bash cd {monorepo root} // Ensuring you have installed and built the Teams JavaScript client SDK pnpm install pnpm build pnpm start-blazor-app ``` -------------------------------- ### Build and Start Perf App from Project Directory Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-perf-test-app/README.md Alternative commands to build and start the perf test app directly from its project directory, assuming the Teams JavaScript client SDK is already built. ```bash pnpm build pnpm start ``` -------------------------------- ### Example Beta Release CDN URL Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Releases Example of the CDN URL for a specific beta release (version 2.19.0-beta.1). ```html https://res-sdf.cdn.office.net/teams-js/2.19.0-beta.1/js/MicrosoftTeams.min.js ``` -------------------------------- ### Install Dependencies Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md Install project dependencies using pnpm. Ensure you have pnpm version 9.0.6 or greater installed globally. ```bash pnpm install ``` -------------------------------- ### Run SSR App Normally and Start ngrok Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md Instructions for running the SSR Test App using ngrok for an HTTPS connection. This involves starting the app in one terminal and ngrok in another. ```bash # In one terminal, start the app normally pnpm dev # In another terminal, start ngrok ngrok http 3000 ``` -------------------------------- ### Handle Authentication Start Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/src/public/auth_start.html Processes URL parameters to set up authentication state and redirect URIs. Used for both mock OAuth testing and initiating Google OAuth flow. ```javascript const params = new URLSearchParams(window.location.search); const mockOAuth = params.get('mockOAuth'); const authId = params.get('authId'); const method = params.get('oauthRedirectMethod'); const redirectUrl = params.get('hostRedirectUrl'); const redirect_uri = params.get('redirect_uri'); const hostName = params.get('hostName'); const state = `{"authId":"${authId}","method":"${method}","hostName":"${hostName}"}`; if (redirectUrl) { sessionStorage.setItem('hostRedirectUrl', redirectUrl); } const getRedirectUri = () => { if (redirect_uri) { return redirect_uri; } else { const idx = window.location.href.lastIndexOf('/'); return `${window.location.href.slice(0, idx)}/auth_end.html`; } }; // Redirect to auth_end page if its mockOauth for testing if (mockOAuth === 'true') { window.location.href = getRedirectUri() + `?state=${state}&code=test_auth_code_1234`; } else { // Do actual google login const queryObj = { state, client_id: '1073583513214-oplf5k63msf7at9rcj68vbrh265803vo.apps.googleusercontent.com', response_type: 'code', access_type: 'offline', scope: 'email%20profile', }; const query = Object.entries(queryObj) .map(([k, v]) => `&${k}=${v}`) .join(''); window.location.href = `https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=${getRedirectUri()}${query}`; } ``` -------------------------------- ### Example Official Release CDN Script Tag Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Releases Example of how to include an official TeamsJS library release (version 2.18.0) using a script tag with integrity hash. ```html ``` -------------------------------- ### Generate SSR App SSL Certificates Manually Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md Manual steps to generate SSL certificates for the SSR Test App using mkcert, including installing mkcert, the local CA, and generating certificates for localhost. ```bash # Install mkcert (if not already installed) brew install mkcert # macOS # or follow instructions at https://github.com/FiloSottile/mkcert # Install the local CA mkcert -install # Generate certificates in the certificates directory cd apps/ssr-test-app/certificates mkcert localhost # This creates localhost.pem and localhost-key.pem ``` -------------------------------- ### Generate SSR App SSL Certificates Automatically Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md Automated script to set up SSL certificates for the SSR Test App, including checking for mkcert installation and generating certificates. ```bash # From the monorepo root pnpm setup-ssr-app-cert ``` -------------------------------- ### Run SSR App with HTTPS from Monorepo Root Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md Command to start the SSR Test App with HTTPS enabled when run from the monorepo root directory. ```bash # From monorepo root pnpm start-ssr-app:https ``` -------------------------------- ### Run SSR App with HTTPS from ssr-test-app Directory Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md Commands to start the SSR Test App with HTTPS enabled when run from the ssr-test-app project directory, differentiating between development and production modes. ```bash # Or from the ssr-test-app directory pnpm dev:https # for development # or pnpm start:https # for production (requires pnpm build first) ``` -------------------------------- ### Asynchronous Function with Callback (Deprecated) Source: https://github.com/officedev/microsoft-teams-library-js/wiki/Library-Architecture This is an example of an outdated asynchronous function signature that uses callbacks. New API calls will be rejected if they use this pattern. ```TypeScript export function getFoo(callback: (foo: Foo, sdkError: SdkError) => void): void {…} ``` -------------------------------- ### Build the Project Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md Build the entire project, including TeamsJS and all included apps, using pnpm. ```bash pnpm build ``` -------------------------------- ### Run Unit Tests Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md Execute unit tests for the project using pnpm. ```bash pnpm test ``` -------------------------------- ### Generate Bundle Analysis Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/tools/bundle-size-tools/bundle-analysis-app/README.md Run this command to generate a webpack profile for bundle analysis. ```bash pnpm webpack:profile ``` -------------------------------- ### Clone the Repository Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md Clone the Microsoft Teams JavaScript client library repository to your local machine. ```bash git clone https://github.com/OfficeDev/microsoft-teams-library-js.git ``` -------------------------------- ### Build or Test from teams-js Directory Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md When working within the `packages/teams-js` directory, you can run build or test commands directly. ```bash pnpm build ``` ```bash pnpm test ``` -------------------------------- ### Generate Reference Documentation Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md Locally generate reference documentation for TeamsJS v2. The output will be in the `packages/teams-js/docs` directory. ```bash pnpm run docs ``` -------------------------------- ### Including Open Iconic Standalone Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Link the default stylesheet for using Open Iconic without a specific framework. ```html ``` -------------------------------- ### Including Open Iconic with Foundation Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Link the Foundation-specific stylesheet to integrate Open Iconic with Foundation projects. ```html ``` -------------------------------- ### Enable TeamsJS Logging Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Logging Run this command in the browser console to enable the 'teamsJs' logging category. Note that this setting is case-sensitive and persists in local storage. ```javascript localStorage.debug = 'teamsJs.*'; ``` -------------------------------- ### Including Open Iconic with Bootstrap Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Link the Bootstrap-specific stylesheet to use Open Iconic with Bootstrap projects. ```html ``` -------------------------------- ### Standard JSDoc for Public Functions Source: https://github.com/officedev/microsoft-teams-library-js/wiki/Library-Architecture This is the standard format for documenting exported functions. It includes a clear description, parameter details, and return value information. ```JavaScript /** * Brief, clear description of exactly what this function is intended to do and * any side effects it might have (like showing UI to the user) * @param One per parameter, describing what the parameter is used for * @returns Brief, clear description of what the function returns. */ ``` -------------------------------- ### Moving APIs to App Namespace Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md APIs previously in `publicAPIs` and `appInitialization` have been moved to the new `app` namespace. This includes initialization, context, theme change handlers, and notification functions. ```typescript // Moved from publicAPIs to app namespace: initialize getContext registerOnThemeChangeHandler // Moved from appInitialization to app namespace: notifyAppLoaded notifySuccess notifyFailure notifyExpectedFailure // Added to app namespace: isInitialized getFrameContext ``` -------------------------------- ### Using Open Iconic with Foundation Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Use the `fi-icon-name` class on span elements to display icons when using Open Iconic with Foundation. ```html ``` -------------------------------- ### Using Open Iconic Standalone Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Apply the `oi` class and use the `data-glyph` attribute to specify the icon name when using Open Iconic independently. ```html ``` -------------------------------- ### Beta Release CDN URL Pattern Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Releases Use this URL pattern to reference beta TeamsJS library releases from the SDF CDN endpoint. Replace with the specific beta version. ```html https://res-sdf.cdn.office.net/teams-js//js/MicrosoftTeams.min.js ``` -------------------------------- ### Listen for Parent Window Messages Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/src/public/naa_childIframe.html Sets up an event listener to receive messages from the parent window. It validates the origin and extracts default payloads for the child iframe. ```javascript let defaultPayloadForBridge = ''; let defaultPayloadForTopWindow = ''; // Listen for messages from the parent window. window.addEventListener('message', (event) => { // Validate the origin if known if (event.origin !== window.origin) return; const data = event.data; if (data.defaultPayloadForBridge) { defaultPayloadForBridge = data.defaultPayloadForBridge; } if (data.defaultPayloadForTopWindow) { defaultPayloadForTopWindow = data.defaultPayloadForTopWindow; } }); ``` -------------------------------- ### Moving APIs to Pages.Config Sub-capability Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md APIs formerly in the `settings` namespace have been renamed and moved to the `pages.config` namespace. This includes handlers for configuration changes and getting/setting configuration. ```typescript // Renamed and moved to pages.config namespace (formerly settings): registerEnterSettingsHandler has renamed and moved to pages.config.registerChangeConfigHandler getSettings has been renamed pages.config.getConfig setSettings has been renamed pages.config.setConfig ``` -------------------------------- ### Commit Message Format Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/CONTRIBUTING.md Follow this format for commit messages to ensure clarity and consistency. Include a summary, detailed explanation, and issue tracking. ```console Summarize change in 50 characters or less Provide more detail after the first line. Leave one blank line below the summary and wrap all lines at 72 characters or less. If the change fixes an issue, leave another blank line after the final paragraph and indicate which issue is fixed in the specific format below. Fix #42 ``` -------------------------------- ### Importing Teams JS SDK Core Namespace Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md Demonstrates the new import convention for the Teams JavaScript client SDK, organizing top-level functions under a core namespace. This replaces the older `import * as ... from ...` syntax. ```typescript import { core } from '@microsoft/teams-js'; ``` -------------------------------- ### Moving APIs to Pages.FullTrust Sub-capability Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md APIs for full trust operations, such as entering and exiting fullscreen mode, have been moved from `privateAPIs` to the `pages.fullTrust` namespace. ```typescript // Moved from privateAPIs to pages.fullTrust namespace: enterFullscreen exitFullscreen ``` -------------------------------- ### Initialize Teams SDK and Notify Authentication Status Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/src/public/externalOauth_end.html This JavaScript function initializes the Microsoft Teams SDK and then notifies the Teams client of the authentication outcome (success or failure) based on URL parameters. It logs the process to the page. ```javascript function appendLog(msg) { const element = document.createElement('p'); element.textContent = msg; document.getElementById('log').appendChild(element); } const params = new URLSearchParams(window.location.search); const titleId = params.get('titleId'); async function callteamsJS() { if (microsoftTeams) { appendLog('successfully loaded microsoftTeams'); try { await microsoftTeams.app.initialize(); if (titleId === 'testOauthFailureTitleId') { microsoftTeams.authentication.notifyFailure('Failed'); appendLog('notifyFailure sent'); } else { microsoftTeams.authentication.notifySuccess('Success'); appendLog('notifySuccess sent'); } } catch (e) { appendLog('Error calling teams js: ' + e); } } else { appendLog('no microsoftTeams'); } } ``` -------------------------------- ### Coloring Icons with CSS Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Set the fill color for specific icons by applying a CSS rule to their unique class on the `` tag. ```css .icon-account-login { fill: #f00; } ``` -------------------------------- ### Sizing Icons with CSS Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Control the size of icons by setting equal width and height on the SVG element using CSS. ```css .icon { width: 16px; height: 16px; } ``` -------------------------------- ### Using Open Iconic with Bootstrap Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Apply the `oi` and `oi-icon-name` classes to span elements to display icons within a Bootstrap project. ```html ``` -------------------------------- ### Moving APIs to Pages.BackStack Sub-capability Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md APIs for managing the back stack have been moved to the `pages.backStack` namespace. This includes registering back button handlers and navigating back. ```typescript // Moved to new pages.backStack namespace: registerBackButtonHandler navigateBack ``` -------------------------------- ### Process Authentication Redirect Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/src/public/auth_end.html Use this code to parse URL parameters for authentication results and redirect the user. Ensure the 'state' parameter is correctly JSON-encoded and contains 'authId', 'method', and 'hostName'. The 'result' parameter is appended to the redirect URL. ```javascript const params = new URLSearchParams(window.location.search); const result = params.get('code'); const { authId, method, hostName } = JSON.parse(params.get('state')); // Redirect back to Orange host if (method === 'deeplink') { const storedRedirectUrl = sessionStorage.getItem('hostRedirectUrl'); if (storedRedirectUrl) { if (storedRedirectUrl.includes('{result}')) { window.location.href = storedRedirectUrl.replace('{result}', result); } else { const url = new URL(storedRedirectUrl); url.searchParams.append('result', result); window.location.href = url.toString(); } } else if (hostName === 'Orange') { window.location.href = `msorange://testapp.com/auth_callback?authId=${authId}&result=${result}`; } } document.getElementById('errorMessage').textContent = 'Unable to redirect back to the App'; ``` -------------------------------- ### Moving APIs to Pages Namespace Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md Several APIs have been reorganized under the new `pages` namespace, including frame context management, cross-domain navigation, and focus return. ```typescript // Moved to new pages namespace: registerFullScreenHandler initializeWithFrameContext navigateCrossDomain returnFocus setFrameContext has been renamed pages.setCurrentFrame ``` -------------------------------- ### Asynchronous Function with Promise (Recommended) Source: https://github.com/officedev/microsoft-teams-library-js/wiki/Library-Architecture This is the recommended signature for asynchronous functions using Promises. It provides a more modern and flexible way to handle asynchronicity. ```TypeScript export function getFoo(): Promise {…} ``` -------------------------------- ### Define New Capability Version Requirements Source: https://github.com/officedev/microsoft-teams-library-js/wiki/Library-Architecture Add a new capability and its host client compatibility requirements to versionConstants in runtime.ts. The object key is the version string, and the value is an array of capability requirements. ```TypeScript // Object key is type string, value is type Array '1.9.0': [ { capability: { anAndroidCapability: {} }, hostClientTypes: [ HostClientType.android, HostClientType.teamsRoomsAndroid, HostClientType.teamsPhones, HostClientType.teamsDisplays, ], }, ], ``` -------------------------------- ### Official Release CDN URL Pattern Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Releases Use this URL pattern to reference official TeamsJS library releases from a CDN. Replace with the specific version. ```html https://res.cdn.office.net/teams-js//js/MicrosoftTeams.min.js ``` -------------------------------- ### Function to be Tested: getCloudStorageFolders Source: https://github.com/officedev/microsoft-teams-library-js/wiki/Unit-Test-Guidelines This TypeScript function retrieves cloud storage folders for a given channel ID. It includes validation to throw an error if the channel ID is null or empty. ```TypeScript export function getCloudStorageFolders(channelId: string): Promise { return new Promise(resolve => { ensureInitialized(FrameContexts.content); // test should validate this throws Error on null channelId if (!channelId || channelId.length === 0) { throw new Error('[files.getCloudStorageFolders] channelId name cannot be null or empty'); } resolve(sendAndHandleError('files.getCloudStorageFolders', channelId)); }); } ``` -------------------------------- ### Importing Modules with TypeScript Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/README.md Use the import syntax to include specific modules from the Teams JavaScript library when using dependency loaders or module bundlers. ```typescript import { app } from '@microsoft/teams-js'; ``` -------------------------------- ### Displaying Open Iconic SVGs Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md Use the standard HTML `` tag to display individual SVG icons. Always include an `alt` attribute for accessibility. ```html icon name ``` -------------------------------- ### Referencing Teams JS Library via npm Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/README.md Include the Microsoft Teams JavaScript API in your HTML page by referencing the minified file from your local node_modules directory. ```html ``` -------------------------------- ### Moving APIs to Pages.AppButton Sub-capability Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md APIs related to app buttons have been renamed and moved to the `pages.appButton` namespace. This includes handlers for click and hover events. ```typescript // Renamed and moved to pages.appButton namespace: registerAppButtonClickHandler has renamed and moved to pages.appButton.onClick registerAppButtonHoverEnterHandler has renamed and moved to pages.appButton.onHoverEnter regsiterAppButtonHoverLeaveHandler has renamed and moved to pages.appButton.onHoverLeave ``` -------------------------------- ### Updated selectAppEntity Function Signature Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md Illustrates the change in the `selectAppEntity` function signature. It now accepts an additional `subEntityId` parameter, and the order of parameters in the callback has been reversed, with `sdkError` becoming optional. ```typescript selectAppEntity( threadId: string, categories: string[], callback: (appEntity: AppEntity, sdkError?: SdkError) => void, ): void is now: selectAppEntity( threadId: string, categories: string[], subEntityId: string, callback: (sdkError?: SdkError, appEntity?: AppEntity) => void, ): void ``` -------------------------------- ### Moving APIs to Pages.Tabs Sub-capability Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md APIs related to tab management have been moved to the `pages.tabs` namespace. This includes functions for retrieving tab instances and navigating between tabs. ```typescript // Moved to new pages.tabs namespace: getTabInstances getMruTabInstances navigateToTab ``` -------------------------------- ### Referencing Teams JS Library Locally Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/README.md Include the Microsoft Teams JavaScript API in your HTML page by referencing the minified file directly from your local project. ```html ```