Edison/powerpoint-toolbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit of documentation files.

Browse Source
This commit is contained in:
Heiko Joerg Schick
2025-03-12 20:10:39 +01:00
parent 28b245f1fb
commit f0773d93d8
3 changed files with 595 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+157
View File
@@ -0,0 +1,157 @@
# Edison PowerPoint Add-in
A productivity toolkit that enhances PowerPoint with specialized formatting and content tools for creating professional presentations.
![Edison Add-in](assets/edison-128.png)
## Features
### Content Tools
- **Match Properties**: Copy visual properties (line style, fill color, text formatting) from the first selected shape to all other selected shapes.
- **Match Sizes**: Resize all selected shapes to match the dimensions of the first selected shape.
- **Swap Positions**: Swap the position of two selected shapes while maintaining their size and formatting.
- **Insert Titles**: Add slide titles to slides that are missing them.
- **Round Image**: Create circular images by generating an elliptical mask and selecting both shapes for intersection.
### Slide Enhancement Tools
- **Progress Bar**: Add or remove a visual progress indicator at the bottom of each slide showing the current position in the presentation.
- **Confidential Marking**: Add or remove a "Confidential" label to all slides in the presentation.
- **Draft Watermark**: Add or remove a "DRAFT" watermark on slide masters to mark in-progress presentations.
### Alignment Tools
- **Horizontal Alignment**: Align selected objects to the left, center, or right of the slide.
- **Vertical Alignment**: Align selected objects to the top, middle, or bottom of the slide.
## Installation
### For End Users
1. Download the latest release from the [Releases](https://github.com/your-org/edison-powerpoint-addin/releases) page.
2. Follow the installation instructions provided with the download.
3. Open PowerPoint and find the Edison add-in in the ribbon.
### For Developers
To set up the development environment:
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
```
4. Start the development server:
```
npm run start
```
## Development Guide
### Project Structure
- `/src/taskpane/components/` - React components for each tool
- `/src/commands/` - Command handlers for add-in functionality
- `/assets/` - Images and icons
### Key Development Commands
- `npm run build` - Build the project for production
- `npm run build:dev` - Build with development settings
- `npm run dev-server` - Start the development server
- `npm run lint` - Check code quality
- `npm run lint:fix` - Fix linting issues
- `npm run start` - Start the add-in in PowerPoint
- `npm run stop` - Stop the running add-in
- `npm run validate` - Validate the manifest file
### Creating New Tools
To add a new tool to the add-in:
1. Create a new component in `/src/taskpane/components/`
2. Follow the pattern of existing components, using the Office.js API for PowerPoint
3. Import and add your component to `App.tsx`
4. Update this documentation to include your new tool
## User Guide
### Getting Started
1. Open PowerPoint and navigate to the "Home" tab
2. Click on the "Edison Pane" button to open the add-in taskpane
3. The taskpane displays all available tools organized by category
### Using Content Tools
#### Match Properties
1. Select multiple shapes (the first shape is the source)
2. Click "Match Properties" in the Edison pane
3. All selected shapes will adopt the properties of the first selected shape
#### Match Sizes
1. Select multiple shapes (the first shape is the source)
2. Click "Match Sizes" in the Edison pane
3. All selected shapes will be resized to match the first selected shape
#### Swap Positions
1. Select exactly two shapes
2. Click "Swap Positions" in the Edison pane
3. The shapes will exchange positions while maintaining their size and formatting
#### Insert Titles
1. Click "Insert Titles" in the Edison pane
2. Slides without titles will have a title placeholder added
#### Round Image
1. Select an image
2. Click "Round Image" in the Edison pane
3. The image will be cropped to a circular shape
### Using Slide Enhancement Tools
#### Progress Bar
1. Click "Add Progress Bar" to add a progress indicator to all slides
2. Click "Remove Progress Bar" to remove the progress indicators
#### Confidential Marking
1. Click "Add Confidential" to add the confidential label to all slides
2. Click "Remove Confidential" to remove all confidential labels
#### Draft Watermark
1. Click "Add Draft" to add a DRAFT watermark to the slide masters
2. Click "Remove Draft" to remove all DRAFT watermarks
### Using Alignment Tools
1. Select one or more shapes
2. Click on the desired alignment button (Left, Center, Right, Top, Middle, Bottom)
3. All selected shapes will be aligned accordingly
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Version History
- v0.1.0 - Initial release with core functionality
docs/DEVELOPERS.md
+257
View File
@@ -0,0 +1,257 @@
# 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)
docs/USER_GUIDE.md
+181
View File
@@ -0,0 +1,181 @@
# Edison PowerPoint Add-in User Guide
This guide will help you use the Edison PowerPoint Add-in to create professional presentations quickly and efficiently.
![Edison Add-in](../assets/edison-128.png)
## Getting Started
### Installation
1. If Edison is not already installed, download it from the [Microsoft AppSource](https://appsource.microsoft.com) or follow the installation instructions provided by your organization.
2. Open PowerPoint and navigate to the "Home" tab in the ribbon.
3. Click on the "Edison Pane" button to open the add-in taskpane.
### Interface Overview
The Edison taskpane is organized into several sections:
- **Content** - Tools for manipulating content and shapes
- **Progress Bar** - Add/remove presentation progress indicators
- **Confidential Marking** - Add/remove confidential labels
- **Draft Watermark** - Add/remove draft watermarks
- **Alignment** - Tools for aligning shapes and objects
## Content Tools
### Match Properties
This tool copies visual properties from the first selected shape to all other selected shapes.
**How to use:**
1. Select multiple shapes (the shape you want to copy properties FROM should be selected FIRST)
2. Click the "Match Properties" button
3. All selected shapes will now have the same formatting properties as the first shape
**Properties matched include:**
- Fill color and transparency
- Line style, color, and weight
- Text formatting (if applicable)
- Shadow effects
### Match Sizes
This tool resizes all selected shapes to match the dimensions of the first selected shape.
**How to use:**
1. Select multiple shapes (the shape with the desired size should be selected FIRST)
2. Click the "Match Sizes" button
3. All selected shapes will be resized to match the first shape's width and height
### Swap Positions
This tool exchanges the positions of two selected shapes while maintaining their size and formatting.
**How to use:**
1. Select exactly two shapes
2. Click the "Swap Positions" button
3. The shapes will exchange positions
**Note:** This tool requires exactly two shapes to be selected.
### Insert Titles
This tool adds slide titles to slides that are missing them.
**How to use:**
1. Click the "Insert Titles" button
2. The add-in will scan your presentation and add title placeholders to any slides that don't have titles
**Note:** This affects all slides in the presentation, not just the current slide.
### Round Image
This tool creates circular images by applying a circular mask.
**How to use:**
1. Select an image
2. Click the "Round Image" button
3. The image will be cropped to a circular shape
## Slide Enhancement Tools
### Progress Bar
Adds or removes a visual progress indicator at the bottom of each slide showing the current position in the presentation.
**How to use:**
1. Click "Add Progress Bar" to add a progress indicator to all slides
2. Click "Remove Progress Bar" to remove all progress indicators
**Note:** The progress bar automatically updates as you navigate through the presentation.
### Confidential Marking
Adds or removes a "Confidential" label to all slides in the presentation.
**How to use:**
1. Click "Add Confidential" to add the confidential label to all slides
2. Click "Remove Confidential" to remove all confidential labels
**Note:** The confidential marking appears in the bottom-right corner of each slide.
### Draft Watermark
Adds or removes a "DRAFT" watermark on slide masters to mark in-progress presentations.
**How to use:**
1. Click "Add Draft" to add a DRAFT watermark to the slide masters
2. Click "Remove Draft" to remove all DRAFT watermarks
**Note:** This adds the watermark to slide masters, affecting all slides in the presentation.
## Alignment Tools
These tools align selected objects horizontally or vertically on the slide.
### Horizontal Alignment
**How to use:**
1. Select one or more shapes
2. Click one of the horizontal alignment buttons:
- **Left** - Aligns all shapes to the left edge
- **Center** - Centers all shapes horizontally
- **Right** - Aligns all shapes to the right edge
### Vertical Alignment
**How to use:**
1. Select one or more shapes
2. Click one of the vertical alignment buttons:
- **Top** - Aligns all shapes to the top edge
- **Middle** - Centers all shapes vertically
- **Bottom** - Aligns all shapes to the bottom edge
## Tips and Best Practices
### Selection Order Matters
For tools like Match Properties and Match Sizes, the **first** object you select is the source. Make sure to select the reference object first, then add other objects to your selection.
### Keyboard Shortcuts for Selection
- **Ctrl+Click** (Windows) or **Cmd+Click** (Mac) to select multiple objects
- **Shift+Click** to select a range of objects
- **Ctrl+A** (Windows) or **Cmd+A** (Mac) to select all objects on a slide
### Working with Progress Bars
- Add the progress bar near the end of your presentation development
- If you add or remove slides, you may need to remove and re-add the progress bar
### Draft Watermarks for Review Cycles
- Add the DRAFT watermark when sharing presentations for review
- Remove the watermark before final distribution
## Troubleshooting
### Common Issues
**The add-in shows an error message:**
- Ensure you've selected the appropriate objects for the tool you're using
- For tools that require multiple selections, verify you have the correct number of objects selected
**Changes aren't appearing:**
- Wait for the "Success" message to appear before continuing
- If using slide master features (like Draft Watermark), you may need to switch to normal view to see changes
**The add-in is slow or unresponsive:**
- For large presentations, some operations may take longer
- Wait for the current operation to complete before starting another
### Getting Help
If you encounter issues not covered in this guide, contact your IT department or the add-in administrator.
## Version Information
This user guide is for Edison PowerPoint Add-in v0.1.0.