Skip to content
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

[DO NOT MERGE] Enable creating add-in in one step in a new tab #4314

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all 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
5 changes: 5 additions & 0 deletions docs/includes/quickstart-choose-editor-experiment.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Create an Office add-in using the one-line script, Yeoman generator for Office Add-ins, or Visual Studio.
- The one-line script automatically sets up your local machine's environment and launches the sample add-in project in Visual Studio Code. This bypasses the manual steps to build an add-in and takes you straight to the code, so that you can test the add-in immediately.
- The Yeoman generator creates a Node.js project that can be managed with Visual Studio Code or any other editor.
- Visual Studio creates a Visual Studio solution.
Select the tab for the option you'd like to use, then follow the instructions to create your add-in and test it locally.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Select the tab for the option you'd like to use, then follow the instructions to create your add-in and test it locally.
Select the tab for the option you'd like to use, then follow the instructions to create your add-in and test it locally.

276 changes: 276 additions & 0 deletions docs/quickstarts/excel-quickstart-jquery-experiment.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,276 @@
---
title: Build your first Excel task pane add-in
description: Learn how to build a simple Excel task pane add-in by using the Office JS API.
ms.date: 12/11/2023
ms.service: excel
ms.localizationpriority: high
---

# Build an Excel task pane add-in

In this article, you'll walk through the process of building an Excel task pane add-in.

## Create the add-in

[!include[Choose your editor](../includes/quickstart-choose-editor-experiment.md)]

# [One-line script](#tab/script)

### Prerequisites

You must have Office connected to a Microsoft 365 subscription.

> [!NOTE]
> If you don't already have Office, you can [join the Microsoft 365 developer program](https://developer.microsoft.com/microsoft-365/dev-program) to get a free, 90-day renewable Microsoft 365 subscription to use during development.

### Create the add-in project

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can run the one-line script on Windows or on macOS. It performs the following to set up the add-in development environment.
- Installs Node.js, npm, and Git, if they aren't found on your machine.
- Downloads the files of the sample add-in project.
- Opens the add-in project in Visual Studio Code, if installed. If Visual Studio Code isn't installed on your machine, the folder that contains the add-in project files opens instead.
- Prompts you to run the add-in.
> [!NOTE]
> In addition to Windows and macOS, we're working to support the script on other platforms.

Suggesting to move this before the commands based on user feedback we received in the past. Users mentioned that they prefer/expect to see the explanation before the actual code.

You can run the one-line script on Windows or on macOS. It performs the following to set up the add-in development environment.

On Windows:
- Installs Node.js, and Git, if they aren't found on your machine.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Installs Node.js, and Git, if they aren't found on your machine.
- Installs Node.js and Git, if they aren't found on your machine.

- Downloads the files of the sample add-in project.
- Opens the add-in project in Visual Studio Code, if installed. If Visual Studio Code isn't installed on your machine, the folder that contains the add-in project files opens instead.
- Prompts you to run the add-in.

On macOS:
- Downloads the files of the sample add-in project.
- Opens the folder that contains the add-in project files. Or opens the add-in project in Visual Studio Code if it is installed and configured to support launching from terminal.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Opens the folder that contains the add-in project files. Or opens the add-in project in Visual Studio Code if it is installed and configured to support launching from terminal.
- Opens the folder that contains the add-in project files. If Visual Studio Code is installed and configured to launch projects from the terminal, the add-in project opens there instead.

- Prompts you to run the add-in.
> [!NOTE]
> In addition to Windows and macOS, we're working to support the script on other platforms.

If you're using Windows, run the following from a command prompt.
```command line
iwr aka.ms/exceladdin/helloworld -outfile excelhelloworld.bat; saps excelhelloworld.bat
```
If you're using macOS, run the following in a terminal.
```command line
bash <(curl -L -s aka.ms/exceladdin/helloworld_mac)
```

### Try it out

Once your add-in project is set up, it automatically opens in Visual Studio Code. If you don't have Visual Studio Code installed on your machine, the folder containing the files of your add-in project opens instead.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Once your add-in project is set up, it automatically opens in Visual Studio Code. If you don't have Visual Studio Code installed on your machine, the folder containing the files of your add-in project opens instead.
Once your add-in project is set up, it automatically opens in Visual Studio Code.
> [!NOTE]
> If you don't have Visual Studio Code installed on your machine, the folder containing the files of your add-in project opens instead. For guidance on how to install Visual Studio Code and test the add-in, see the project's readme file.

@GavinGu07 suggesting this to provide additional guidance for users without VS Code installed. I took this from the spec, but let me know if this is no longer accurate.


If you choose to run the add-in when prompted, an Excel spreadsheet opens, displaying the add-in task pane. Select a range of cells in the spreadsheet, then choose **Run** from the task pane to set the color of the selected range to yellow.

![The sample add-in task pane in Excel with the Run button highlighted.](../images/excel-quickstart-addin-3c.png)

### Next steps

Congratulations, you've successfully created an Excel task pane add-in! Next, learn more about the capabilities of an Excel add-in and build a more complex add-in by following along with the [Excel add-in tutorial](../tutorials/excel-tutorial.md).

# [Yeoman generator](#tab/yeomangenerator)

### Prerequisites

[!include[Yeoman generator prerequisites](../includes/quickstart-yo-prerequisites.md)]

### Create the add-in project

[!include[Yeoman generator create project guidance](../includes/yo-office-command-guidance.md)]

- **Choose a project type:** `Office Add-in Task Pane project`
- **Choose a script type:** `Javascript`
- **What do you want to name your add-in?** `My Office Add-in`
- **Which Office client application would you like to support?** `Excel`

![The Yeoman Generator for Office Add-ins command line interface.](../images/yo-office-excel.png)

After you complete the wizard, the generator creates the project and installs supporting Node components.

[!include[Node.js version 20 warning](../includes/node-20-warning-note.md)]

[!include[Yeoman generator next steps](../includes/yo-office-next-steps.md)]

### Explore the project

[!include[Yeoman generator add-in project components](../includes/yo-task-pane-project-components-js.md)]

### Try it out

1. Navigate to the root folder of the project.

```command&nbsp;line
cd "My Office Add-in"
```

1. [!include[Start server section](../includes/quickstart-yo-start-server-excel.md)]

1. In Excel, choose the **Home** tab, and then choose the **Show Taskpane** button on the ribbon to open the add-in task pane.

![The Excel Home menu, with the Show Taskpane button highlighted.](../images/excel-quickstart-addin-3b.png)

1. Select any range of cells in the worksheet.

1. At the bottom of the task pane, choose the **Run** link to set the color of the selected range to yellow.

![The add-in task pane open in Excel, with the Run button highlighted in the add-in task pane.](../images/excel-quickstart-addin-3c.png)

### Next steps

Congratulations, you've successfully created an Excel task pane add-in! Next, learn more about the capabilities of an Excel add-in and build a more complex add-in by following along with the [Excel add-in tutorial](../tutorials/excel-tutorial.md).

# [Visual Studio](#tab/visualstudio)

### Prerequisites

[!include[Quick Start prerequisites](../includes/quickstart-vs-prerequisites.md)]

### Create the add-in project

1. In Visual Studio, choose **Create a new project**.

1. Using the search box, enter **add-in**. Choose **Excel Web Add-in**, then select **Next**.

1. Name your project **ExcelWebAddIn1** and select **Create**.

1. In the **Create Office Add-in** dialog window, choose **Add new functionalities to Excel**, and then choose **Finish** to create the project.

1. Visual Studio creates a solution and its two projects appear in **Solution Explorer**. The **Home.html** file opens in Visual Studio.

### Explore the Visual Studio solution

[!include[Description of Visual Studio projects](../includes/quickstart-vs-solution.md)]

### Update the code

1. **Home.html** specifies the HTML that will be rendered in the add-in's task pane. In **Home.html**, replace the `<body>` element with the following markup and save the file.

```html
<body class="ms-font-m ms-welcome">
<div id="content-header">
<div class="padding">
<h1>Welcome</h1>
</div>
</div>
<div id="content-main">
<div class="padding">
<p>Choose the button below to set the color of the selected range to green.</p>
<br />
<h3>Try it out</h3>
<button class="ms-Button" id="set-color">Set color</button>
</div>
</div>
</body>
```

1. Open the file **Home.js** in the root of the web application project. This file specifies the script for the add-in. Replace the entire contents with the following code and save the file.

```js
'use strict';

(function () {

Office.onReady(function() {
// Office is ready
$(document).ready(function () {
// The document is ready
$('#set-color').click(setColor);
});
});

async function setColor() {
await Excel.run(async (context) => {
const range = context.workbook.getSelectedRange();
range.format.fill.color = 'green';

await context.sync();
}).catch(function (error) {
console.log("Error: " + error);
if (error instanceof OfficeExtension.Error) {
console.log("Debug info: " + JSON.stringify(error.debugInfo));
}
});
}
})();
```

1. Open the file **Home.css** in the root of the web application project. This file specifies the custom styles for the add-in. Replace the entire contents with the following code and save the file.

```css
#content-header {
background: #2a8dd4;
color: #fff;
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 80px;
overflow: hidden;
}

#content-main {
background: #fff;
position: fixed;
top: 80px;
left: 0;
right: 0;
bottom: 0;
overflow: auto;
}

.padding {
padding: 15px;
}
```

### Update the manifest

1. In **Solution Explorer**, go to the **ExcelWebAddIn1** add-in project and open the **ExcelWebAddIn1Manifest** directory. This directory contains your manifest file, **ExcelWebAddIn1.xml**. The XML manifest file defines the add-in's settings and capabilities. See the preceding section [Explore the Visual Studio solution](#explore-the-visual-studio-solution) for more information about the two projects created by your Visual Studio solution.

1. The `ProviderName` element has a placeholder value. Replace it with your name.

1. The `DefaultValue` attribute of the `DisplayName` element has a placeholder. Replace it with **My Office Add-in**.

1. The `DefaultValue` attribute of the `Description` element has a placeholder. Replace it with **A task pane add-in for Excel**.

1. Save the file.

```xml
...
<ProviderName>John Doe</ProviderName>
<DefaultLocale>en-US</DefaultLocale>
<!-- The display name of your add-in. Used on the store and various places of the Office UI such as the add-ins dialog. -->
<DisplayName DefaultValue="My Office Add-in" />
<Description DefaultValue="A task pane add-in for Excel"/>
...
```

### Try it out

1. Using Visual Studio, test the newly created Excel add-in by pressing **F5** or choosing the **Start** button to launch Excel with the **Show Taskpane** add-in button displayed on the ribbon. The add-in will be hosted locally on IIS. If you are asked to trust a certificate, do so to allow the add-in to connect to its Office application.

1. In Excel, choose the **Home** tab, and then choose the **Show Taskpane** button on the ribbon to open the add-in task pane.

![The Excel Home menu, with the Show Taskpane button highlighted.](../images/excel-quickstart-addin-2a.png)

1. Select any range of cells in the worksheet.

1. In the task pane, choose the **Set color** button to set the color of the selected range to green.

![The add-in task pane open in Excel.](../images/excel-quickstart-addin-2c.png)

[!include[Console tool note](../includes/console-tool-note.md)]

### Next steps

Congratulations, you've successfully created an Excel task pane add-in! Next, learn more about [developing Office Add-ins with Visual Studio](../develop/develop-add-ins-visual-studio.md).

---

[!include[The common troubleshooting section for all quickstarts](../includes/quickstart-troubleshooting.md)]

## Code samples

- [Excel "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/excel-hello-world): Learn how to build a simple Office Add-in with only a manifest, HTML web page, and a logo.

## See also

- [Office Add-ins platform overview](../overview/office-add-ins.md)
- [Develop Office Add-ins](../develop/develop-overview.md)
- [Excel JavaScript object model in Office Add-ins](../excel/excel-add-ins-core-concepts.md)
- [Excel add-in code samples](https://developer.microsoft.com/microsoft-365/gallery/?filterBy=Excel,Samples)
- [Excel JavaScript API reference](../reference/overview/excel-add-ins-reference-overview.md)
- [Using Visual Studio Code to publish](../publish/publish-add-in-vs-code.md#using-visual-studio-code-to-publish)
Loading