# Run script on specific events in CotEditor on Mac scripts

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

- `document opened` : after you opened the file and then the contents were loaded
- `document saved` : after you saved the file and then the contents were stored

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 conform to the following protocols:

- written in AppleScript or JavaScript for Automation (JXA)
- stored in the form of a script bundle (.scptd)

In addition, events to subscribe to 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 the standard applications distributed with macOS.

To support scripting hooks, the list of events to subscribing must be written in `Contents/Info.plist`. Info.plist is a property list containing the metadata of the bundle and formatted in XML like 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

An event handler is a block to receive certain events that the application caused and do something with the received event. In this section, the manners to write an event handler are described with a 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
            write to console "Opened " & (theDocument's name)
        end document opened

        on document saved theDocument
            write to console "Saved " & (theDocument's name)
        end document saved
    end using terms from

### JavaScript for Automation (JXA)

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

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

    function documentOpened(document) {
      CotEditor.writeToConsole("Opened " + document.name())
    }

    function documentSaved(document) {
      CotEditor.writeToConsole("Saved " + document.name())
    }

## See also

- Script CotEditor
- Customize the Script menu
- Script CotEditor with AppleScript