powerpoint-toolbox/docs/DEVELOPERS.md

Edison PowerPoint Add-in Developer Documentation

This document provides detailed technical information for developers working on the Edison PowerPoint Add-in.

Architecture Overview

Edison is a PowerPoint add-in built with:

• TypeScript for type-safe code
• React for UI components
• Office.js API for PowerPoint integration
• Fluent UI for Microsoft-style interface components

The application follows a component-based architecture where each tool is encapsulated in its own React component.

Project Structure

/
├── assets/                  # Images and icons
├── dist/                    # Build output (generated)
├── src/
│   ├── commands/            # Command handlers
│   │   ├── commands.html    # HTML for command UI
│   │   └── commands.ts      # Command implementations
│   └── taskpane/            # Main add-in UI
│       ├── components/      # React components
│       │   ├── AlignmentButtons.tsx
│       │   ├── App.tsx      # Main application component
│       │   ├── ConfidentialButtons.tsx
│       │   ├── DraftButtons.tsx
│       │   ├── Header.tsx
│       │   ├── InsertTitles.tsx
│       │   ├── MatchProperties.tsx
│       │   ├── MatchSizes.tsx
│       │   ├── ProgressBarButtons.tsx
│       │   ├── RoundImage.tsx
│       │   ├── SwapPositions.tsx
│       │   └── commonStyles.tsx
│       ├── index.tsx        # Entry point
│       └── taskpane.html    # Main HTML container
├── babel.config.json        # Babel configuration
├── manifest.xml             # Add-in manifest
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
└── webpack.config.js        # Webpack configuration

Development Environment Setup

Prerequisites

• Node.js (LTS version recommended)
• npm
• Microsoft PowerPoint (desktop version)

Setup Steps

1. Clone the repository:

   git clone https://github.com/your-org/edison-powerpoint-addin.git
   cd edison-powerpoint-addin
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build:dev
   

4. Start the development server:

   npm run dev-server
   

5. Start the add-in in PowerPoint:

   npm run start
   

Local Development Certificates

Office Add-ins require HTTPS even for local development. The office-addin-dev-certs package is used to create and install self-signed certificates for development.

If you encounter certificate issues, run:

npx office-addin-dev-certs install

Component Development Guidelines

Creating a New Tool

1. Create a new component file in src/taskpane/components/
2. Import the necessary Office.js APIs and React hooks
3. Use the StatusContext for user feedback
4. Follow the pattern of existing components:
   • Use the PowerPoint.run() method for PowerPoint operations
   • Provide clear success/error messaging
   • Handle selection states appropriately

Example component structure:

import * as React from "react";
import { useState } from "react";
import { Button } from "@fluentui/react-components";
import { useStatusContext } from "./App";

const MyNewTool: React.FC = () => {
  const { setStatusMessage, setStatusType, isProcessing, setIsProcessing } = useStatusContext();

  const performAction = async () => {
    setIsProcessing(true);
    try {
      await PowerPoint.run(async (context) => {
        // Implement your PowerPoint operations here
        await context.sync();
      });
      setStatusMessage("Operation completed successfully!");
      setStatusType("success");
    } catch (error) {
      setStatusMessage(`Error: ${error.message}`);
      setStatusType("error");
      console.error("Operation error:", error);
    } finally {
      setIsProcessing(false);
    }
  };

  return (
    <Button onClick={performAction} disabled={isProcessing}>
      My New Tool
    </Button>
  );
};

export default MyNewTool;

Common PowerPoint.js Operations

Selecting Shapes

const shapes = context.presentation.getSelectedShapes();
shapes.load("items");
await context.sync();

Working with Slide Masters

const slideMasters = context.presentation.slideMasters;
slideMasters.load("items");
await context.sync();

Creating Shapes

const shape = slide.shapes.addGeometricShape("Rectangle");
shape.left = 100;
shape.top = 100;
shape.height = 50;
shape.width = 50;
await context.sync();

Status System

The application includes a status system that provides feedback to users:

• Success: Operation completed successfully
• Warning: Operation completed with concerns
• Error: Operation failed
• Processing: Shows a spinner while operations are in progress

Use the status context in your components:

const { 
  statusMessage, 
  setStatusMessage, 
  statusType, 
  setStatusType, 
  isProcessing, 
  setIsProcessing 
} = useStatusContext();

Build and Deployment

Development Build

npm run build:dev

Production Build

npm run build

Manifest Validation

npm run validate

This validates the manifest.xml file against the Office Add-in schema.

Testing

Currently, the project doesn't have automated tests. This is an area for future improvement.

Recommended testing approach:

1. Manual testing in PowerPoint
2. Implementation of unit tests for individual utilities
3. Integration tests for PowerPoint API interactions

Performance Considerations

• Minimize context.sync() calls, especially in loops
• Batch operations when possible
• Use memoization for expensive calculations
• Ensure proper cleanup of event listeners

Common Issues and Solutions

Add-in not loading in PowerPoint

• Verify the development server is running
• Check for certificate errors in the browser console
• Validate the manifest.xml file

PowerPoint API errors

• Ensure correct API version is being used
• Check the sequence of operations (some operations require specific order)
• Verify selections exist before operating on them

Best Practices

1. Error Handling: Always use try/catch blocks with PowerPoint API calls
2. User Feedback: Provide clear status messages for all operations
3. Accessibility: Ensure all UI elements have proper labels and keyboard access
4. Theme Support: Use Fluent UI theme tokens for consistent theming
5. Code Organization: Keep component files focused on a single responsibility

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request with a clear description of the changes

Resources

• Office Add-ins Documentation
• Office.js API Reference
• Fluent UI Documentation
• React Documentation