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
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”.
- 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 Linkcommand should return the URL generated by the app. For example, OmniFocus provides a
Copy LinkAPI 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.)
- 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 Linkcommand should generate
hook://file/URLs in its context. BBEdit, OmniGraffle and OmniOutliner are examples amongst many.
- 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 Linkcommand may generate
hook://fileURLs. An example is the excellent personal information manager, EagleFiler. EagleFiler has a
Copy Linkfunction 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
- 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
- However, where Hook uses the
- 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://spotify/are examples of this.
- 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://emailis 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://emaillinks 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.
- 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.
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 Linkin 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://notes/(depricated scheme for Apple Notes.)
hook://outlook/note/. However, outlook’s IDs are not proper URLs.
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.