ibz-04/gloamy/automating-pages

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

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:

// 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):

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)