urlevent

Last updated last month

Allows CommandPost to respond to URLs CommandPost is configured to react to URLs that start with commandpost:// when they are opened by OS X. This extension allows you to register callbacks for these URL events and their parameters, offering a flexible way to receive events from other applications.

You can also choose to make CommandPost the default for http:// and https:// URLs, which lets you route the URLs in your Lua code

Given a URL such as commandpost://someEventToHandle?someParam=things&otherParam=stuff, in the literal, RFC1808 sense of the URL, someEventToHandle is the hostname (or net_loc) of the URL, but given that these are not network resources, we consider someEventToHandle to be the name of the event. No path should be specified in the URL - it should consist purely of a hostname and, optionally, query parameters.

See also hs.ipc for a command line IPC mechanism that is likely more appropriate for shell scripts or command line use. Unlike hs.ipc, hs.urlevent is not able to return any data to its caller.

NOTE: If CommandPost is not running when a commandpost:// URL is opened, CommandPost will be launched, but it will not react to the URL event. Nor will it react to any events until this extension is loaded and event callbacks have been bound. NOTE: Any event which is received, for which no callback has been bound, will be logged to the CommandPost Console NOTE: When you trigger a URL from another application, it is usually best to have the URL open in the background, if that option is available. Otherwise, OS X will activate CommandPost (i.e. give it focus), which makes URL events difficult to use for things like window management.

API Overview

API Documentation

Variables

Signature

hs.urlevent.httpCallback

Type

Variable

Description

A function that should handle http:// and https:// URL events

Notes

Functions

bind

Signature

hs.urlevent.bind(eventName, callback)

Type

Function

Description

Registers a callback for a commandpost:// URL event

Parameters

Returns

Notes

Signature

hs.urlevent.getAllHandlersForScheme(scheme) -> table

Type

Function

Description

Gets all of the application bundle identifiers of applications able to handle a URL scheme

Parameters

Returns

Signature

hs.urlevent.getDefaultHandler(scheme) -> string

Type

Function

Description

Gets the application bundle identifier of the application currently registered to handle a URL scheme

Parameters

Returns

openURL

Signature

hs.urlevent.openURL(url)

Type

Function

Description

Opens a URL with the default application

Parameters

Returns

Signature

hs.urlevent.openURLWithBundle(url, bundleID) -> boolean

Type

Function

Description

Opens a URL with a specified application

Parameters

Returns

Signature

hs.urlevent.setDefaultHandler(scheme[, bundleID])

Type

Function

Description

Sets the default system handler for URLs of a given scheme

Parameters

Returns

Notes

Signature

hs.urlevent.setRestoreHandler(scheme, bundleID)

Type

Function

Description

Stores a URL handler that will be restored when CommandPost or reloads its config

Parameters

Returns

Notes