Adding scripting hooks for CotEditor scripts

Scripting hooks allows CotEditor scripts to be executed on certain events. The following events are available with CotEditor:

See `CotEditor Event Handler suite` section on AppleScript Dictionary for further information.

The rest of this page describes how to include the script hooking to your CotEditor script.

Synopsis

Scripts with scripting hook must conforms to the following protocols:

In addition, events to subscribe and handlers for them must be declared, as described below.

Structure of Script Bundle

A script bundle is the directory structure as follows:

HookingScript.scptd
└── Contents
    ├── Info.plist
    └── Resources
        ├── Script Libraries
        │   └── my-fancy-library.scpt
        ├── Scripts
        │   └── main.scpt
        └── description.rtfd
            └── TXT.rtf

Any scripts can be exported in this form with Script Editor.app, which is one of standard applications distributed with macOS.

To support scripting hooks, the list of events to subscribe must be written in `Contents/Info.plist`. `Info.plist` is a property list containing the metadata of the bundle and formatted in XML as the following example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleIdentifier</key>
    <string>com.coteditor.hooking-script</string>
    <key>CFBundleName</key>
    <string>Hooking Script</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
  </dict>
</plist>

The events to subscribe must be stored at the key `CotEditorHandlers` and in the form of `array` of `string`.

<key>CotEditorHandlers</key>
<array>
  <string>document opened</string>
  <string>document saved</string>
</array>

Event Handlers

A event handler is the block to receive certain events which the application caused and do something with the received event. In this section, the manners to write an event handler are described with the simple example, which shows the dialog on opening and saving a file.

AppleScript

In AppleScript, handlers are written with a `using terms from` block and `on` blocks.

using terms from application "CotEditor"
    on document opened theDocument
        set thePath to file of theDocument
        display alert "Opened " & thePath
    end document opened

    on document saved theDocument
        set thePath to file of theDocument
        display alert "Saved " & thePath
    end document saved
end using terms from

JavaScript for Automation (JXA)

In JXA, `function` statements on the global object will create handlers.

CotEditor = Application.currentApplication()
CotEditor.includeStandardAdditions = true

function documentOpened(document) {
  CotEditor.displayAlert("Opened " + document.file().toString())
}

function documentSaved(document) {
  CotEditor.displayAlert("Saved " + document.file().toString())
}

See also