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)

• Discover: Open Script Editor > File > Open Dictionary > Pages.

• Prototype: Write minimal AppleScript to verify the command works.

• 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).

• Optimize: Use batch text operations when possible to avoid performance penalties.

• 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)