usercontent

​
This module provides support for injecting custom JavaScript user content into your webviews and for JavaScript to post messages back to Hammerspoon.
API Overview
Constructors - API calls which return an object, typically one that offers API methods
​new​
Methods - API calls which can only be made on an object returned by a constructor
​injectScript​
​removeAllScripts​
​setCallback​
​userScripts​
API Documentation
Constructors
​new​
Signature
hs.webview.usercontent.new(name) -> usercontentControllerObject
Type
Constructor
Description
Create a new user content controller for a webview and create the message port with the specified name for JavaScript message support.
Parameters
name - the name of the message port which JavaScript in the webview can use to post messages to Hammerspoon.
Returns
the usercontentControllerObject
Notes
This object should be provided as the final argument to the hs.webview.new constructor in order to tie the webview to this content controller. All new windows which are created from this parent webview will also use this controller.
See hs.webview.usercontent:setCallback for more information about the message port.
Methods
​injectScript​
Signature
hs.webview.usercontent:injectScript(scriptTable) -> usercontentControllerObject
Type
Method
Description
Add a script to be injected into webviews which use this user content controller.
Parameters
scriptTable - a table containing the following keys which define the script and how it is to be injected:
source - the javascript which is injected (required)
mainFrame - a boolean value which indicates whether this script is only injected for the main webview frame (true) or for all frames within the webview (false). Defaults to true.
injectionTime - a string which indicates whether the script is injected at "documentStart" or "documentEnd". Defaults to "documentStart".
Returns
the usercontentControllerObject or nil if the script table was malformed in some way.
​removeAllScripts​
Signature
hs.webview.usercontent:removeAllScripts() -> usercontentControllerObject
Type
Method
Description
Removes all user scripts currently defined for this user content controller.
Parameters
None
Returns
the usercontentControllerObjectNotes:
The WKUserContentController class only allows for removing all scripts. If you need finer control, make a copy of the current scripts with hs.webview.usercontent.userScripts() first so you can recreate the scripts you want to keep.
Notes
The WKUserContentController class only allows for removing all scripts. If you need finer control, make a copy of the current scripts with hs.webview.usercontent.userScripts() first so you can recreate the scripts you want to keep.
​setCallback​
Signature
hs.webview.usercontent:setCallback(fn) -> usercontentControllerObject
Type
Method
Description
Set or remove the callback function to handle message posted to this user content's message port.
Parameters
fn - The function which should receive messages posted to this user content's message port. Specify an explicit nil to disable the callback. The function should take one argument which will be the message posted and any returned value will be ignored.
Returns
the usercontentControllerObject
Notes
Within your (injected or served) JavaScript, you can post messages via the message port created with the constructor like this:
​userScripts​
Signature
hs.webview.usercontent:userScripts() -> array
Type
Method
Description
Get a table containing all of the currently defined injection scripts for this user content controller
Parameters
None
Returns
An array of injected user scripts. Each entry in the array will be a table containing the following keys:
source - the javascript which is injected
mainFrame - a boolean value which indicates whether this script is only injected for the main webview frame (true) or for all frames within the webview (false)
injectionTime - a string which indicates whether the script is injected at "documentStart" or "documentEnd".
Notes
Because the WKUserContentController class only allows for removing all scripts, you can use this method to generate a list of all scripts, modify it, and then use it in a loop to reapply the scripts if you need to remove just a few scripts.

Last modified 1yr ago

Signature	`hs.webview.usercontent.new(name) -> usercontentControllerObject`
Type	Constructor
Description	Create a new user content controller for a webview and create the message port with the specified name for JavaScript message support.
Parameters	name - the name of the message port which JavaScript in the webview can use to post messages to Hammerspoon.
Returns	the usercontentControllerObject
Notes	This object should be provided as the final argument to the `hs.webview.new` constructor in order to tie the webview to this content controller. All new windows which are created from this parent webview will also use this controller. See `hs.webview.usercontent:setCallback` for more information about the message port.

Signature	`hs.webview.usercontent:injectScript(scriptTable) -> usercontentControllerObject`
Type	Method
Description	Add a script to be injected into webviews which use this user content controller.
Parameters	scriptTable - a table containing the following keys which define the script and how it is to be injected: source - the javascript which is injected (required) mainFrame - a boolean value which indicates whether this script is only injected for the main webview frame (true) or for all frames within the webview (false). Defaults to true. injectionTime - a string which indicates whether the script is injected at "documentStart" or "documentEnd". Defaults to "documentStart".
Returns	the usercontentControllerObject or nil if the script table was malformed in some way.

Signature	`hs.webview.usercontent:removeAllScripts() -> usercontentControllerObject`
Type	Method
Description	Removes all user scripts currently defined for this user content controller.
Parameters	None
Returns	the usercontentControllerObjectNotes: The WKUserContentController class only allows for removing all scripts. If you need finer control, make a copy of the current scripts with `hs.webview.usercontent.userScripts()` first so you can recreate the scripts you want to keep.
Notes	The WKUserContentController class only allows for removing all scripts. If you need finer control, make a copy of the current scripts with `hs.webview.usercontent.userScripts()` first so you can recreate the scripts you want to keep.

Signature	`hs.webview.usercontent:setCallback(fn) -> usercontentControllerObject`
Type	Method
Description	Set or remove the callback function to handle message posted to this user content's message port.
Parameters	fn - The function which should receive messages posted to this user content's message port. Specify an explicit nil to disable the callback. The function should take one argument which will be the message posted and any returned value will be ignored.
Returns	the usercontentControllerObject
Notes	Within your (injected or served) JavaScript, you can post messages via the message port created with the constructor like this:

Signature	`hs.webview.usercontent:userScripts() -> array`
Type	Method
Description	Get a table containing all of the currently defined injection scripts for this user content controller
Parameters	None
Returns	An array of injected user scripts. Each entry in the array will be a table containing the following keys: source - the javascript which is injected mainFrame - a boolean value which indicates whether this script is only injected for the main webview frame (true) or for all frames within the webview (false) injectionTime - a string which indicates whether the script is injected at "documentStart" or "documentEnd".
Notes	Because the WKUserContentController class only allows for removing all scripts, you can use this method to generate a list of all scripts, modify it, and then use it in a loop to reapply the scripts if you need to remove just a few scripts.

usercontent

API Overview

API Documentation

Constructors

​new​

Methods

​injectScript​

​removeAllScripts​

​setCallback​

​userScripts​

new

injectScript

removeAllScripts

setCallback

userScripts