URL Templates Engine

The URL templates engine (URLTemplateAction) powers instant web search, documentation lookup, and custom URI scheme deep-linking actions.

Execution Mechanism#

When a user selects a URL template action:

1. Text Extraction: Selected text is trimmed of leading and trailing whitespace.
2. Placeholder Substitution: TextPlaceholderEngine substitutes template tokens with percent-encoded query parameters.
3. URL Resolution: The resulting string is parsed into a URL object and returned as ActionResult.openURL(url).
4. Platform Launch: DefaultActionResultHandler opens the URL via NSWorkspace.shared.open(url).

Supported Placeholders#

TextPlaceholderEngine replaces the following template tokens:

Regex Pattern Gating & Visibility Rules#

URL template actions support regex gating (via regexPattern or ExtensionActionRules). When evaluated, enablement and capture extraction delegate to ActionVisibility:

@MainActor
public func isEnabled(for context: ActionContext) -> Bool {
    guard let rules else {
        return ActionVisibility.isEnabled(
            requirements: nil,
            legacyRegex: regexPattern,
            context: context
        ).enabled
    }
    return rules.resolveVisibility(for: context).enabled
}

Common Regex Examples#

• Match URLs Only: ^https?://\\S+$
• Match Issue Tracker Numbers: ^#[0-9]+$ or ^[A-Z]+-[0-9]+$
• Match IP Addresses: ^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$

Practical Examples#

{
 "id": "builtin.search.google",
 "title": "Search Google",
 "icon": "symbol:magnifyingglass",
 "url": "https://www.google.com/search?q={query}"
}

{
 "id": "action.github.repo",
 "title": "Open GitHub Repo",
 "icon": "symbol:book",
 "url": "https://github.com/{query}",
 "regex": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
}