From f0773d93d875db37fc809e02da5453a1fa565ace Mon Sep 17 00:00:00 2001 From: Heiko Joerg Schick Date: Wed, 12 Mar 2025 20:10:39 +0100 Subject: [PATCH] Initial commit of documentation files. --- README.md | 157 +++++++++++++++++++++++++++ docs/DEVELOPERS.md | 257 +++++++++++++++++++++++++++++++++++++++++++++ docs/USER_GUIDE.md | 181 +++++++++++++++++++++++++++++++ 3 files changed, 595 insertions(+) create mode 100644 README.md create mode 100644 docs/DEVELOPERS.md create mode 100644 docs/USER_GUIDE.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..23709803 --- /dev/null +++ b/README.md @@ -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 \ No newline at end of file diff --git a/docs/DEVELOPERS.md b/docs/DEVELOPERS.md new file mode 100644 index 00000000..1bae471e --- /dev/null +++ b/docs/DEVELOPERS.md @@ -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 ( + + ); +}; + +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) \ No newline at end of file diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 00000000..c3878048 --- /dev/null +++ b/docs/USER_GUIDE.md @@ -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. \ No newline at end of file