webview

​
Display web content in a window from Hammerspoon
This module uses Apple's WebKit WKWebView class to provide web content display with JavaScript injection support. The objective is to provide a functional interface to the WKWebView and WKUserContentController classes.
This module is not intended to replace a full web browser and does have some limitations to keep in mind:
Self-signed SSL certificates are not accepted unless they have first been approved and included in the users Keychain by another method, for example, opening the page first in Safari.
The context-menu (right clicking or ctrl-clicking in the webview) provides some menu items which are currently unsupported -- a known example of this is any "Download..." menu item in the context menu for links and images.
It is uncertain at present exactly how or where cookies and cached page data is stored or how it can be invalidated.
This can be mitigated to an extent for web requests by using hs.webview:reload(true) and by crafting the url for hs.webview:url({...}) as a table -- see the appropriate help entries for more information.
Any suggestions or updates to the code to address any of these or other limitations as they may become apparent are welcome at the Hammerspoon github site: https://www.github.com/Hammerspoon/hammerspoon
Submodules
​hs.webview.datastore​
​hs.webview.toolbar​
​hs.webview.usercontent​
API Overview
Deprecateds - API features which will be removed in an future release
​asHSDrawing​
​asHSWindow​
​setLevel​
Constants - Useful values which cannot be changed
​certificateOIDs​
​windowMasks​
Functions - API calls offered directly by the extension
​titleVisibility​
Constructors - API calls which return an object, typically one that offers API methods
​new​
​newBrowser​
Methods - API calls which can only be made on an object returned by a constructor
​allowGestures​
​allowMagnificationGestures​
​allowNavigationGestures​
​allowNewWindows​
​allowTextEntry​
​alpha​
​attachedToolbar​
​behavior​
​behaviorAsLabels​
​bringToFront​
​certificateChain​
​children​
​closeOnEscape​
​darkMode​
​delete​
​deleteOnClose​
​estimatedProgress​
​evaluateJavaScript​
​examineInvalidCertificates​
​frame​
​goBack​
​goForward​
​hide​
​historyList​
​hswindow​
​html​
​isOnlySecureContent​
​isVisible​
​level​
​loading​
​magnification​
​navigationCallback​
​navigationID​
​orderAbove​
​orderBelow​
​parent​
​policyCallback​
​privateBrowsing​
​reload​
​sendToBack​
​shadow​
​show​
​size​
​sslCallback​
​stopLoading​
​title​
​topLeft​
​transparent​
​url​
​urlParts​
​userAgent​
​windowCallback​
​windowStyle​
​windowTitle​
API Documentation
Deprecateds
​asHSDrawing​
Signature
hs.webview:asHSDrawing() -> hs.drawing object
Type
Deprecated
Description
Because use of this method can easily lead to a crash, useful methods from hs.drawing have been added to the hs.webview module itself. If you believe that a useful method has been overlooked, please submit an issue.
Parameters
None
Returns
a placeholder object
​asHSWindow​
Signature
hs.webview:asHSWindow() -> hs.window object
Type
Deprecated
Description
Returns an hs.window object for the webview so that you can use hs.window methods on it.
​setLevel​
Signature
hs.webview:setLevel(theLevel) -> drawingObject
Type
Deprecated
Description
Deprecated; you should use hs.webview:level instead.
Parameters
theLevel - the level specified as a number, which can be obtained from hs.drawing.windowLevels.
Returns
the webview object
Notes
see the notes for hs.drawing.windowLevels
Constants
​certificateOIDs​
Signature
hs.webview.certificateOIDs[]
Type
Constant
Description
A table of common OID values found in SSL certificates. SSL certificates provided to the callback function for hs.webview:sslCallback or in the results of hs.webview:certificateChain use OID strings as the keys which describe the properties of the certificate and this table can be used to get a more common name for the keys you are most likely to see.
​windowMasks​
Signature
hs.webview.windowMasks[]
Type
Constant
Description
A table containing valid masks for the webview window.
Notes
The Maximize button in the window title is enabled when Resizable is set.
The Close, Minimize, and Maximize buttons are only visible when the Window is also Titled.
Functions
​titleVisibility​
| Signature | hs.webview:titleVisibility([state]) -> webviewObject | string | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Get or set whether or not the title text appears in the webview window. | | Parameters |
state - an optional string containing the text "visible" or "hidden", specifying whether or not the webview's title text appears when webview's window style includes "titled".
| | Returns |
if a value is provided, returns the webview object; otherwise returns the current value.
| | Notes |
See also hs.webview:windowStyle and hs.webview.windowMasks.
|
Constructors
​new​
Signature
hs.webview.new(rect, [preferencesTable], [userContentController]) -> webviewObject
Type
Constructor
Description
Create a webviewObject and optionally modify its preferences.
Parameters
rect - a rectangle specifying where the webviewObject should be displayed.
preferencesTable - an optional table which can include one of more of the following keys:
javaEnabled - java is enabled (default false)
javaScriptEnabled - JavaScript is enabled (default true)
javaScriptCanOpenWindowsAutomatically - can JavaScript open windows without user intervention (default true)
minimumFontSize - minimum font size (default 0.0)
plugInsEnabled - plug-ins are enabled (default false)
developerExtrasEnabled - include "Inspect Element" in the context menu
suppressesIncrementalRendering - suppresses content rendering until fully loaded into memory (default false)
The following additional preferences may also be set under OS X 10.11 or later (they will be ignored with a warning printed if used under OS X 10.10):
applicationName - a string specifying an application name to be listed at the end of the browser's USER-AGENT header. Note that this is only appended to the default user agent string; if you set a custom one with hs.webview:userAgent, this value is ignored.
allowsAirPlay - a boolean specifying whether media playback within the webview can play through AirPlay devices.
datastore - an hs.webview.datastore object specifying where website data such as cookies, cacheable content, etc. is to be stored.
privateBrowsing - a boolean (default false) specifying that the datastore should be set to a new, empty and non-persistent datastore. Note that this will override the datastore key if both are specified and this is set to true.
userContentController - an optional hs.webview.usercontent object to provide script injection and JavaScript messaging with Hammerspoon from the webview.
Returns
The webview object
Notes
To set the initial URL, use the hs.webview:url method before showing the webview object.
Preferences can only be set when the webview object is created. To change the preferences of an open webview, you will need to close it and recreate it with this method.
​newBrowser​
Signature
hs.webview.newBrowser(rect, [preferencesTable], [userContentController]) -> webviewObject
Type
Constructor
Description
Create a webviewObject with some presets common to an interactive web browser.
Parameters
rect - a rectangle specifying where the webviewObject should be displayed.
preferencesTable - an optional table which specifies special settings for the webview object.
userContentController - an optional hs.webview.usercontent object to provide script injection and JavaScript messaging with Hammerspoon from the webview.
Returns
The webview object
Notes
The parameters are the same as for hs.webview.new -- check there for more details
This constructor is just a short-hand for hs.webview.new(...):allowTextEntry(true):allowGestures(true):windowStyle(15), which specifies a webview with a title bar, title bar buttons (zoom, close, minimize), and allows form entry and gesture support for previous and next pages.
Methods
​allowGestures​
| Signature | hs.webview:allowGestures([value]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the webview will respond to gestures from a trackpad or magic mouse. Default is false. | | Parameters |
value - an optional boolean value indicating whether or not the webview should respond gestures.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
| | Notes |
This is a shorthand method for getting or setting both hs.webview:allowMagnificationGestures and hs.webview:allowNavigationGestures.
This method will set both types of gestures to true or false, if given an argument, but will only return true if both gesture types are currently true; if either or both gesture methods are false, then this method will return false.
|
​allowMagnificationGestures​
| Signature | hs.webview:allowMagnificationGestures([value]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the webview will respond to magnification gestures from a trackpad or magic mouse. Default is false. | | Parameters |
value - an optional boolean value indicating whether or not the webview should respond to magnification gestures.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
|
​allowNavigationGestures​
| Signature | hs.webview:allowNavigationGestures([value]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the webview will respond to the navigation gestures from a trackpad or magic mouse. Default is false. | | Parameters |
value - an optional boolean value indicating whether or not the webview should respond to navigation gestures.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
|
​allowNewWindows​
| Signature | hs.webview:allowNewWindows([value]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the webview allows new windows to be opened from it by any method. Defaults to true. | | Parameters |
value - an optional boolean value indicating whether or not the webview should allow new windows to be opened from it.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
| | Notes |
This method allows you to prevent a webview from being able to open a new window by any method. This includes right-clicking on a link and selecting "Open in a New Window", JavaScript pop-ups, links with the target of "__blank", etc.
If you just want to prevent automatic JavaScript windows, set the preference value javaScriptCanOpenWindowsAutomatically to false when creating the web view - this method blocks all methods.
|
​allowTextEntry​
| Signature | hs.webview:allowTextEntry([value]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the webview can accept keyboard for web form entry. Defaults to false. | | Parameters |
value - an optional boolean value which sets whether or not the webview will accept keyboard input.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
|
​alpha​
| Signature | hs.webview:alpha([alpha]) -> webviewObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the alpha level of the window containing the hs.webview object. | | Parameters |
alpha - an optional number between 0.0 and 1.0 specifying the new alpha level for the webview.
| | Returns |
If a parameter is provided, returns the webview object; otherwise returns the current value.
|
​attachedToolbar​
| Signature | hs.webview:attachedToolbar([toolbar]) -> webviewObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or attach/detach a toolbar to/from the webview. | | Parameters |
toolbar - if an hs.webview.toolbar object is specified, it will be attached to the webview. If an explicit nil is specified, the current toolbar will be removed from the webview.
| | Returns |
if a toolbarObject or explicit nil is specified, returns the webviewObject; otherwise returns the current toolbarObject or nil, if no toolbar is attached to the webview.
| | Notes |
this method is a convenience wrapper for the hs.webview.toolbar.attachToolbar function.
|
​behavior​
| Signature | hs.webview:behavior([behavior]) -> webviewObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the window behavior settings for the webview object. | | Parameters |
behavior - an optional number representing the desired window behaviors for the webview object.
| | Returns |
If an argument is provided, the webview object; otherwise the current value.
| | Notes |
Window behaviors determine how the webview object is handled by Spaces and Exposé. See hs.drawing.windowBehaviors for more information.
|
​behaviorAsLabels​
| Signature | hs.webview:behaviorAsLabels(behaviorTable) -> webviewObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the window behavior settings for the webview object using labels defined in hs.drawing.windowBehaviors. | | Parameters |
behaviorTable - an optional table of strings and/or numbers specifying the desired window behavior for the webview object.
| | Returns |
If an argument is provided, the webview object; otherwise the current value.
| | Notes |
Window behaviors determine how the webview object is handled by Spaces and Exposé. See hs.drawing.windowBehaviors for more information.
|
​bringToFront​
Signature
hs.webview:bringToFront([aboveEverything]) -> webviewObject
Type
Method
Description
Places the drawing object on top of normal windows
Parameters
aboveEverything - An optional boolean value that controls how far to the front the webview should be placed. True to place the webview on top of all windows (including the dock and menubar and fullscreen windows), false to place the webview above normal windows, but below the dock, menubar and fullscreen windows. Defaults to false.
Returns
The webview object
​certificateChain​
| Signature | hs.webview:certificateChain() -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the certificate chain for the most recently committed navigation of the webview. | | Parameters |
None
| | Returns |
a table containing the certificates that make up the SSL certificate chain securing the most recent committed navigation. Each certificate is described in a table with the following keys:
commonName - the common name for the certificate; most commonly this will be a string matching the server portion of the URL request or other descriptor of the certificate's purpose.
values - a table containing key-value pairs describing the certificate. The keys will be certificate OIDs. Common OIDs and their meaning can be found in hs.webview.certificateOIDs. The value for each key will be a table with the following keys:
label - a description or label for the entry
localized label - a localized version of label
type - a description of the data type for this value
value - the value
| | Notes |
This method is only supported by OS X 10.11 and newer
A navigation which was performed via HTTP instead of HTTPS will return an empty array.
|
​children​
Signature
hs.webview:children() -> array
Type
Method
Description
Returns an array of webview objects which have been opened as children of this webview.
Parameters
None
Returns
an array containing the webview objects of all child windows opened from this webview.
​closeOnEscape​
| Signature | hs.webview:closeOnEscape([flag]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | If the webview is closable, this will get or set whether or not the Escape key is allowed to close the webview window. | | Parameters |
flag - an optional boolean value which indicates whether a webview, when it's style includes Closable (see hs.webview:windowStyle), should allow the Escape key to be a shortcut for closing the webview window. Defaults to false.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
| | Notes |
If this is set to true, Escape will only close the window if no other element responds to the Escape key first (e.g. if you are editing a text input field, the Escape will be captured by the text field, not by the webview Window.)
|
​darkMode​
Signature
hs.webview:darkMode([state]) -> bool
Type
Method
Description
Set or display whether or not the hs.webview window should display in dark mode.
Parameters
state - an optional boolean which will set whether or not the hs.webview window should display in dark mode.
Returns
A boolean, true if dark mode is enabled otherwise false.
​delete​
Signature
hs.webview:delete([propagate], [fadeOutTime]) -> none
Type
Method
Description
Destroys the webview object, optionally fading it out first (if currently visible).
Parameters
propagate - an optional boolean, default false, which indicates whether or not the child windows of this webview should also be deleted.
fadeOutTime - an optional number of seconds over which to fade out the webview object. Defaults to zero.
Returns
None
Notes
This method is automatically called during garbage collection, notably during a Hammerspoon termination or reload, with a fade time of 0.
​deleteOnClose​
| Signature | hs.webview:deleteOnClose([value]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the webview should delete itself when its window is closed. | | Parameters |
value - an optional boolean value which sets whether or not the webview will delete itself when its window is closed by any method. Defaults to false for a window created with hs.webview.new and true for any webview windows created by the main webview (user selects "Open Link in New Window", etc.)
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
| | Notes |
If set to true, a webview object will be deleted when the user clicks on the close button of a titled and closable webview (see hs.webview.windowStyle).
Children of an explicitly created webview automatically have this attribute set to true. To cause closed children to remain after the user closes the parent, you can set this to false with a policy callback function when it receives the "newWindow" action.
|
​estimatedProgress​
Signature
hs.webview:estimatedProgress() -> number
Type
Method
Description
Returns the estimated percentage of expected content that has been loaded. Will equal 1.0 when all content has been loaded.
Parameters
None
Returns
a numerical value between 0.0 and 1.0 indicating the percentage of expected content which has been loaded.
​evaluateJavaScript​
Signature
hs.webview:evaluateJavaScript(script, [callback]) -> webviewObject
Type
Method
Description
Execute JavaScript within the context of the current webview and optionally receive its result or error in a callback function.
Parameters
script - the JavaScript to execute within the context of the current webview's display
callback - an optional function which should accept two parameters as the result of the executed JavaScript. The function parameters are as follows:
result - the result of the executed JavaScript code or nil if there was no result or an error occurred.
error - an NSError table describing any error that occurred during the JavaScript execution or nil if no error occurred.
Returns
the webview object
​examineInvalidCertificates​
| Signature | hs.webview:examineInvalidCertificates([flag]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not invalid SSL server certificates that are approved by the ssl callback function are accepted as valid for browsing with the webview. | | Parameters |
flag - an optional boolean, default false, specifying whether or not an invalid SSL server certificate should be accepted if it is approved by the ssl callback function.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
| | Notes |
In order for this setting to have any effect, you must also register an ssl callback function with hs.webview:sslCallback which should return true if the certificate should be granted an exception or false if it should not. For a certificate to be granted an exception, both this method and the result of the callback must be true.
|
​frame​
| Signature | hs.webview:frame([rect]) -> webviewObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the frame of the webview window. | | Parameters |
rect - An optional rect-table containing the co-ordinates and size the webview window should be moved and set to
| | Returns |
If an argument is provided, the webview object; otherwise the current value.
| | Notes |
a rect-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the webview window (keys x and y) and the new size (keys h and w). The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.
|
​goBack​
Signature
hs.webview:goBack() -> webviewObject
Type
Method
Description
Move to the previous page in the webview's history, if possible.
Parameters
None
Returns
The webview Object
​goForward​
Signature
hs.webview:goForward() -> webviewObject
Type
Method
Description
Move to the next page in the webview's history, if possible.
Parameters
None
Returns
The webview Object
​hide​
Signature
hs.webview:hide([fadeOutTime]) -> webviewObject
Type
Method
Description
Hides the webview object
Parameters
fadeOutTime - An optional number of seconds over which to fade out the webview. Defaults to zero
Returns
The webview object
​historyList​
Signature
hs.webview:historyList() -> historyTable
Type
Method
Description
Returns the URL history for the current webview as an array.
Parameters
None
Returns
A table which is an array of the URLs viewed within this webview and a key named current which is equal to the index corresponding to the currently visible entry. Each array element will be a table with the following keys:
URL - the URL of the web page
initialURL - the URL of the initial request that led to this item
title - the web page title
​hswindow​
Signature
hs.webview:hswindow() -> hs.window object
Type
Method
Description
Returns an hs.window object for the webview so that you can use hs.window methods on it.
Parameters
None
Returns
an hs.window object
Notes
hs.window:minimize only works if the webview is minimizable (see hs.webview.windowStyle)
hs.window:setSize only works if the webview is resizable (see hs.webview.windowStyle)
hs.window:close only works if the webview is closable (see hs.webview.windowStyle)
hs.window:maximize will reposition the webview to the upper left corner of your screen, but will only resize the webview if the webview is resizable (see hs.webview.windowStyle)
​html​
Signature
hs.webview:html(html,[baseURL]) -> webviewObject, navigationIdentifier
Type
Method
Description
Render the given HTML in the webview with an optional base URL for relative links.
Parameters
html - the html to be rendered in the webview
baseURL - an optional Base URL to use as the starting point for any relative links within the provided html.
Returns
The webview Object
Notes
Web Pages generated in this manner are not added to the webview history list
​isOnlySecureContent​
Signature
hs.webview:isOnlySecureContent() -> bool
Type
Method
Description
Returns a boolean value indicating if all content current displayed in the webview was loaded over securely encrypted connections.
Parameters
None
Returns
true if all content current displayed in the web view was loaded over securely encrypted connections; otherwise false.
​isVisible​
Signature
hs.webview:isVisible() -> boolean
Type
Method
Description
Checks to see if a webview window is visible or not.
Parameters
None
Returns
true if the webview window is visible, otherwise false
​level​
| Signature | hs.webview:level([theLevel]) -> drawingObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the window level | | Parameters |
theLevel - an optional parameter specifying the desired level as an integer, which can be obtained from hs.drawing.windowLevels.
| | Returns |
if a parameter is specified, returns the webview object, otherwise the current value
| | Notes |
see the notes for hs.drawing.windowLevels
|
​loading​
Signature
hs.webview:loading() -> boolean
Type
Method
Description
Returns a boolean value indicating whether or not the vebview is still loading content.
Parameters
None
Returns
true if the content is still being loaded, or false if it has completed.
​magnification​
| Signature | hs.webview:magnification([value]) -> webviewObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the webviews current magnification level. Default is 1.0. | | Parameters |
value - an optional number specifying the webviews magnification level.
| | Returns |
If a value is provided, then this method returns the webview object; otherwise the current value
|
​navigationCallback​
Signature
hs.webview:navigationCallback(fn) -> webviewObject
Type
Method
Description
Sets a callback for tracking a webview's navigation process.
Parameters
fn - the function to be called when the navigation status of a webview cahnges. To disable the callback function, explicitly specify nil. The function should expect 3 or 4 arguments and may optionally return 1. The function arguments are defined as follows:
action - a string indicating the webview's current status. It will be one of the following:
didStartProvisionalNavigation - a request or action to change the contents of the main frame has occurred
didReceiveServerRedirectForProvisionalNavigation - a server redirect was received for the main frame
didCommitNavigation - content has started arriving for the main frame
didFinishNavigation - the webview's main frame has completed loading.
didFailNavigation - an error has occurred after content started arriving
didFailProvisionalNavigation - an error has occurred as or before content has started arriving
webView - the webview object the navigation is occurring for.

Submodules

API Overview

API Documentation

Deprecateds

​asHSDrawing​

​asHSWindow​

​setLevel​

Constants

​certificateOIDs​

​windowMasks​

Functions

​titleVisibility​

Constructors

​new​

​newBrowser​

Methods

​allowGestures​

​allowMagnificationGestures​

​allowNavigationGestures​

​allowNewWindows​

​allowTextEntry​

​alpha​

​attachedToolbar​

​behavior​

​behaviorAsLabels​

​bringToFront​

​certificateChain​

​children​

​closeOnEscape​

​darkMode​

​delete​

​deleteOnClose​

​estimatedProgress​

​evaluateJavaScript​

​examineInvalidCertificates​

​frame​

​goBack​

​goForward​

​hide​

​historyList​

​hswindow​

​html​

​isOnlySecureContent​

​isVisible​

​level​

​loading​

​magnification​

​navigationCallback​

asHSDrawing

asHSWindow

setLevel

certificateOIDs

windowMasks

titleVisibility

new

newBrowser

allowGestures

allowMagnificationGestures

allowNavigationGestures

allowNewWindows

allowTextEntry

alpha

attachedToolbar

behavior

behaviorAsLabels

bringToFront

certificateChain

children

closeOnEscape

darkMode

delete

deleteOnClose

estimatedProgress

evaluateJavaScript

examineInvalidCertificates

frame

goBack

goForward

hide

historyList

hswindow

html

isOnlySecureContent

isVisible

level

loading

magnification

navigationCallback