Initial commit of documentation files.
This commit is contained in:
@@ -0,0 +1,157 @@
|
||||
# Edison PowerPoint Add-in
|
||||
|
||||
A productivity toolkit that enhances PowerPoint with specialized formatting and content tools for creating professional presentations.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user