Skip to content

[Word] (import template) Add support for the unified manifest #971

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Jul 8, 2025
Merged
Show file tree
Hide file tree
Changes from 15 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 92 additions & 24 deletions Samples/word-import-template/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ products:
- office-word
- office
- m365
- office-teams
languages:
- javascript
extensions:
Expand Down Expand Up @@ -33,10 +34,6 @@ The user updates their Word document with the content from another Word document
- Word on Mac
- Word on the web

## Prerequisites

- Office connected to a Microsoft 365 subscription (including Office on the web).

## Solution

| Solution | Authors |
Expand All @@ -48,33 +45,30 @@ The user updates their Word document with the content from another Word document
| Version | Date | Comments |
|----------|------|----------|
| 1.0 | 03-08-2024 | Initial release |
| 1.1 | 07-07-2025 | Add support for the unified manifest for Microsoft 365 |

## Run the sample
## Decide on a version of the manifest

You can run this sample in Word on Windows, on Mac, or in a browser. The add-in web files are served from this repo on GitHub.
- Add-in only manifest
- To run the add-in only manifest, which is the **manifest.xml** file in the sample's root directory **Samples/word-import-template**, go to the [Add-in only manifest](#add-in-only-manifest) section.
- [Unified manifest for Microsoft 365](https://learn.microsoft.com/office/dev/add-ins/develop/json-manifest-overview)
- To run the unified manifest for Microsoft 365 (**manifest.json**), go to the [Unified manifest](#unified-manifest) section.

1. Download the **manifest.xml** file from this sample to a folder on your computer.
1. Sideload the add-in manifest in Word by following the appropriate instructions in the article [Sideload an Office Add-in for testing](https://learn.microsoft.com/office/dev/add-ins/testing/test-debug-office-add-ins#sideload-an-office-add-in-for-testing).
## Add-in only manifest

### Try it out
### Run the sample

Once the add-in is loaded, use the following steps to try out the functionality.

1. Open Word on Windows, on Mac, or in a browser.
Use one of the following add-in file hosting options to run the sample.

1. To open the add-in task pane, go to the **Home** tab and choose **Show Task Pane**.
#### Use GitHub as the web host

1. In the "Template" section of the add-in UI, select **Choose File**. Navigate to the location of your .docx file then open the file. The template is automatically applied to your document, replacing any preexisting content.

![The initial screen displaying the button to choose a file.](./resources/word-import-template-initial-screen.png)

For convenience, the resources folder of this project includes a *template example.docx* file.

![Screen showing the imported template.](./resources/word-import-template-applied.png)
You can run this sample in Word on Windows, on Mac, or in a browser. The add-in web files are served from this repo on GitHub.

1. In the document, update the text and other content.
1. Download the **manifest.xml** file from this sample to a folder on your computer.
1. Sideload the add-in manifest in Word by following the appropriate instructions in the article [Sideload an Office Add-in for testing](https://learn.microsoft.com/office/dev/add-ins/testing/test-debug-office-add-ins#sideload-an-office-add-in-for-testing).
1. Follow the steps in [Try it out](#try-it-out) to test the sample.

## Run the sample from localhost
#### Use localhost

If you prefer to configure a web server and host the add-in's web files from your computer, use the following steps.

Expand Down Expand Up @@ -106,9 +100,83 @@ If you prefer to configure a web server and host the add-in's web files from you
office-addin-https-reverse-proxy --url http://localhost:3000
```

1. Sideload `manifest-localhost.xml` in Word by following the appropriate instructions in the article [Sideload an Office Add-in for testing](https://learn.microsoft.com/office/dev/add-ins/testing/test-debug-office-add-ins#sideload-an-office-add-in-for-testing).
1. Sideload **manifest-localhost.xml** in Word by following the appropriate instructions in the article [Sideload an Office Add-in for testing](https://learn.microsoft.com/office/dev/add-ins/testing/test-debug-office-add-ins#sideload-an-office-add-in-for-testing).

1. Follow the steps in [Try it out](#try-it-out) to test the sample.

## Unified manifest

### Prerequisites

- If you want to run the web server on localhost, install a recent version of [npm](https://www.npmjs.com/get-npm) and [Node.js](https://nodejs.org) on your computer. To check if you've already installed these tools, from a command prompt, run the following commands.

```console
node -v
npm -v
```

- If you want to run the sample using GitHub as the web host, install the [Microsoft 365 Agents Toolkit command line interface (CLI)](https://learn.microsoft.com/microsoftteams/platform/toolkit/teams-toolkit-cli). From a command prompt, run the following command.

```console
npm install -g @microsoft/teamsapp-cli
```

### Run the sample

You can run this sample in Word on Windows, on Mac, or in a browser. Use one of the following add-in file hosting options.

#### Use GitHub as the web host

1. [Try out the sample!](#try-it-out)
The quickest way to run the sample is to use GitHub as the web host. However, you can't debug or change the source code. The add-in web files are served from this GitHub repository.

1. Download the **manifest-configurations/unified/word-import-template.zip** file from this sample to a folder on your computer.
1. Sideload the add-in manifest in Word by following the appropriate instructions in the article [Sideload Office Add-ins that use the unified manifest for Microsoft 365](https://learn.microsoft.com/office/dev/add-ins/testing/sideload-add-in-with-unified-manifest).
1. Follow the steps in [Try it out](#try-it-out) to test the sample.

#### Use localhost

If you prefer to host the web server on localhost, follow these steps:

1. Clone or download this repository.
1. From a command prompt, go to the root of the project folder **/Samples/word-import-template**.
1. Copy the files from the **manifest-configurations/unified** subfolder to the root folder.
1. Run the following commands.

```console
npm install
```

```console
npm start
```

This starts the web server on localhost and sideloads the **manifest.json** file to Word.

1. Follow the steps in [Try it out](#try-it-out) to test the sample.

1. To stop the web server and uninstall the add-in from Word, run the following command.

```console
npm stop
```

## Try it out

Once the add-in is loaded, use the following steps to try out the functionality.

1. Open Word on Windows, on Mac, or in a browser.

1. To open the add-in task pane, go to the **Home** tab and choose **Show Task Pane**.

1. In the "Template" section of the add-in UI, select **Choose File**. Navigate to the location of your .docx file then open the file. The template is automatically applied to your document, replacing any preexisting content.

![The initial screen displaying the button to choose a file.](./resources/word-import-template-initial-screen.png)

For convenience, the resources folder of this project includes a *template example.docx* file.

![Screen showing the imported template.](./resources/word-import-template-applied.png)

1. In the document, update the text and other content.

## Make it yours

Expand Down
Binary file added Samples/word-import-template/assets/color.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Samples/word-import-template/assets/outline.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 4 additions & 2 deletions Samples/word-import-template/assets/sample.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@
"The user updates their Word document with the content from another Word document, treating the external document like a template. The user selects a Word document through the add-in UI then it's applied to the current document."
],
"creationDateTime": "2024-03-08",
"updateDateTime": "2024-03-08",
"updateDateTime": "2025-07-07",
"products": [
"Office"
"Office",
"Teams",
"TeamsToolkit"
],
"metadata": [
{
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
# Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
# Visit https://aka.ms/teamsfx-actions for details on actions
version: v1.7

environmentFolderPath: ./env

# Triggered when 'teamsapp provision' is executed
provision:
- uses: arm/deploy # Deploy given ARM templates parallelly.
with:
# AZURE_SUBSCRIPTION_ID is a built-in environment variable,
# if its value is empty, TeamsFx will prompt you to select a subscription.
# Referencing other environment variables with empty values
# will skip the subscription selection prompt.
subscriptionId: ${{AZURE_SUBSCRIPTION_ID}}
# AZURE_RESOURCE_GROUP_NAME is a built-in environment variable,
# if its value is empty, TeamsFx will prompt you to select or create one
# resource group.
# Referencing other environment variables with empty values
# will skip the resource group selection prompt.
resourceGroupName: ${{AZURE_RESOURCE_GROUP_NAME}}
templates:
- path: ./infra/azure.bicep # Relative path to this file
# Relative path to this yaml file.
# Placeholders will be replaced with corresponding environment
# variable before ARM deployment.
parameters: ./infra/azure.parameters.json
# Required when deploying ARM template
deploymentName: Create-resources-for-tab
# Teams Toolkit will download this bicep CLI version from github for you,
# will use bicep CLI in PATH if you remove this config.
bicepCliVersion: v0.9.1

# Get the deployment token from Azure Static Web Apps
- uses: azureStaticWebApps/getDeploymentToken
with:
resourceId: ${{AZURE_STATIC_WEB_APPS_RESOURCE_ID}}
# Save deployment token to the environment file for the deployment action
writeToEnvironmentFile:
deploymentToken: SECRET_TAB_SWA_DEPLOYMENT_TOKEN

# Triggered when 'teamsapp deploy' is executed
deploy:
# Run npm command
- uses: cli/runNpmCommand
name: install dependencies
with:
args: install
- uses: cli/runNpmCommand
name: build app
with:
args: run build --if-present
# Azure Static Web Apps needs index.html
- uses: cli/runNpxCommand
with:
args: shx touch dist/index.html
# Deploy bits to Azure Static Web Apps
- uses: cli/runNpxCommand
name: deploy to Azure Static Web Apps
with:
args: '@azure/static-web-apps-cli deploy ./dist -d
${{SECRET_TAB_SWA_DEPLOYMENT_TOKEN}} --env production'
projectId: 445fce6e-0384-4531-ade7-dd7b25673031
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"id": "6be35712-f71b-4bd8-83a3-908a397db2d0",
"manifestVersion": "devPreview",
"version": "1.0.1",
"name": {
"short": "Import template - sample",
"full": "Import template - sample"
},
"description": {
"short": "Get started with document templates.",
"full": "Get started with document templates."
},
"developer": {
"name": "Contoso",
"websiteUrl": "https://www.contoso.com",
"privacyUrl": "https://www.contoso.com/privacy",
"termsOfUseUrl": "https://www.contoso.com/servicesagreement"
},
"icons": {
"outline": "assets/outline.png",
"color": "assets/color.png"
},
"accentColor": "#230201",
"localizationInfo": {
"defaultLanguageTag": "en-us",
"additionalLanguages": []
},
"authorization": {
"permissions": {
"resourceSpecific": [
{
"name": "Document.ReadWrite.User",
"type": "Delegated"
}
]
}
},
"validDomains": [
"contoso.com"
],
"extensions": [
{
"requirements": {
"scopes": [
"document"
]
},
"runtimes": [
{
"requirements": {
"capabilities": [
{
"name": "AddinCommands",
"minVersion": "1.1"
}
]
},
"id": "TaskPaneRuntime",
"type": "general",
"code": {
"page": "https://localhost:3000/taskpane.html"
},
"lifetime": "short",
"actions": [
{
"id": "TaskPaneRuntimeShow",
"type": "openPage"
}
]
}
],
"ribbons": [
{
"contexts": [
"default"
],
"tabs": [
{
"builtInTabId": "TabHome",
"groups": [
{
"id": "CommandsGroup",
"label": "Contoso Add-in",
"icons": [
{
"size": 16,
"url": "https://localhost:3000/assets/icon-16.png"
},
{
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"size": 80,
"url": "https://localhost:3000/assets/icon-80.png"
}
],
"controls": [
{
"id": "TaskPaneButton",
"type": "button",
"label": "Show Task Pane",
"icons": [
{
"size": 16,
"url": "https://localhost:3000/assets/icon-16.png"
},
{
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"size": 80,
"url": "https://localhost:3000/assets/icon-80.png"
}
],
"supertip": {
"title": "Show Task Pane",
"description": "Click to show a task pane."
},
"actionId": "TaskPaneRuntimeShow",
"enabled": true
}
]
}
]
}
]
}
],
"alternates": [
{
"alternateIcons": {
"icon": {
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
"highResolutionIcon": {
"size": 64,
"url": "https://localhost:3000/assets/icon-64.png"
}
}
}
],
"getStartedMessages": [
{
"title": "Get started with your sample add-in!",
"description": "Your sample add-in loaded successfully. Go to the HOME tab and click the 'Show Task Pane' button to get started.",
"learnMoreUrl": "https://go.microsoft.com/fwlink/?LinkId=276812"
}
]
}
]
}
Loading