This document first provides the background to Hookmark’s script editor. Then it describes the script editor itself.
The Scripts tab contains scripts that control how Hookmark interacts with your favorite apps, linking them together.
The Scripts tab is a Hookmark Pro feature. It is not shown in Standard mode of Hookmark.
Many apps work with Hookmark “out of the box”, and are not visible on this tab. For many other apps, Hookmark contains “integration script bundles” which are listed in the Apps pane on the left of this tab.
Background to Script Editor
If your favorite app is not yet supported by Hookmark, you can use Hookmark’s Scripts tab to copy and paste some AppleScript that does the trick. You can also press the “Update Built-in Scripts” button to get updated scripts from CogSci Apps that might do the trick.
The Scripts tab is for users who know AppleScript or JavaScript, or who wish to use AppleScript they receive from trusted sources. If you do not understand AppleScript, then do not use AppleScript unless it comes from a trusted source. (This recommendation applies also to Apple’s own Script Editor app, not just Hookmark). You can ask for input on the Hookmark forum.
Hookmark implicitly assumes an app is either “read-only” or “create-read-write”.
Read-only apps include web browsers, ebook readers, mail apps, and PDF readers. Yes, you can create emails, but that is irrelevant to Hookmark at the moment because their ID is not known until the message is sent.
Create-read-write apps are apps that can appear in the “Hook to New” menu. Those are apps in which you can create new files or objects. Most apps are of this type.
What Hookmark needs from apps
The primary function of Hookmark is linking. To do this Hookmark needs to be able to get the address (“URL” or “ID”) of the current app’s foreground resource. For example, to work with a web browser, Hookmark needs to get the address of the web page (resource) in the frontmost window (or tab). This is the bare minimum requirement.
It is very helpful (but not strictly required) for Hookmark to be able to get the name of the frontmost window’s resource, so that Hookmark can insert this name in links that it creates (whether Hookmark formats those links in Markdown, RTF or for presentation in the Hookmark window).
What Hookmark needs to be able to create new items depends on the type of app.
a. If it is a file-based app, Hookmark just needs a template for the app to be in the templates folder. As explained on the Notes Tab preferences help page, “Hook to New” then copies that template into the new folder, renames the file, and links the file to the foreground resource.
b. For database apps, Hookmark needs to be able to tell the app to create a new resource. Either Hookmark will instruct the app about what address (URL or ID) the new resource should have, or the app will return the address of the new resource.
AppleScript requirements of third-party apps
Hookmark mainly uses AppleScript to interact with third party apps. (For apps that lack the required AppleScript, like Firefox, Hookmark (also) does “UI scripting”, and may use other tricks.).
The AppleScript dictionary needs to support methods for the above. In sum, depending on the app, Hookmark may need a script (or standard macOS support) for:
a. opening an item (for most types of files, a script is not required)
b. getting the name of the foreground item
c. getting the address of the foreground item
d. creating a new item (with the “Hook to New” command)
The Scripts tab itself
This section describes the components of the Scripts tab, and how to use them.
The Scripts tab consists of:
- a list of scriptable applications on the left;
- a five-tab script editor panel on the right, where you can edit the script of a selected app; and
- scripts version information at the bottom (version number and date).
Apps pane
The Apps pane, on the left, presents a list of scriptable apps. That is a subset of all the apps in your /Applications folder, and elsewhere. The name and bundle of each app are presented together. When you select an app in this pane, the Script Pane (on right) displays its contents.
Hookmark comes with built-in scripts for many apps. However, you can customize these scripts with the Scripts tab (on the right). When you customize a built-in script, Hookmark places an asterisk (*) after its name.
Below the list of apps there are two checkboxes:
- The
Only show installed appscheckbox allows you to only see the apps that are on your Mac. - The
Hide default built-in scriptscheckbox allows you to focus on scripts that you have customized. (For most users, there will be no customized scripts.)
Script Editor pane
The Script Editor pane consists of 4 tabs (at the top) and a text editor pane. There is a tab for each scriptable function:
a. opening an item (for files a script is not required)
b. getting the name of the foreground item
c. getting the address of the foreground item
d. creating a new item (with the “Hook to New” command)
Just click on the tab to get to the script you’d like to edit.
You will notice in perusing the built-in scripts that not all tabs require text. When text is not provided, Hookmark uses a default mechanism to interact with the app. For example, if it is a file-based app, then Hookmark will simply open the file using a system call.
Don’t forget to save a script bundle when you are ready to deploy it, using the “Save” button.
If you wish to revert to a built-in script, just click the “Revert to Built-in Script” button. So please feel free to experiment with scripts knowing that you can easily roll back your changes.
NB: There will soon be an Export button so that you can save the selected script to a zip file.
Updating built-in scripts (bottom section)
Hookmark is capable of updating its scripts through communication with its script server. This update mechanism is separate from the process of updating the Hookmark app. This enables the updating of scripts to be more lightweight and frequent than updating the app. However, when you update the app, you also get the latest scripts.
Two methods are available to update Hookmark scripts:
- using the Check Now button on the Update pane; and
- by updating the entire Hookmark app.
If you edit a script or write your own custom scripts they will override Hookmark’s built-in scripts and will not be affected by any changes or updates. If you “Reset to Default” the scripts for an app, they will reset to the latest available version.
At the bottom of the Scripts pane, there is a label that indicates the date and time at which Hookmark’s scripts were last synced from the server.
Updating of the app and scripts is subject to the same overall Hookmark license agreement.
URL Scheme
The scheme field must be filled in if there is an Open Item script. Hookmark matches the scheme to URLs to open links to an application with the right Open Item script.
If the application can handle the URL natively (website URLs, Omnifocus and other applications which support URL schemes) then it doesn’t need an Open Item script and doesn’t need the scheme to be filled out.
The scheme is used to find the appropriate script to open URLs with.
Scheme should match the URL returned by Get Address which is formatted scheme://document-identifier.
How to write Hookmark integration scripts
If you’d like to learn more about creating or editing integration scripts, please check out the Integration page, which points to the Creating Integration Scripts page.