257 lines
7.1 KiB
Markdown
257 lines
7.1 KiB
Markdown
# 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:
|
|
```bash
|
|
git clone https://github.com/your-org/edison-powerpoint-addin.git
|
|
cd edison-powerpoint-addin
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Build the project:
|
|
```bash
|
|
npm run build:dev
|
|
```
|
|
|
|
4. Start the development server:
|
|
```bash
|
|
npm run dev-server
|
|
```
|
|
|
|
5. Start the add-in in PowerPoint:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```tsx
|
|
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
|
|
```typescript
|
|
const shapes = context.presentation.getSelectedShapes();
|
|
shapes.load("items");
|
|
await context.sync();
|
|
```
|
|
|
|
#### Working with Slide Masters
|
|
```typescript
|
|
const slideMasters = context.presentation.slideMasters;
|
|
slideMasters.load("items");
|
|
await context.sync();
|
|
```
|
|
|
|
#### Creating Shapes
|
|
```typescript
|
|
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:
|
|
```typescript
|
|
const {
|
|
statusMessage,
|
|
setStatusMessage,
|
|
statusType,
|
|
setStatusType,
|
|
isProcessing,
|
|
setIsProcessing
|
|
} = useStatusContext();
|
|
```
|
|
|
|
## Build and Deployment
|
|
|
|
### Development Build
|
|
```bash
|
|
npm run build:dev
|
|
```
|
|
|
|
### Production Build
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Manifest Validation
|
|
```bash
|
|
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](https://docs.microsoft.com/en-us/office/dev/add-ins/)
|
|
- [Office.js API Reference](https://docs.microsoft.com/en-us/javascript/api/overview/office)
|
|
- [Fluent UI Documentation](https://developer.microsoft.com/en-us/fluentui)
|
|
- [React Documentation](https://reactjs.org/docs/getting-started.html) |