Create Your First Add-in

Last Updated: October 26, 2023

Welcome to the world of add-in development! This tutorial will guide you through the process of creating a simple "Hello World" add-in for your application. By the end of this guide, you'll have a foundational understanding of the add-in architecture and how to build your first extension.

Prerequisites

Before you begin, ensure you have the following installed:

A supported version of the target application.
Node.js and npm (or yarn) installed on your system.
Basic knowledge of HTML, CSS, and JavaScript.
Familiarity with command-line interfaces.

Step 1: Set Up Your Development Environment

We'll use Yeoman to scaffold our add-in project. Yeoman provides a set of generators that help you quickly set up the basic structure for your add-in.

Open your terminal or command prompt.
Install the Yeoman generator for add-ins globally:
```
npm install -g yo generator-addin-template
```
Navigate to the directory where you want to create your project:
```
cd path/to/your/projects
```
Run the generator:
```
yo addin-template
```
Follow the prompts to configure your new add-in. You'll be asked for details like the add-in name, description, and target application.

Step 2: Explore the Project Structure

After the generator finishes, you'll have a new directory containing your add-in project. Let's look at some key files and folders:

manifest.xml: This is the heart of your add-in. It defines its metadata, permissions, and how it integrates with the host application.
src/: This directory contains your add-in's source code, including HTML, CSS, and JavaScript files.
- src/index.html: The main HTML file for your add-in's UI.
- src/styles.css: Your add-in's styles.
- src/script.js: The JavaScript logic for your add-in.
package.json: This file lists your project's dependencies and scripts.

Step 3: Develop Your Add-in's UI

Open src/index.html in your code editor. You'll see a basic HTML structure. Let's add a simple heading and a button.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Add-in</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <h1>Hello, World!</h1>
    <p>This is my first add-in.</p>
    <button id="greetButton">Say Hello</button>
    <script src="script.js"></script>
</body>
</html>

Now, open src/styles.css and add some basic styling.

body {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
    padding: 20px;
    background-color: #f0f0f0;
}
h1 {
    color: #0078d4;
}
button {
    background-color: #0078d4;
    color: white;
    border: none;
    padding: 10px 15px;
    border-radius: 4px;
    cursor: pointer;
    font-size: 1em;
    margin-top: 10px;
}
button:hover {
    background-color: #005a9e;
}

Step 4: Add Functionality with JavaScript

Open src/script.js. This is where you'll write the logic for your add-in. Let's make the button display an alert.

document.getElementById('greetButton').addEventListener('click', () => {
    alert('Hello from your first add-in!');
});

Important Note on APIs

For add-ins that interact with the host application's data or features (e.g., reading an email, accessing a document), you'll need to use the specific APIs provided by the host application. These are typically exposed through a JavaScript library. Refer to the API Reference for details.

Step 5: Build and Test Your Add-in

To test your add-in, you typically need to sideload it into the host application. The exact process varies depending on the application, but it usually involves:

Building your add-in for production. Run the following command in your project's root directory:
```
npm run build
```
Locating the generated add-in files (often in a dist/ folder).
Using the host application's developer tools to sideload the add-in using its manifest file (manifest.xml).

Refer to your specific application's documentation for detailed instructions on sideloading add-ins.

Tip: Local Development Server

Many generators include a command for starting a local development server (e.g., npm start or npm run dev) which often includes features like hot-reloading, making testing much faster.

Next Steps

Congratulations! You've successfully created and tested your first add-in. You can now explore more advanced topics:

Explore Advanced Features
Understand the API Reference thoroughly.
Learn about deployment and distribution options.

View Sample Code Back to Tutorials