diff --git a/docs/develop/develop-overview-experiment.md b/docs/develop/develop-overview-experiment.md new file mode 100644 index 0000000000..fdd232f274 --- /dev/null +++ b/docs/develop/develop-overview-experiment.md @@ -0,0 +1,142 @@ +--- +title: Develop Office Add-ins +description: An introduction to developing Office Add-ins. +ms.topic: overview +ms.date: 05/26/2023 +ms.localizationpriority: high +--- + +# Develop Office Add-ins + +> [!TIP] +> Please review [Office Add-ins platform overview](../overview/office-add-ins.md) before reading this article. + +All Office Add-ins are built upon the Office Add-ins platform. For any add-in you build, you'll need to understand important concepts like application and platform availability, Office JavaScript API programming patterns, how to specify an add-in's settings and capabilities in the manifest file, how to design the UI and user experience, and more. Core development concepts like these are covered here in the **Development lifecycle** > **Develop** section of the documentation. Review the information here before exploring the application-specific documentation that corresponds to the add-in you're building (for example, [Excel](../excel/index.yml)). + +## Create an Office Add-in + +You can create an Office Add-in by using the [Yeoman generator for Office Add-ins](yeoman-generator-overview.md), Visual Studio, or Teams Toolkit. + +### Yeoman generator + +The Yeoman generator for Office Add-ins can be used to create a Node.js Office Add-in project that can be managed with Visual Studio Code or any other editor. The generator can create Office Add-ins for any of the following: + +- Excel +- OneNote +- Outlook +- PowerPoint +- Project +- Word +- Excel custom functions + +Create your project using HTML, CSS and JavaScript (or TypeScript), or using React. If you choose React, you can choose between JavaScript and Typescript as well. For more information about creating add-ins with the generator, see [Yeoman generator for Office Add-ins](yeoman-generator-overview.md). + +### Visual Studio + +Visual Studio can be used to create Office Add-ins for Excel, Outlook, Word, and PowerPoint. An Office Add-in project gets created as part of a Visual Studio solution and uses HTML, CSS, and JavaScript. For more information about creating add-ins with Visual Studio, see [Develop Office Add-ins with Visual Studio](../develop/develop-add-ins-visual-studio.md). + +[!include[Yeoman vs Visual Studio comparison](../includes/yeoman-generator-recommendation.md)] + +### Teams Toolkit + +The Teams Toolkit can be used to create almost any kind of Teams App, a term which includes all extensions of Microsoft 365, including those that don't extend the Teams application. For details about creating an add-in, see [Create Office Add-in projects with Teams Toolkit](teams-toolkit-overview.md). + +## Understand the two parts of an Office Add-in + +An Office Add-in consists of two parts. + +- The add-in manifest that defines the settings and capabilities of the add-in. + +- The web application that defines the UI and functionality of add-in components such as task panes, content add-ins, and dialog boxes. + +The web application uses the Office JavaScript API to interact with content in the Office document where the add-in is running. Your add-in can also do other things that web applications typically do, like call external web services, facilitate user authentication, and more. + +### Define an add-in's settings and capabilities + +An Office Add-in's manifest defines the settings and capabilities of the add-in. You'll configure the manifest to specify things such as: + +- Metadata that describes the add-in (for example, ID, version, description, display name, default locale). +- Office applications where the add-in will run. +- Permissions that the add-in requires. +- How the add-in integrates with Office, including any custom UI that the add-in creates (for example, a custom tab or custom ribbon buttons). +- Location of images that the add-in uses for branding and command iconography. +- Dimensions of the add-in (for example, dimensions for content add-ins, requested height for Outlook add-ins). +- Rules that specify when the add-in activates in the context of a message or appointment (for Outlook add-ins only). +- Keyboard shortcuts (for Excel only). + +For detailed information about the manifest, see [Office Add-ins manifest](add-in-manifests.md). + +### Interact with content in an Office document + +An Office Add-in can use the Office JavaScript APIs to interact with content in the Office document where the add-in is running. + +#### Access the Office JavaScript API library + +[!include[information about accessing the Office JS API library](../includes/office-js-access-library.md)] + +#### API models + +[!include[information about the Office JS API models](../includes/office-js-api-models.md)] + +#### API requirement sets + +[!include[information about the Office JS API requirement sets](../includes/office-js-requirement-sets.md)] + +#### Explore APIs with Script Lab + +Script Lab is an add-in that enables you to explore the Office JavaScript API and run code snippets while you're working in an Office program such as Excel or Word. It's available for free via AppSource and is a useful tool to include in your development toolkit as you prototype and verify the functionality you want in your add-in. In Script Lab, you can access a library of built-in samples to quickly try out APIs or even use a sample as the starting point for your own code. + +The following one-minute video shows Script Lab in action. + +[![Short video that shows Script Lab running in Excel, Word, and PowerPoint.](../images/screenshot-wide-youtube.png 'Script Lab preview video')](https://aka.ms/scriptlabvideo) + +For more information about Script Lab, see [Explore Office JavaScript APIs using Script Lab](../overview/explore-with-script-lab.md). + +## Extend the Office UI + +An Office Add-in can extend the Office UI by using add-in commands and HTML containers such as task panes, content add-ins, or dialog boxes. + +- [Add-in commands](../design/add-in-commands.md) can be used to add a custom tab, custom buttons and menus to the default ribbon in Office, or to extend the default context menu that appears when users right-click text in an Office document or an object in Excel. When users select an add-in command, they initiate the task that the add-in command specifies, such as running JavaScript code, opening a task pane, or launching a dialog box. + +- HTML containers like [task panes](../design/task-pane-add-ins.md), [content add-ins](../design/content-add-ins.md), and [dialog boxes](../develop/dialog-api-in-office-add-ins.md) can be used to display custom UI and expose additional functionality within an Office application. The content and functionality of each task pane, content add-in, or dialog box derives from a web page that you specify. Those web pages can use the Office JavaScript API to interact with content in the Office document where the add-in is running, and can also do other things that web pages typically do, like call external web services, facilitate user authentication, and more. + +The following image shows an add-in command on the ribbon, a task pane to the right of the document, and a dialog box or content add-in over the document. + +![Diagram showing add-in commands on the ribbon, a task pane, and a dialog box / content add-in in an Office document.](../images/add-in-ui-elements.png) + +For more information about extending the Office UI and designing the add-in's UX, see [Office UI elements for Office Add-ins](../design/interface-elements.md). + +## Next steps + +This article has outlined the different ways to create Office Add-ins, introduced the ways that an add-in can extend the Office UI, described the API sets, and introduced Script Lab as a valuable tool for exploring Office JavaScript APIs and prototyping add-in functionality. Now that you've explored this introductory information, consider continuing your Office Add-ins journey along the following paths. + +### Create an Office Add-in + +Discover how Office Add-ins create solutions for content creation, better collaboration with peers, and task automation. Run the following samples to experience quick and easy real-life solutions in action. + +- [Add AI-generated content to your Word document](https://github.com/OfficeDev/Word-Scenario-based-Add-in-Samples/tree/main/Word-Add-in-AIGC) +- [Get data from an Excel spreadsheet for a mail merge](https://github.com/OfficeDev/Excel-Scenario-based-Add-in-Samples/tree/main/Mail-Merge-Sample-Add-in) +- [Create PowerPoint presentations with unique designs](../powerpoint/shapes.md) +- [Automatically insert a personalized signature in Outlook](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-set-signature) + +When you're ready to create your own solution, start with a simple "Hello World" add-in with only a manifest, HTML web page, and a logo. + +- [Excel "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/excel-hello-world) +- [Outlook "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/outlook-hello-world) +- [PowerPoint "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/powerpoint-hello-world) +- [Word "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/word-hello-world) + +### Learn more + +Learn more about developing, testing, and publishing Office Add-ins by exploring this documentation. + +> [!TIP] +> For any add-in that you build, you'll use information in the [Development lifecycle](../overview/core-concepts-office-add-ins.md) section of this documentation, along with information in the application-specific section that corresponds to the type of add-in you're building (for example, [Excel](../excel/index.yml)). + +## See also + +- [Office Add-ins platform overview](../overview/office-add-ins.md) +- [Learn about the Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program) +- [Design Office Add-ins](../design/add-in-design.md) +- [Test and debug Office Add-ins](../testing/test-debug-office-add-ins.md) +- [Publish Office Add-ins](../publish/publish.md) diff --git a/docs/excel/excel-add-ins-overview-experiment.md b/docs/excel/excel-add-ins-overview-experiment.md new file mode 100644 index 0000000000..91d2937de7 --- /dev/null +++ b/docs/excel/excel-add-ins-overview-experiment.md @@ -0,0 +1,112 @@ +--- +title: Excel add-ins overview +description: Excel add-in allow you to extend Excel application functionality across multiple platforms including Windows, Mac, iPad, and in a browser. +ms.date: 03/21/2023 +ms.topic: overview +ms.custom: scenarios:getting-started +ms.localizationpriority: high +--- + + +# Excel add-ins overview + +An Excel add-in allows you to extend Excel application functionality across multiple platforms including Windows, Mac, iPad, and in a browser. Use Excel add-ins within a workbook to: + +- Interact with Excel objects, read and write Excel data. +- Extend functionality using web based task pane or content pane +- Add custom ribbon buttons or contextual menu items +- Add custom functions +- Provide richer interaction using dialog window + +The Office Add-ins platform provides the framework and Office.js JavaScript APIs that enable you to create and run Excel add-ins. By using the Office Add-ins platform to create your Excel add-in, you'll get the following benefits. + +- **Cross-platform support**: Excel add-ins run in Office on the web, Windows, Mac, and iPad. +- **Centralized deployment**: Admins can quickly and easily deploy Excel add-ins to users throughout an organization. +- **Use of standard web technology**: Create your Excel add-in using familiar web technologies such as HTML, CSS, and JavaScript. +- **Distribution via AppSource**: Share your Excel add-in with a broad audience by publishing it to [AppSource](https://appsource.microsoft.com/marketplace/apps?product=office&page=1&src=office&corrid=53245fad-fcbe-41f8-9f97-b0840264f97c&omexanonuid=4a0102fb-b31a-4b9f-9bb0-39d4cc6b789d). + +> [!NOTE] +> Excel add-ins are different from COM and VSTO add-ins, which are earlier Office integration solutions that run only in Office on Windows. Unlike COM add-ins, Excel add-ins do not require you to install any code on a user's device, or within Excel. + +## Components of an Excel add-in + +An Excel add-in includes two basic components: a web application and a configuration file, called a manifest file. + +The web application uses the [Office JavaScript API](../reference/javascript-api-for-office.md) to interact with objects in Excel, and can also facilitate interaction with online resources. For example, an add-in can perform any of the following tasks. + +- Create, read, update, and delete data in the workbook (worksheets, ranges, tables, charts, named items, and more). +- Perform user authorization with an online service by using the standard OAuth 2.0 flow. +- Issue API requests to Microsoft Graph or any other API. + +The web application can be hosted on any web server, and can be built using client-side frameworks (such as Angular, React, jQuery) or server-side technologies (such as ASP.NET, Node.js, PHP). + +The [manifest](../develop/add-in-manifests.md) is a configuration file that defines how the add-in integrates with Office clients by specifying settings and capabilities such as: + +- The URL of the add-in's web application. +- The add-in's display name, description, ID, version, and default locale. +- How the add-in integrates with Excel, including any custom UI that the add-in creates (ribbon buttons, context menus, and so on). +- Permissions that the add-in requires, such as reading and writing to the document. + +To enable end users to install and use an Excel add-in, you must publish its manifest either to AppSource or to an add-ins catalog. For details about publishing to AppSource, see [Make your solutions available in AppSource and within Office](/office/dev/store/submit-to-appsource-via-partner-center). + +## Capabilities of an Excel add-in + +In addition to interacting with the content in the workbook, Excel add-ins can add custom ribbon buttons or menu commands, insert task panes, add custom functions, open dialog boxes, and even embed rich, web-based objects such as charts or interactive visualizations within a worksheet. + +### Add-in commands + +Add-in commands are UI elements that extend the Excel UI and start actions in your add-in. You can use add-in commands to add a button on the ribbon or an item to a context menu in Excel. When users select an add-in command, they initiate actions such as running JavaScript code, or showing a page of the add-in in a task pane. + +![Add-in commands in Excel.](../images/excel-add-in-commands-script-lab.png) + +For more information about command capabilities, supported platforms, and best practices for developing add-in commands, see [Add-in commands for Excel, Word, and PowerPoint](../design/add-in-commands.md). + +### Task panes + +Task panes are interface surfaces that typically appear on the right side of the window within Excel. Task panes give users access to interface controls that run code to modify the Excel document or display data from a data source. + +![Task pane add-in in Excel.](../images/excel-add-in-task-pane-insights.png) + +For more information about task panes, see [Task panes in Office Add-ins](../design/task-pane-add-ins.md). For a sample that implements a task pane in Excel, see [Excel Add-in JS WoodGrove Expense Trends](https://github.com/OfficeDev/Excel-Add-in-WoodGrove-Expense-Trends). + +### Custom functions + +Custom functions enable developers to add new functions to Excel by defining those functions in JavaScript as part of an add-in. Users within Excel can access custom functions just as they would any native function in Excel, such as `SUM()`. + +![Animated image showing an end user inserting the MYFUNCTION.SPHEREVOLUME custom function into a cell of an Excel worksheet.](../images/SphereVolumeNew.gif) + +For more information about custom functions, see [Create custom functions in Excel](custom-functions-overview.md). + +### Dialog boxes + +Dialog boxes are surfaces that float above the active Excel application window. You can use dialog boxes for tasks such as displaying sign-in pages that can't be opened directly in a task pane, requesting that the user confirm an action, or hosting videos that might be too small if confined to a task pane. To open dialog boxes in your Excel add-in, use the [Dialog API](/javascript/api/office/office.ui). + +![Add-in dialog box in Excel.](../images/excel-add-in-dialog-choose-number.png) + +For more information about dialog boxes and the Dialog API, see [Use the Dialog API in your Office Add-ins](../develop/dialog-api-in-office-add-ins.md). + +### Content add-ins + +Content add-ins are surfaces that you can embed directly into Excel documents. You can use content add-ins to embed rich, web-based objects such as charts, data visualizations, or media into a worksheet or to give users access to interface controls that run code to modify the Excel document or display data from a data source. Use content add-ins when you want to embed functionality directly into the document. + +![Content add-in in Excel.](../images/excel-add-in-content-map.png) + +For more information about content add-ins, see [Content Office Add-ins](../design/content-add-ins.md). For a sample that implements a content add-in in Excel, see [Excel Content Add-in Humongous Insurance](https://github.com/OfficeDev/Excel-Content-Add-in-Humongous-Insurance) in GitHub. + +## JavaScript APIs to interact with workbook content + +[!include[The roles of the Common and application-specific APIs](../includes/excel-api-models.md)] + +## Next steps + +Ready to enhance your productivity using Excel add-ins? Discover how to [extract contact data from an Excel spreadsheet to easily perform a mail merge](https://github.com/OfficeDev/Excel-Scenario-based-Add-in-Samples/tree/main/Mail-Merge-Sample-Add-in). + +When you're ready to explore creating your own solution, [build your first Excel add-in](../quickstarts/excel-quickstart-jquery.md). Then, learn more about [core concepts](excel-add-ins-core-concepts.md) to further extend the functionality of your add-in. + +## See also + +- [Office Add-ins platform overview](../overview/office-add-ins.md) +- [Learn about Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program) +- [Developing Office Add-ins](../develop/develop-overview.md) +- [Excel JavaScript object model in Office Add-ins](excel-add-ins-core-concepts.md) +- [Excel JavaScript API reference](../reference/overview/excel-add-ins-reference-overview.md) diff --git a/docs/overview/office-add-ins-experiment.md b/docs/overview/office-add-ins-experiment.md new file mode 100644 index 0000000000..398d93b0b3 --- /dev/null +++ b/docs/overview/office-add-ins-experiment.md @@ -0,0 +1,137 @@ +--- +title: Office Add-ins platform overview +description: Use familiar web technologies such as HTML, CSS, and JavaScript to extend and interact with Word, Excel, PowerPoint, OneNote, Project, and Outlook. +ms.date: 03/21/2023 +ms.topic: overview +ms.custom: scenarios:getting-started +ms.localizationpriority: high +--- + +# Office Add-ins platform overview + +You can use the Office Add-ins platform to build solutions that extend Office applications and interact with content in Office documents. With Office Add-ins, you can use familiar web technologies such as HTML, CSS, and JavaScript to extend and interact with Outlook, Excel, Word, PowerPoint, OneNote, and Project. Your solution can run in Office across multiple platforms, including Windows, Mac, iPad, and in a browser. + +![Office application plus an embedded website (add-in) make endless extensibility possibilities.](../images/addins-overview.png) + +Office Add-ins can do almost anything a webpage can do inside a browser. Use the Office Add-ins platform to: + +- **Add new functionality to Office clients** - Bring external data into Office, automate Office documents, expose functionality from Microsoft and others in Office clients, and more. For example, use Microsoft Graph API to connect to data that drives productivity. + +- **Create new rich, interactive objects that can be embedded in Office documents** - Embed maps, charts, and interactive visualizations that users can add to their own Excel spreadsheets and PowerPoint presentations. + +## How are Office Add-ins different from COM and VSTO add-ins? + +COM and VSTO add-ins are earlier Office integration solutions that run only in Office on Windows. Unlike COM and VSTO add-ins, Office Add-ins are web add-ins and don't involve code that runs on the user's device or in the Office client. For an Office Add-in, the application (for example, Excel), reads the add-in manifest and hooks up the add-in's custom ribbon buttons and menu commands in the UI. When needed, it loads the add-in's JavaScript and HTML code, which executes in the context of a browser or webview control in a sandbox. + +![A four-quadrant diagram showing the focus areas for different Office extensibility solutions. Office Web Add-ins along with COM and VSTO add-ins target professional developers, while VBA targets end users. Office Web Add-ins are focused on cross-platform experiences and collaboration while COM and VSTO add-ins and VBA cater to the individual's experience on Windows.](../images/office-programmability-diagram.png) + +Office Add-ins provide the following advantages over add-ins built using VBA, COM, or VSTO. + +- Cross-platform support: Office Add-ins run in Office on the web, Windows, Mac, and iPad. + +- Centralized deployment and distribution: Admins can deploy Office Add-ins centrally across an organization. + +- Easy access via AppSource: You can make your solution available to a broad audience by submitting it to AppSource. + +- Based on standard web technology: You can use any library you like to build Office Add-ins. + +![The reasons to use Office Add-ins: cross-platform, centralized deployment, easy access via AppSource, and built on standard web technologies.](../images/why.png) + +[!INCLUDE [new-outlook-vsto-com-support](../includes/new-outlook-vsto-com-support.md)] + +## Components of an Office Add-in + +An Office Add-in includes two basic components: an XML manifest file, and your own web application. The manifest defines various settings, including how your add-in integrates with Office clients. Your web application needs to be hosted on a web server, or web hosting service, such as Microsoft Azure. + +### Manifest + +The manifest is an XML file that specifies settings and capabilities of the add-in, such as: + +- The add-in's display name, description, ID, version, and default locale. + +- How the add-in integrates with Office.   + +- The permission level and data access requirements for the add-in. + +### Web app + +The most basic Office Add-in consists of a static HTML page that is displayed inside an Office application, but that doesn't interact with either the Office document or any other Internet resource. However, to create an experience that interacts with Office documents or allows the user to interact with online resources from an Office client application, you can use any technologies, both client and server side, that your hosting provider supports (such as ASP.NET, PHP, or Node.js). To interact with Office clients and documents, you use the Office.js JavaScript APIs. + +![Components of a Hello World add-in.](../images/about-addins-componentshelloworldoffice.png) + +## Extending and interacting with Office clients + +Office Add-ins can do the following within an Office client application. + +- Extend functionality (any Office application) + +- Create new objects (Excel or PowerPoint) + +### Extend Office functionality + +You can add new functionality to Office applications via the following:   + +- Custom ribbon buttons and menu commands (collectively called "add-in commands"). + +- Insertable task panes. + +Custom UI and task panes are specified in the add-in manifest.   + +#### Custom buttons and menu commands   + +You can add custom ribbon buttons and menu items to the ribbon in Office on the web and on Windows. This makes it easy for users to access your add-in directly from their Office application. Command buttons can launch different actions such as showing a task pane with custom HTML or executing a JavaScript function.   + +![Custom buttons and menu commands.](../images/about-addins-addincommands.png) + +#### Task panes   + +You can use task panes in addition to add-in commands to enable users to interact with your solution. Clients that don't support add-in commands (Office on iPad) run your add-in as a task pane. In Excel, Word, and PowerPoint, users launch task pane add-ins via the **Home** > **Add-ins** button. In Outlook, users launch task pane add-ins via the add-in button or via the **All Apps** button on the ribbon. + +![Use task panes in addition to add-in commands.](../images/about-addins-taskpane.png) + +### Extend Outlook functionality + +Outlook add-ins can extend the Office app ribbon and also display contextually next to an Outlook item when you're viewing or composing it. They can work with an email message, meeting request, meeting response, meeting cancellation, or appointment when a user is viewing a received item or replying or creating a new item. + +Outlook add-ins can access contextual information from the item, such as an address or tracking ID, and then use that data to access additional information on the server and from web services to create compelling user experiences. In most cases, an Outlook add-in runs without modification in the Outlook application to provide a seamless experience on the desktop, web, and tablet and mobile devices. + +For an overview of Outlook add-ins, see [Outlook add-ins overview](../outlook/outlook-add-ins-overview.md). + +### Create new objects in Office documents + +You can embed web-based objects called content add-ins within Excel and PowerPoint documents. With content add-ins, you can integrate rich, web-based data visualizations, media (such as a YouTube video player or a picture gallery), and other external content. + +![Embed web-based objects called content add-ins.](../images/about-addins-contentaddin.png) + +## Office JavaScript APIs + +The Office JavaScript APIs contain objects and members for building add-ins and interacting with Office content and web services. There's a common object model that's shared by Excel, Outlook, Word, PowerPoint, OneNote, and Project. There are also more extensive application-specific object models for Excel and Word. These APIs provide access to well-known objects such as paragraphs and workbooks, which makes it easier to create an add-in for a specific application. + +## Code samples + +Discover how Office Add-ins create solutions for content creation, better collaboration with peers, and task automation. Run the following samples to experience quick and easy real-life solutions in action. + +- [Add AI-generated content to your Word document](https://github.com/OfficeDev/Word-Scenario-based-Add-in-Samples/tree/main/Word-Add-in-AIGC) +- [Get data from an Excel spreadsheet for a mail merge](https://github.com/OfficeDev/Excel-Scenario-based-Add-in-Samples/tree/main/Mail-Merge-Sample-Add-in) +- [Create PowerPoint presentations with unique designs](../powerpoint/shapes.md) +- [Automatically insert a personalized signature in Outlook](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-set-signature) + +When you're ready to create your own solution, start with a simple "Hello World" add-in with only a manifest, HTML web page, and a logo. + +- [Excel "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/excel-hello-world) +- [Outlook "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/outlook-hello-world) +- [PowerPoint "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/powerpoint-hello-world) +- [Word "Hello world" add-in](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/hello-world/word-hello-world) + +## Next steps + +For a more detailed introduction to developing Office Add-ins, see [Develop Office Add-ins](../develop/develop-overview.md). + +## See also + +- [Core concepts for Office Add-ins](../overview/core-concepts-office-add-ins.md) +- [Develop Office Add-ins](../develop/develop-overview.md) +- [Design Office Add-ins](../design/add-in-design.md) +- [Test and debug Office Add-ins](../testing/test-debug-office-add-ins.md) +- [Publish Office Add-ins](../publish/publish.md) +- [Learn about the Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program) diff --git a/docs/word/word-add-ins-programming-overview-experiment.md b/docs/word/word-add-ins-programming-overview-experiment.md new file mode 100644 index 0000000000..8c538715a3 --- /dev/null +++ b/docs/word/word-add-ins-programming-overview-experiment.md @@ -0,0 +1,86 @@ +--- +title: Word add-ins overview +description: Learn the basics of Word add-ins. +ms.date: 02/24/2023 +ms.topic: overview +ms.custom: scenarios:getting-started +ms.localizationpriority: high +--- + +# Word add-ins overview + +Do you want to create a solution that extends the functionality of Word? For example, one that involves automated document assembly? Or a solution that binds to and accesses data in a Word document from other data sources? You can use the Office Add-ins platform, which includes the Word JavaScript API and the Office JavaScript API, to extend Word clients running on a Windows desktop, on a Mac, or in the cloud. + +Word add-ins are one of the many development options that you have on the [Office Add-ins platform](../overview/office-add-ins.md). You can use add-in commands to extend the Word UI and launch task panes that run JavaScript that interacts with the content in a Word document. Any code that you can run in a browser can run in a Word add-in. Add-ins that interact with content in a Word document create requests to act on Word objects and synchronize object state. + +[!INCLUDE [publish policies note](../includes/note-publish-policies.md)] + +The following figure shows an example of a Word add-in that runs in a task pane. + +*Figure 1. Add-in running in a task pane in Word* + +![Add-in running in a task pane in Word.](../images/word-add-in-show-host-client.png) + +The Word add-in can do the following: + + 1. Send requests to the Word document. + 1. Use JavaScript to access the paragraph object and update, delete, or move the paragraph. + +For example, the following code shows how to append a new sentence to that paragraph. + +```js +await Word.run(async (context) => { + const paragraphs = context.document.getSelection().paragraphs; + paragraphs.load(); + await context.sync(); + paragraphs.items[0].insertText(' New sentence in the paragraph.', + Word.InsertLocation.end); + await context.sync(); +}); + +``` + +You can use any web server technology to host your Word add-in, such as ASP.NET, NodeJS, or Python. Use your favorite client-side framework -- Ember, Backbone, Angular, React -- or stick with vanilla or plain JavaScript to develop your solution. You can also use services like Azure to [authenticate](../develop/overview-authn-authz.md) and host your application. + +The Word JavaScript APIs give your application access to the objects and metadata found in a Word document. You can use these APIs to create add-ins that target: + +* Word 2013 or later on Windows +* Word on the web +* Word 2016 or later on Mac +* Word on iPad + +Write your add-in once, and it will run in all versions of Word across multiple platforms. For details, see [Office client application and platform availability for Office Add-ins](/javascript/api/requirement-sets). + +## JavaScript APIs for Word + +You can use two sets of JavaScript APIs to interact with the objects and metadata in a Word document. The first is the [Common API](/javascript/api/office), which was introduced in Office 2013. Many of the objects in the Common API can be used in add-ins hosted by two or more Office clients. This API uses callbacks extensively. + +The second is the [Word JavaScript API](/javascript/api/word). This is an [application-specific API model](../develop/application-specific-api-model.md) that was introduced with Word 2016. It's a strongly-typed object model that you can use to create Word add-ins that target Word 2016 and later on Mac and on Windows. This object model uses promises and provides access to Word-specific objects like [body](/javascript/api/word/word.body), [content controls](/javascript/api/word/word.contentcontrol), [inline pictures](/javascript/api/word/word.inlinepicture), and [paragraphs](/javascript/api/word/word.paragraph). The Word JavaScript API includes TypeScript definitions and vsdoc files so that you can get code hints in your IDE. + +Currently, all Word clients support the shared Office JavaScript API, and most clients support the Word JavaScript API. For details about supported clients, see [Office client application and platform availability for Office Add-ins](/javascript/api/requirement-sets). + +We recommend that you start with the Word JavaScript API because the object model is easier to use. Use the Word JavaScript API if you need to do the following: + +* Access the objects in a Word document. + +Use the shared Office JavaScript API when you need to do any of the following: + +* Target Word 2013. +* Perform initial actions for the application. +* Check the supported requirement set. +* Access metadata, settings, and environmental information for the document. +* Bind to sections in a document and capture events. +* Open a dialog box. + +## Next steps + +Ready to enhance your productivity using Word add-ins? Discover how to [insert AI-generated content into a document](https://github.com/OfficeDev/Word-Scenario-based-Add-in-Samples/tree/main/Word-Add-in-AIGC). + +When you're ready to explore creating your own solution, [build your first Word add-in](../quickstarts/word-quickstart.md). Then, learn more about [core concepts](word-add-ins-core-concepts.md) to further extend the functionality of your add-in. + +## See also + +* [Developing Office Add-ins](../develop/develop-overview.md) +* [Learn about the Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program) +* [Office Add-ins platform overview](../overview/office-add-ins.md) +* [Word JavaScript API reference](../reference/overview/word-add-ins-reference-overview.md)