# Adding scripting hooks for CotEditor scripts

Scripting hooks allows 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 was loaded
* `document saved`: after you saved the file and then the contents was 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 conforms to the following protocols:
- written in AppleScript or JavaScript for Automation (JXA)
- stored in the form of script bundle (`.scptd`)
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:

```plist
<?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`.

```plist
<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.

```applescript
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.

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

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

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