You can write or edit scripts to control how Hook behaves with different applications. For example, you could modify how Hook handles Things to link whole projects instead of individual TODOs, or you could change how Hook integrates with DevonThink, to behave more like Evernote.

The other reason to write your own Hook scripts is to create Hook integration for an application from scratch.

Integration scripting is done through the Script Editor pane. It is strongly suggested that users write and test the scripts in a dedicated Applescript editing application like Script Editor.app or the (highly recommended) Script Debugger and copy/paste them to the Hook Script Editor fields.

Integration scripts

There are four integration scripts:

1. Get Address
2. Get Name (which is now optional if the name is returned as part of the address)
3. Open Item
4. Link to New

1. Get Address

Returns a URL to identify and retrieve the document or resource or context with.

NB, it is possible to return a Markdown link that contains both the name and address of a link. In that case the name tab (script) can be left blank.

The built-in VoodooPad script is an example of this. It ends by returning a newly constructed Markdown link.

set theLink to "[" & theResult & "](x-voodoopad-item://" & theUUID & ")"
return theLink
end tell

Requirements

• The URL must be unique to each document. Different documents cannot share the same URL.
• A document must always produce the same URL, even if the document is moved, renamed, or edited.
• URL must be formed “scheme://document-identifier”
• Either the URL must open the document or else the Open Item script for the application must be able to parse the URL to open the document

Storing values in the clipboard

• Hook will save and restore the contents of your clipboard if this script writes over it.

2. Get Name (now optional)

Returns the title of the linked resource.

• If this script doesn’t exist or doesn’t return a value Hook will use the URL from Get URL as the title of the link.
• Hook will save and restore the contents of your clipboard if this script writes over it.

This tab can generally be left blank if the Address script returns a Markdown formatted link that contains both the name and address.

3. Open Item

Parses a URL to open the linked item.

Default behaviour

By default, if there is no Open Item script, Hook will pass the URL to macOS to open. If the URL retrieved by Get Address can be opened without assistance, an Open Item script is not required.

For example, links to websites and files are opened with the default web browser or the application assigned to the file type. Many applications, such as Omnifocus, Evernote, and Bear have their own scheme and can handle links to open documents without a custom Open Item script.

Scheme

Any application which has a custom Open Item script requires a scheme.

The scheme is part of the URL. It identifies the type of resource being opened and the app needed to open it. Hook uses the URL’s scheme to select which Open Item script to handle the link with.

Parse the URL to open the document

The Open Item script should either reformulate the URL into a valid URL and open it, or use the document-idenitifer portion of the URL to locate the document and open it.

Any instance of the string “$0” in the script will be replaced with the URL.

The URL is the same as is returned by Get Address and is formed scheme://document-identifier.

4. New Item

The “New Item” script creates a new item with the selected application and links it to the current context.

New Item runs when you select Link to New in the Hook window. This script is entirely optional and not necessary for the core Hook functionality of linking documents and resources.

The New Item script should

• create a new item,
• name the item after the current context,
• open the item, and
• return the URL of the new item

Any instance of “$title” will be replaced in the script by the title of the current document, to be used to name the new item

Applications which create files don’t need a Link to New Item script, it is easier and better just to put a file in the template folder.