Shortcuts Actions

You can automate Hookmark using Apple’s Shortcuts app. Hookmark has an extensive list of actions with which you can copy links to the active window, add bookmarks to Hookmark, focus on a given bookmark, hook bookmarks together, and get your bookmarks. The uses of these actions are unlimited. They mean you can connect, create and access information anyway you like without even interacting with Hookmark’s user interface.

Check out our directory of Hookmark Shortcuts . They use Hookmark’s actions. These include Shortcuts we have created, and will include Shortcuts others have donated.

Shortcuts integration requires at least macOS 12 (Monterey) and Hookmark Pro version 3.8.

New to Shortcuts?

You can think of Hookmark’s actions, which are displayed in macOS Shortcuts app (and described below), as an “API” (application programming interface) to control Hookmark. It is equivalent to Hookmark’s AppleScript dictionary.

You can think of individual shortcuts as being user-friendly scripts, or “workflows”. In fact, Apple’s Shortcuts app is based on a product called “Workflows” that Apple acquired.

Hookmark’s Shortcuts Actions

Contents:

A. Hookmark’s objects:

B. Hookmark’s actions:

A. Hook Objects

1. Bookmark

Many Hookmark actions operate with Bookmark objects. These are links that can be stored in Hookmark. A Bookmark has the following fields.

  • a name
  • an address (URL) and
  • optionally a path. The path parameter is used specifically when the URL matches the hook://file/ pattern. (I.e., its scheme is hook and the “subscheme” is “file”).

2. Request Handle

A Request Handle is an object returned by Get bookmark from active window when the foreground app cannot immediately return the address (URL) and name of the foreground item. This is typically because the foreground app uses x-callback-url, an asynchronous protocol, rather than AppleScript. So an action cannot immediately get the bookmark; a two-step process is required.

The request handle may be used as input parameter to Hookmark’s Get Bookmark By Request Handle action.

B. Hookmark Actions

Action 1: Add Bookmark

Adds a bookmark to Hookmark with the given URL and name. If the name is not provided, the URL will be used as a name. If the URL is already in the database Hookmark will not add a bookmark. Thus (exceptions aside) this action returns a new or existing bookmark for the given URL. This means this action can be used as a “get bookmark” method (one that also can add a bookmark). However, this action cannot (yet) be used to change the name of an existing bookmark; thus, if a bookmark already exists for this URL, the name input parameter of this action will be ignored.

To be clear: also use this action whenever you want to get a Hookmark bookmark for a given URL. You can then feed this bookmark object into other actions.

Input parameters:

  • URL: a valid bookmark URL
  • Title: a non-empty title of a bookmark

Returns

  • A bookmark object

Exceptions:

  • Invalid sub-scheme. hook://file/ URLs are not supported by Shortcuts. If user tries to add a bookmark of the form hook://file/, Hookmark will return this message.

Action 2: Get Bookmark From Active Window

Returns a complex object containing either a valid bookmark or a request handle, and a value indicating the type of result that is returned.

Parameters: none

Returns

Returns an object with three three fields:

  1. bookmark: a bookmark object;
  2. request handle: a string to be used in Get bookmark by request handle action;
  3. is bookmark, a boolean value that indicates whether a bookmark object or a request handle is valid.

if is bookmark is true (1), then the bookmark field is valid, and the request handle field should be ignored.

if is bookmark is false (-1), then the bookmark field is invalid, and the request handle may be used to obtain a bookmark. If is bookmark is false (-1) then in order to get the bookmark from the active window, use Hookmark’s Get Bookmark By Request Handle with request handle as input parameter.

The two step-process is required for apps that use asynchronous protocols (like x-callback-url) for inter-app communication. Example: Agenda, Craft, Drafts, and Obsidian. However don’t need to concern yourself about this implementation detail ( x-callback-url), simply use the is bookmark value when appropriate.

If is bookmark is true then if the item is not yet bookmarked, Hookmark will bookmark it in the process, meaning it will add the bookmark to its database.

⚠️ After calling Get Bookmark From Active Window wait for 1s between calling Get Bookmark By Request Handle. This will give time for the x-callback-url app to return its result to Hookmark, and available to you.

Action 3: Get Bookmark By Request Handle

Given a request handle (which was returned by the prior Get bookmark from active window action), return a bookmark. I.e. return a bookmark for the item that was in active window last time the Get Bookmark From Active Window action returned a request handle.

NB: this is typically a bookmark for an app that uses x-callback-url.

Input parameters:

Returns

Exceptions

If there’s no request handle, an error message will be returned accordingly.

Action 4: Focus On Bookmark

Open Hookmark and focus on the given bookmark. That means Hookmark’s title bar will show the title of the bookmark, and its hooked items will be presented in the HOOKED section. However, if the bookmark already exists in Hookmark the name will be ignored.

Input parameter:

  • a bookmark

Returns Nothing.

Exceptions

An error message will be return if bookmark is missing or invalid.

Action 5: Hook Bookmarks Together

Hook two bookmarks given together.

Input parameters:

  • bookmark 1
  • bookmark 2

Returns: nothing.

Exceptions

Error messages: If the input is not a valid URL Hookmark will say

  • Input to bookmark1 is not a valid bookmark
  • Input to bookmark2 is not a valid bookmark

Action 6: Get Bookmarks Hooked To URL

Get a list containing all the bookmarks that are hooked to the URL.

Input parameters:

  • URL: URL of the bookmark.

Result: a list of bookmarks that are hooked to the given URL.

Exceptions

If there is no URL, Hookmark will ask for a valid URL.

Action 7: Unhook Bookmarks

Unhook the two given bookmarks from each other. This does not delete the bookmarks.

Input parameters:

  • bookmark 1: first bookmark
  • bookmark 2: second bookmark

Result: none.