Principles That Determine the URL Scheme Returned by `Copy Link` for a Given App

When you call Copy Link on a linkable item in a given app, Hook returns a link consisting of the item’s name and an address (URL) to access that item. Hook will use the custom scheme for the app, shown in its Scripts preferences pane, or the default script (also shown in that pane). This document describes the rules that determine the scheme of the URLs returned by default by Hook for items of a given app or service — for example, whether it is a hook:// URL scheme, the app’s native URL scheme (such as OmniFocus://), or some other URL scheme. This also lists Hook’s custom sub-schemes.

The first thing to note is that for any given app with which Hook can integrate, Hook Pro users can configure the URLs that are returned by Hook via Hook’s > Preferences’ > Scripts’ tab. This means that users are not bound to Hook’s defaults. The current document, then, discusses the URL schemes that may by default be returned by Hook’s Copy Link.

Principles for selection of the URL scheme returned by Hook

This section describes the principles used by CogSci Apps for determining the scheme of URLs returned by Copy Link (and Copy Markdown Link). The expression “in the context of this app” means “when Hook is invoked while this app is in the foreground of macOS”.

  1. If an app offers a way to generate URLs to its resources and if the app robustly serves its URLs, then in the context of this app, Hook’s Copy Link command should return the URL generated by the app. For example, OmniFocus provides a Copy Link API that returns links with OmniFocus:// URLs. OmniFocus robustly serves OmniFocus:// URLs. So Hook uses them. (FYI: in the majority of cases where an app programmatically serves a URL scheme, Hook uses it.)
  2. If an app’s resources are Finder manipulatable files, and the app can open its files directly but does not have its own URL scheme, then in the context of this app, Hook’s Copy Link command should generate hook://file/ URLs in its context. BBEdit, OmniGraffle and OmniOutliner are examples amongst many.
  3. If an app can generate its own URLs but cannot necessarily serve them robustly (particularly in the case where the file is modified by the user directly on the Finder), then if the app does not use its URLs in a mobile setting, then (other things being equal), in the context of this app, Hook’s Copy Link command may generate hook://file URLs. An example is the excellent personal information manager, EagleFiler. EagleFiler has a Copy Link function that generates x-eaglefiler://open?… URLs. Files in EagleFiler are directly accessible on Finder, but moving them directly on Finder (outside EagleFiler) breaks their URLs. (See also Other considerations.) In addition, EagleFiler users often open these items in a third party app (e.g., an external PDF reader) where the EagleFiler URLs of these items are not available; so in this case, Hook by default generates a hook://file/ URL.
    • However, where Hook uses the hook://file/ scheme for such an app, CogSci Apps may publish an alternative integration script bundle whose ‘get address’ script returns a URL in the app’s native URL scheme (e.g., x-eaglefiler://open?…). This is what CogSci Apps did for EagleFiler and Curio. Hook Pro users can copy and paste the published integration bundle into Hook’s script for the app.. This means that Pro users can easily configure Hook to return URLs in the app’s native scheme or the hook://file/ scheme.
  4. If an app cannot generate URLs to its resources but does provide some means of identifying its resources, Hook may create URLs of the form hook://<app-specific-sub-scheme>, where the sub-scheme is specific to the app. hook://outlook/ , hook://notes and hook://spotify/ are examples of this.
  5. For groups of related apps that can, in principle, open the “same” information resource, but that cannot generate or consume URLs of a generic format, Hook may define a generic scheme of the form hook://<function-specific-sub-scheme>. hook://email is an example: compatible email apps (Apple Mail, MailMate , Airmail 3, etc.) all provide an API to get the current email’s RFC compliant ID, and to open emails by this ID but do not provide a generic URL. Because macOS does not provide a standard configuration for email (unlike for web browsers), Hook creates hook://email links and serves these links by translating them the links to the email app specified (in Hook) as the default for such links. See favorite apps.
  6. Hook may also provide schemes for additional services and functions it provides. hook://search/ is a prime example of this. These links may be manually created by users or automatically by software. Activating these links triggers a Spotlight search for files that match the search criteria.

Qualifications

The above are simply principles. Please note:

  • Other specific considerations may be pertinent to particular apps and hence affect the scheme of URLs Hook returns. They may be discussed in our documentation for the specific apps, and added to future revisions of this document.
  • Ultimately, to see how Hook returns URLs for a particular app, the user may try Hook’s Copy Link in the context of that app, examine the script for the app in the Script Editor pane, and/or visit the documentation about the app on this website (including the Hook productivity forum).
  • As noted above, if they wish, users can configure Hook, via the app’s “get address” script, to return a different URL scheme from the one provided in the Hook app.

Custom hook:// sub-schemes

Like many other apps, Hook defines a scheme of its own. It is hook://. Hook supports a particularly rich collection of sub-schemes, most of which were mentioned above.

  • hook://search/ : triggers a Spotlight search
  • hook://file/ : for linking to files on Finder.
  • hook://email/ : for linking to emails in an email-client agnostic way (based on RFC email ID)
  • hook://ical/
  • hook://macJournal/
  • hook://notes/ (depricated scheme for Apple Notes.)
  • hook://outlook/ , hook://outlook/task/ and hook://outlook/note/. However, outlook’s IDs are not proper URLs.
  • hook://slack/
  • hook://spotify/
  • hook://tbx/ (for accessing Tinderbox items).

Other sub-schemes may be defined in the future.

This section will be augmented with links to the web pages that discuss the specific sub-schemes. Meanwhile, try searching the documentation or forum — using a search engine or 🔍 glass above.