automating-pages

What this skill does

# Automating Pages (JXA-first, AppleScript discovery)

## Relationship to the macOS automation skill
- Standalone for Pages, aligned with `automating-mac-apps` patterns.
- Use `automating-mac-apps` for permissions, shell, and UI scripting guidance.
- **PyXA Installation:** To use PyXA examples in this skill, see the installation instructions in `automating-mac-apps` skill (PyXA Installation section).

## Core framing
- Pages dictionary is AppleScript-first; discover there.
- JXA provides the logic and data handling.
- **Objects are specifiers**: References to Pages elements that require methods for reads (e.g., `doc.body.text()`) and assignments for writes (e.g., `doc.body.text = 'new text'`).

### Example: Create Document
```javascript
const pages = Application('Pages');
const doc = pages.Document({templateName: 'Blank'});
pages.documents.push(doc);
doc.body.text = "Hello World";
```

## Workflow (default)
1) **Discover**: Open Script Editor > File > Open Dictionary > Pages.
2) **Prototype**: Write minimal AppleScript to verify the command works.
3) **Port to JXA**: Convert AppleScript syntax to JXA objects.
   - Example: `make new document` becomes `pages.documents.push(pages.Document())`.
   - Add error handling (try/catch blocks).
4) **Optimize**: Use batch text operations when possible to avoid performance penalties.
5) **Fallback**: Use AppleScript bridge or UI scripting for dictionary gaps (e.g., specific layout changes).

## Image Insertion (Critical Difference from Keynote)

**IMPORTANT**: Pages does **NOT** support direct image insertion like Keynote does:
```javascript
// THIS WORKS IN KEYNOTE:
Keynote.Image({ file: Path("/path/to/image.png"), position: {x: 100, y: 100} });

// THIS DOES NOT WORK IN PAGES!
Pages.Image({ file: Path("/path/to/image.png") }); // ❌ Will fail
```

**Solution**: Use ObjC Pasteboard bridging (see `pages-advanced.md` for details):
```javascript
ObjC.import('AppKit');
const nsImage = $.NSImage.alloc.initWithContentsOfFile("/path/to/image.png");
const pb = $.NSPasteboard.generalPasteboard;
pb.clearContents;
pb.setDataForType(nsImage.TIFFRepresentation, $.NSPasteboardTypeTIFF);
// Then use System Events to paste (Cmd+V)
```

**Example Script**: See `automating-pages/scripts/insert_images.js` for a complete working example.

## Common Pitfalls
- **Image insertion**: Pages lacks a native `Image` constructor unlike Keynote. Use ObjC Pasteboard method.
- **Dictionary gaps**: Some features (like sophisticated layout adjustments) aren't in the dictionary. Use the AppleScript bridge or UI scripting.
- **Permissions**: Ensure 'Accessibility' settings are enabled for UI scripting.
- **Saving**: Always use `doc.save({in: file_path})` with a valid path object.

## Validation Checklist
- [ ] Document opens without errors
- [ ] Text insertion and formatting succeeds
- [ ] Save operations complete with valid path objects
- [ ] Template application works if used
- [ ] Export to target format produces valid output (PDF, Word)
- [ ] Error handling covers missing files and permissions

## When Not to Use
- Cross-platform document automation (use python-docx or pandoc)
- AppleScript alone suffices (skip JXA complexity)
- Web-based documents (Google Docs API)
- Non-macOS platforms
- Complex page layout requiring manual design tools

## What to load
### Level 1: Basics
- JXA Pages basics: `automating-pages/references/pages-basics.md` (Core objects and document lifecycle)

### Level 2: Recipes & Common Tasks
- Recipes (templates, export, text): `automating-pages/references/pages-recipes.md` (Standard operations)
- Export options matrix: `automating-pages/references/pages-export-matrix.md` (PDF, Word, ePub formats)
- Template strategy: `automating-pages/references/pages-template-strategy.md` (Managing custom templates)

### Level 3: Advanced
- Advanced patterns (tables, images, AppleScript bridge): `automating-pages/references/pages-advanced.md` (Complex integrations)
- UI scripting patterns: `automating-pages/references/pages-ui-scripting.md` (Fallbacks)
- Dictionary translation table: `automating-pages/references/pages-dictionary.md` (AppleScript to JXA mapping)
- PyXA (Python) alternative: `automating-pages/references/pages-pyxa.md`

### Example Scripts
- Image insertion: `automating-pages/scripts/insert_images.js` (ObjC Pasteboard method for inserting images)