Creating and Modifying Integration Scripts

This page explains how Hook communicates (“integrates”) with other apps to link their items to each other and to other apps’ items. It also explains how you can customize these integrations. There is a list of examples below.

How Hook works with your favorite apps

When Hook is invoked in the context of an app, like TextEdit, Hook calls its “integration script” for that app. Hook tries to get the name and the address of the foreground resource in the current app, using the Get Address and possibly the Get Name script for that app. (You’ll see below that the Get Address script can also return the name, using Markdown links.) Similarly, to create new items Hook uses its New Item script for that app.

Hook has a bundle of scripts for each of many apps. It also has some default scripts “under the hood”. That explains why Hook works with many apps that are not listed in the Scripts preferences tab. It also explains why some apps have a blank “New Item” and/or “Open Item” tab(s).

Customizing app integration with Hook’s Script editor (“Scripts” Preferences tab)

Hook Pro users can customize how Hook integrates with an app by editing Hook’s integration script for that app. They can also add new scripts to make Hook work with apps that are not yet supported by default by Hook.

The scripts can be written in AppleScript or JavaScript. Most of Hook’s integration scripts are exposed in Hook > Preferences > Scripts. Have a look for inspiration. These scripts make use of “AppleEvents” and other inter-app communication systems, such as “x-callback-url“. Hook can even interact via shell scripts (in macOS, AppleScript and JavaScript support calling shelling scripts).

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 app like Script Editor.app or the (highly recommended) Script Debugger and copy/paste them to the Hook Script Editor fields.

Integration scripts

There are up to four integration scripts per app:

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

1. Get Address

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

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 app 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 script will not run if Hook can obtain a name from the Address script, which happens if either the Address script returns a Markdown formatted link that contains both the name and address, or if it returns a file link (since the name of the file is included in the path).

Even apart from those cases, this script is not strictly required for linking. If Hook cannot get the name for a resource it will simply assign it the URL as its name.

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 app assigned to the file type. Many apps, 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 app 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 app and links it to the current context.

New Item runs when you select Hook 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

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

Tutorial examples: Things , Xcode, Agenda and More

Here are examples in the form of tutorials:

There are many other examples in the help pages and in the forum. Just search for your favorite app on this website to find them.

The links above contain all the information most advanced users will need. But you can also visit the Hook productivity forum or get in touch with us.

What if your favorite app lacks linking automation?

Sometimes, an app does not have an API (“application programming interface”, aka “automation”) for its items to be linked. Some of those apps are flagged on the Linkable Mac Apps – Hook.

In that case you can always contact the developer about improving their app with automation. That web page provides some boiler plate you can copy, paste and adapt to explain the issue to the developer.

Help Contents

Help > Integration :

Version 2.0 of Hook now available. Click here for more information.