Creating and Modifying Integration Scripts

This page explains how Hookmark 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 Hookmark works with your favorite apps

When Hookmark is invoked in the context of an app (e.g. TextEdit), Hookmark calls its “integration script” for that app. Hookmark 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, Hookmark uses its New Item script for the app.

Hookmark’s default scripts work for many apps, but some apps require custom scripts, which is what you see listed in Hookmark’s Scripts tab.
Some apps with entries in the Scripts tab have blank “New Item” and/or “Open Item” tab(s), because the default scripts work in those specific cases.

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

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

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

Integration scripting is done through the Script Editor pane. It is strongly suggested that users write and test their scripts in a dedicated Applescript editing app like Script Editor.app or the (highly recommended) Script Debugger and copy/paste them to the Hookmark 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 as “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

Hookmark 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, Hookmark will use the URL from Get URL as the title of the link.
  • Hookmark will save and restore the contents of your clipboard if this script writes over it.

This script will not run if Hookmark can obtain a name from the Address script, which happens if the Address script returns a Markdown formatted link that contains both the name and address, or 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 Hookmark 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, Hookmark 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. Hookmark 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 as 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 Hookmark window. This script is entirely optional and not necessary for the core Hookmark 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 more useful just to put a file in the template folder.

Tutorial examples: Things, Xcode, Agenda and more

Here are some examples in the form of tutorials:

There are many other examples in the help pages and on the Hookmark forum.

The links above contain all the information most advanced users will need. But you can also visit the Hookmark 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 page.

In that case you can always contact the developer about improving their app with automation. That web page provides some boilerplate you can copy, paste, and adapt to explain the issue to the developer in an email or forum post.

See also

See also: Principles That Determine the URL Scheme Returned by Copy Link for a Given App.