Abstract

dwb can be extended with different types of userscripts. This api documentation describes the javascript interface.

Getting Started

Scripts that use the javascript api must be located in $XDG_CONFIG_HOME/dwb/userscripts like any other script. To include a userscript put a script with shebang

#!javascript

in the userscripts directory.

All native javascript methods can be used in scripts, however there are limitations:

  • The execution context of userscripts is completely seperated from the web execution context. Due to security concerns it is not possible to communicate with the web execution context, it is only possible to inject scripts into the web context.

  • In contrast to the global window object in the web execution context, the global object is a readonly object, i.e. it is not possible to set properties on the global object, see also global data for details.

Global

Functions from the global object.

Functions

bind()

boolean bind(String shortcut, Function callback, [String name])

Bind a javascript function to a shortcut. This is the preferred method of binding keys to shortcuts since the shortcut is evaluated using the native method, but also the keyPress-signal can be used to bind shortcuts.

shortcut

A shortcut shortcut, will be parsed the same way as if set in dwb:keys

callback

Callback function that will be called when the shortcut is pressed

name

A name that identifies the function on command line, optional

returns

true if the function was binded successfully

domainFromHost()

String domainFromHost(String hostname)

Gets the base domain name from a hostname where the base domain name is the effective second level domain name, e.g. for www.example.com it will be example.com, for www.example.co.uk it will be example.co.uk.

hostname

a hostname

returns

the base domain

execute()

Boolean execute(String command)

Executes a dwb command

command

a dwb command to execute, will be parsed the same way as if executed from commandline

returns

true if execution was successful

exit()

Boolean exit()

Exit dwb, must be called if the script is running from commandline.

include()

Value include(String path, [Boolean global])

Includes a file. Note that there is only one context, all scripts are executed in this context. Included files are not visible in other scripts unless true is passed as second parameter.

path

Path to a file to include

global

Whether to include the script into the global scope, optional

returns

The return value of the included file

sendRequest()

void sendRequest(String uri, Function callback, [String method])

Sends a http-request.

uri

The uri the request will be sent to.

callback

A callback that will be called when the request is finished, the callback has 2 parameters, the first will be an object that contains body and headers, the second the associated SoupMessage.

method

The http request method, default GET, optional.

sendRequestSync()

Object sendRequestSync(String uri, [String method])

Sends a http-request synchronously.

uri

The uri the request will be sent to.

method

The http request method, default GET, optional.

returns

Object that contains the response body, the response headers and the http status code of the request.

tabComplete()

void tabComplete(String label, Array items, Function callback)

Initiates tab completion.

label

The command line label

items

An array of objects, each object can have 2 properties, left which will be the left completion label and right which will be the right completion label.

callback

Callback function, the first argument will be the returned string from the url bar.

timerStart()

Number timerStart(Number interval, Function func)

Executes a function repeatedly until the function returns false or [timerStop] is called on the id returned from this function

interval

Interval in milliseconds

func

Function to execute

returns

An id that can be passed to timerStop

timerStop()

Number timerStop(Number id)

Stops a timer started by [timerStart]

id

The id returned from [timerStart]

returns

true if the timer was stopped

unbind()

Number unbind(Function func|String name)

Unbind a shortcut that was previously binded with [bind]

func or name

Either the function or the optional name passed to [bind].

returns

true if the function is unbinded

Example
execute("tabopen ixquick.com");

// Execute a function once, similar to window.setTimeout()
timerStart(2000, function() {
  tabs.current.inject("alert('Hello world')");
  return false;
});
Note
Scripts included with include are either visible in the global scope or invisible, even in the including script. To use an included script it can return an object with its public objects:
// included script

var private = 37;
return {
  getPrivate : function () {
    return private;
  }
};

// Scripts that includes the above
var i = include("/path/to/script");
var p = i.getPrivate();               // 37

Global Objects

data

The data object can be used to determine internally used data securely. All properties are readonly Strings.

data.bookmarks

Bookmark file

data.cacheDir

Cache directory

data.configDir

Config directory

data.cookies

Cookie file

data.cookiesWhitelist

Whitelist for persistent cookies

data.customKeys

Custom keyboard shortcuts

data.history

History file

data.keys

Shortcuts configuration file

data.pluginsWhitelist

Whitelist for the plugin blocker

data.profile

Profile which will be default unless another profile is specified on command line

data.quickmarks

Quickmark file

data.scriptWhitelist

Whitelist for scripts

data.session

File with stored sessions for this profile

data.sessionCookiesWhitelist

Whitelist for session cookies

data.settings

Settings configuration file

data.searchEngines

Searchengines

Example
// Get contents of the currently used bookmark file
var bookmarks = io.read(data.bookmarks);

io

The io object implements functions for input and output.

debug()

void io.debug(String message | Error error, [Error error])

Prints a debug message and the call stack to stderr. If the first parameter is an error object the second parameter is ignored, else the error is optional.

message

The message to show

error

A javascript error object, optional as second parameter

dirNames()

Array io.dirNames(String path)

Get directory entries.

path

A path to a directory

returns

An array with the directory names

error()

void io.error(String text)

Shows an error message in the browser window.

text

The message to show

notify()

void io.notify(String text)

Shows a message in the browser window.

text

The message to show

print()

void io.print(String text, [String stream])

Print text to stdout or stderr

text

the text to print

stream

pass "stderr" to print to stderr, optional

prompt()

String io.prompt(String text, [Boolean visible])

Gets user input synchronously.

text

The message for the prompt

visible

Whether the chars should be visible, pass false for a password prompt, default true, optional

returns

The text that was entered or null

read()

String io.read(String path)

Read from a file.

path

Path to a file that should be read

returns

A string with the file content

write()

Boolean io.write(String path, String mode, String text)

Write to a file

path

Path to a file to write to

mode

Either "a" to append to the file, or "w" to strip the file or create a new file.

text

The text that should be written to the file

returns

true if writing was successful

Example
var text = io.read("/home/foo/textfile.txt");
io.print(text);

system

The system object implements system functions.

fileTest()

Boolean system.fileTest(String path, FileTest flags)

Checks for [FileTest] flags on a file.

path

Path to a file to check

flags

The flags to test

returns

true if any of the test on the flags is true

getEnv()

String system.getEnv(String name)

Get a system environment variable

name

Name of the variable

returns

The variable or null if the variable wasn’t found

mkdir()

Boolean system.mkdir(String path, Number mode)

Creates a directory and all parent directories.

path

Path to create

mode

The permissions the directory will get

returns

true if creation was successful or directory already existed

spawn()

SpawnError system.spawn(String command, [Function stdin], [Function stderr])

Executes a shell command using the default search path

command

The command to execute

stdin(String)

Callback function for stdin, pass null if only stderr is needed, optional

stderr(String)

Callback function for stderr, optional

returns

[SpawnError] if an error occured, 0 otherwise

spawnSync()

Object system.spawn(String command)

Executes a shell command synchronously using the default search path

command

The command to execute

returns

An object that contains stdout, stderr and status.

Example
var home = system.getEnv("HOME");
// asynchronous wrapped read
function asyncread(filename) {
  system.spawn("cat " + filename, function (response) {
      ...
  });
}
asyncread(home + "/.bashrc");

tabs

The tabs object implements functions and properties to get webview objects.

Properties

current

tabs.current        webview     read

The currently focused webview

length

tabs.length         Number      read

Total number of tabs

number

tabs.number         Number      read

Number of the currently focused tab

Functions

nth()

webview tabs.nth(Number n)

Gets the webview object of the nth tab

n

Number of the tab

returns

The corresponding [webview]

Example
var c = tabs.current;
tabs.nth(2).loadUri(c.uri);

util

The util object implements helper functions.

getBody(Function)

String util.getBody(Function func)

Gets the body of a function, useful for scripts that will be injected into sites.

func

A function

returns

The body of the function as a string

Webkit objects

All webkit objects correspond to gobject objects, i.e. they have the same properties, but the javascript properties are all camelcase. For example, a WebKitWebView has the property zoom-level, the corresponding javascript property is zoomLevel:

var webview = tabs.current
webview.zoomLevel = webview.zoomLevel * 2;

All Objects derived from GObjets implement the following functions.

connect()

Number object.connect(String name, Function callback)

Connect to a gobject-signal.

name

The signal name to connect to.

callback

Callback function that will be called when the signal is emitted.

returns

The signal id of the signal.

disconnect()

Boolean object.disconnect(Number id)

Disconnect from a gobject-signal.

id

The signal id obtained from [connect]

returns

true if the signal was disconnected

Example

tabs.current.connect("notify::load-status", function() {
  io.print("Status changed");
});

webview

The webview object represents the widget that actually displays the site content.

Properties

The properties correspond to the gobject properties in camelcase. Additional properties are

allFrames

wv.allFrames        array of frames     read

All frames of a webview including the mainframe

focusedFrame

wv.focusedFrame        frame     read

The focused frame of the webview

mainFrame

wv.mainFrame        frame     read

The main frame of the webview

number

wv.number        frame     read

The number of the webview, starting at 0

Functions

inject()

String wv.inject(String script, [Boolean global])

Injects a script into a webview

script

The script to inject

global

true to inject it into the global scope, false to encapsulate it in a function, optional

returns

The return value of the script. If the script is injected globally inject always returns null. The return value is always converted to a string. To return objects call JSON.parse on the return value.

history()

void wv.history(Number steps)

Loads a history item steps away from the current history item

steps

Number of steps, pass a negative value to go back in history

loadUri()

Boolean wv.loadUri(String uri, [Function callback])

Load an uri in a webview.

uri

The uri to load

callback

A callback function that will be called when the load status changes, return true to stop the emission, optional

returns

true if the uri is loaded

reload()

void wv.reload(void)

Reload a webview

Example

var wv = tabs.current;

wv.loadUri("http://www.example.com", function() {
  if (wv.loadStatus == LoadStatus.finished) {
    wv.inject("alert('Hello ' + wv.uri + '!!!');");
    return true;
  }
});
Note
If a script is injected from a [loadStatus]-callback the script must be injected after LoadStatus.committed has been emitted. On LoadStatus.committed the document hasn’t been created, if the script modifies the DOM it should be injected on LoadStatus.finished. If only LoadStatus.committed or loadFinished.committed are used it is better to use the corresponding signals instead to reduce overhead.

frame

A frame represents a frame or iframe. Due to same origin policy it is not possible to inject scripts from a [webview] into iframes with a different domain. For this purpose the frame object can be used.

Properties

The properties correspond to the gobject properties in camelcase. Additional properties are

domain

frame.domain        frame     read

The domain name of the frame which is the effective second level domain

host

frame.host        frame     read

The host name of the frame

To get the domain or hostname of a webview

webview.mainFrame.domain
webview.mainFrame.host

can be used.

Functions

inject()

Boolean frame.inject(String script, [Boolean global])

Injects a script into a frame, also see webview.inject for details.

download

Corresponds to a WebKitDownload.

Constructor

Download()

new Download(String uri)

Constructs a new download

uri

The uri of the download

Functions

start()

Boolean download.start([Function callback])

Starts a download

callback

A callback function that will be executed whenever the [DownloadStatus] changes, return true to stop the emission, optional.

cancel()

void download.cancel()

Cancels a download

Example
var download = new Download("http://www.example.org/foo.pdf");
var filename = "/tmp/" + download.suggestedFilename;
download.destinationUri = "file://" + filename;
download.start(function () {
  if (download.status == DownloadStatus.finished) {
    system.spawn("xpdf " + filename);
  }
});

request

Corresponds to a WebKitNavigationRequest.

Corresponds to a WebKitWebNavigationAction.

Signals

With the signals object dwb communicates with the script on certain events. To connect to a signal one can call the connect function that is implemented by the signals object, that takes 2 arguments, the name of the signal and a callback function.

The callback function has a varying number of parameters. The last paramter is always a json-object which might be empty or contain additional data relevant to the signal. A callback function should either return true or false or nothing which is equivalent to false. If multiple callbacks are connected to the same signal and one callback function returns true the overall return value will be true.

dwb only emits signals as long as one callback is connected to a signal. To reduce overhead one should disconnect from signals when no longer needed.

The signals object is not a readonly object, properties can be added to the object which are visible in all scripts but it should be avoided to add properties on the signals object. signals should only be used to connect to signals or define custom signals.

The signals object implements the following functions

Functions

connect()

Number signals.connect(String signal, Function callback)

Connect to a signal

signal

The signal to connect to

callback

The callback function which will be called when the signal is emitted

returns

Unique id for this connection, can be passed to [disconnect]

emit()

Boolean signals.emit(String signal,  ...)

Emits a signal with a variable number of arguments passed to the callback function

signal

The signal to emit

Objects passed to the callback function

returns

Overall return value from all connected callback functions

disconnect()

Boolean signals.disconnect(Number id)

disconnect from a signal

id

The id returned from [connect]

returns

true if the signal was disconnected, false if the signal wasn’t found or was already disconnected.

disconnectByFunction()

Boolean signals.disconnectByFunction(Function callback)

disconnect from all signals with matching callback function

callback

The callback function passed to [connect]

returns

true if signals were disconnected, false if no signal was disconnected

disconnectByName()

Boolean signals.disconnectByName(String signal)

disconnect from all signals with matching name, It should be avoided to call disconnectByName on signals implemented by dwb since it will completely stop the emission of the signal in all scripts.

signal

The callback function passed to [connect]

returns

true if signals were disconnected, false if no signal was disconnected

Emitted signals

Custom signals can be created by simply calling

signals.connect("nameOfNewSignal", callbackFunction);

Signals emitted by dwb are the following:

buttonPress

Boolean callback(webview, hittestresult, json)

Emitted when a button is pressed on the [webview], return true to prevent the default action

webview

The [webview] which received the signal

hittestresult

Hittestresult under the cursor

json.button

The button that is pressed, usually a value between 1 and 5

json.state

A bitmap of modifiers pressed, see [Modifier]

json.time

The time in milliseconds when the button was pressed

json.type

A [ClickType]

json.x

x-position relative to the window

json.xRoot

x-position relative to the screen

json.y

y-position relative to the window

json.yRoot

y-position relative to the screen

buttonRelease

Boolean callback(webview, hittestresult, json)

Emitted when a button is released, return true to prevent the default action

webview

The [webview] which received the signal

hittestresult

Hittestresult under the cursor

json

Same as [buttonPress] but without json.type

close

Boolean callback()

Emitted when dwb is closed

createTab

Boolean callback(webview)

Emitted when a tab is created

webview

The [webview] that corresponds to the created tab

closeTab

Boolean callback(webview)

Emitted when a tab is closed

webview

The [webview] that corresponds to the tab

documentLoaded

void callback(webview, frame)

Emitted when a the dom document of an frame has loaded.

webview

The [webview] that emitted the signal

frame

The frame that contains the document

download

Boolean callback(webview, download, json)

Emitted before a download starts, before a file or action has been chosen, return true if the signal was handled.

webview

The [webview] that emitted the signal

download

The [Download]

json.referer

The referer

json.mimeType

The mimetype of the file

downloadStart

Boolean callback(download, json)

Emitted before a download starts after a path or application has been chosen, return true if the signal was handled. Note that destinationUri has not been set on the download.

download

The [Download]

json.referer

The referer

json.mimeType

The mimetype of the file

json.destinationUri

The chosen destination path or null if an application was chosen.

json.application

The chosen application or null if a path was chosen.

downloadStatus

Boolean callback(download)

Emitted when the [DownloadStatus] changes.

download

The [Download]

frameCreated

void callback(webview, frame)

Emitted when the frame is created

webview

The webview the frame belongs to

frame

The frame

frameStatus

void callback(webview, frame)

Emitted when the [LoadStatus] of a frame changes

webview

The webview the frame belongs to

frame

The frame

void callback(webview, json)

Emitted when the mouse is over a link

webview

The webview that emitted the signal

json.uri

The uri of the link or null if there is no link under the pointer, i.e. the pointer left a link

json.title

The link’s title or null if the pointer left a link

keyPress

Boolean callback(webview, json)

Emitted when a key is pressed, return true to prevent the default action

webview

The focused webview

json.isModifier

Whether or not the key is a modifier

json.keyCode

Hardware keycode

json.keyVal

Keycode as listed in gdkkeysyms.h

json.name

A string represantation of the key

json.state

A bitmap of modifiers pressed, see [Modifier]

keyRelease

Boolean callback(webview, json)

Emitted when a key is released, return true to prevent the default action

webview

The focused webview

json

Same as [keyPress]

loadCommitted

void callback(webview)

Emitted when the load has just commited, no data has been loaded when this signal is emitted. This is the preferred signal for injected scripts that do not manipulate the DOM.

webview

The webview that emitted the signal

loadFinished

Boolean callback(webview)

Emitted when the site has completely loaded.

webview

The webview that emitted the signal

loadStatus

void callback(webview)

Emitted when the load status changes

webview

The webview that emitted the signal

mimeType

Boolean callback(webview, frame, request, json)

Decide whether or not to show a given mimetype. Return true to stop the request.

webview

The webview that emitted the signal

frame

The frames requires the decision

request

The network request

json.mimeType

The mimetype

Boolean callback(webview, frame, request, action)

Emitted before a new site is loaded, return true to stop the request.

webview

The webview that emitted the signal

frame

The frame that requires the navigation

request

The network request

action

The navigation action

resource

Boolean callback(webview, frame, request, response)

Emitted before a new resource is going to be loaded

webview

The webview that emitted the signal

frame

The frame that dispatched the request

request

The network request

response

The network response

tabFocus

Boolean callback(webview, json)

Emitted when another tab gets focus, return true to stop the event

webview

The new tab

json.last

The number of the previously focused tab

Example
// Prevent example.com from being loaded
function navigationCallback(wv, frame, request, action) {
  if (/.*\.example\.com.*/.test(request.uri)) {
    return true;
  }
}
signals.connect("navigation", navigationCallback);

Enum objects

Enum objects are objects that have only readonly properties, mapping gtk/webkit enums to javascript objects.

ButtonContext

const ButtonContext = {
  document   : 1 << 1,
  link       : 1 << 2,
  image      : 1 << 3,
  media      : 1 << 4,
  selection  : 1 << 5,
  editable   : 1 << 6
};

ChecksumType

const ChecksumType = {
  md5     : 0,
  sha1    : 1,
  sha256  : 2
};

ClickType

const ClickType = {
  click       : 4,
  doubleClick : 5,
  tripleClick : 6
};

DownloadStatus

const DownloadStatus = {
  error       : -1,
  created     : 0,
  started     : 1,
  cancelled   : 2,
  finished    : 3
};

FileTest

const FileTest = {
  regular    : 1 << 0,
  symlink    : 1 << 1,
  dir        : 1 << 2,
  executable : 1 << 3,
  exists     : 1 << 4
};

LoadStatus

const LoadStatus = {
  provisional       : 0,
  committed         : 1,
  finished          : 2,
  firstVisualLayout : 3,
  failed            : 4
};

Modifier

const Modifier = {
  Shift     : 1 << 0,
  Lock      : 1 << 1,
  Control   : 1 << 2,
  Mod1      : 1 << 3,
  Mod2      : 1 << 4,
  Mod3      : 1 << 5,
  Mod4      : 1 << 6,
  Mod5      : 1 << 7,
  Button1   : 1 << 8,
  Button2   : 1 << 9,
  Button3   : 1 << 10,
  Button4   : 1 << 11,
  Button5   : 1 << 12,
  Super     : 1 << 26,
  Hyper     : 1 << 27,
  Meta      : 1 << 28,
  Release   : 1 << 30,
  Modifier  : 0x5c001fff
};
const NavigationReason = {
  linkClicked     : 0,
  formSubmitted   : 1,
  backForward     : 2,
  reload          : 3,
  formResubmitted : 4,
  other           : 5
};

SpawnError

const SpawnError = {
  success       : 0,
  spawnFailed   : 1<<0,
  stdoutFailed  : 1<<1,
  stderrFailed  : 1<<2
};

Global data

Since all scripts share the same execution context, they are encapsulated in a function. To avoid conflicts with other scripts it is not allowed to set properties on the global object, i.e.

#!javascript

// not allowed, the global object is readonly
number = 0;
io.print(number);     // undefined

// always use var instead
var number = 0;
io.print(number2);    // 0

// won't work either
function foo() {
  bar = 1;
}
foo();
io.print(bar);        // undefined

For sharing data between scripts either signals can be created or the globals-object can be used. To share data with the globals object securely when the scripts are loaded the script can return an init function that will be called after all scripts have been initialized:

Script 1
#!javascript

// set when the script is initialized.
globals.foo = "bar";
Script 2
#!javascript

//  The behaviour is undefined, depending on if Script 1 was initialized before
//  Script 2 or the other way round.
io.print(globals.foo)       // undefined or "bar"

// Will be called after all scripts have been initialized
return  {
  init : function () {
    // globals.foo has been initialized
    io.print(globals.foo); // "bar"
  }
};

One exception is [include], scripts that are explicitly included into the global scope setting the second parameter to true are visible in every script.

foo
var foo = "bar";
Script 1
#!javascript

include("/path/to/foo", true); // visible in every script
Script 2
#!javascript

// Make sure Script 1 has been initialized
return {
  init : function() {
    io.print(foo);                // "bar";
  }
};

Extensions

dwb provides the possibility to load extensions. It is recommended to implement javascript-userscripts as an extension to have consistent configuration locations for scripts.

The extensions object has the following properties and functions

Properties

enableDebugging

extensions.enableDebugging         Boolean      read

Whether to enable debugging messages.

Functions

debug()

void extensions.debug(String name, String message)

Prints a debug message and the call stack to stdout, enableDebugging must be set to true in order to print debug messages.

name

Name of the extension

message

The debug message to print.

load()

Boolean extensions.load(String name, [Object config])

Loads an extension

name

Name of the extension

config

The config for the script, if omitted the config is read from $XDG_CONFIG_HOME/dwb/extensionrc, optional

returns

True if the extension was loaded

reload()

Boolean extensions.reload(String name, [Object config])

Reloads an extension

name

Name of the extension

config

The new config for the script, if omitted the old config is used, optional

returns

True if the extension was successfully reloaded

unload()

Boolean extensions.unload(String name)

Unloads an extension

name

Name of the extension

returns

True if the extension was unloaded

error()

void extensions.error(String name, String message|Error e, [String message])

Print an error message and call stack to stderr.

name

Name of the extension

message|e

The error message or an Error

message

If the second parameter is an Error, an optional message can be specified.

message()

void extensions.message(String name, String message)

Print a consistent message to stderr

name

Name of the extension

message

The message

warning()

void extensions.warning(String name, String message)

Print a consistent warning to stderr

name

Name of the extension

message

The warning message

Example
#!javascript

extensions.load("foobar");
Writing extensions

The default searchpath for extensions isn $XDG_DATA_HOME/dwb/extensions and SHARE_DIR/dwb/extensions where the SHARE_DIR with sharedirectory being the share directory of the installation, most likely /usr/share.

The configuration for extensions is in $XDG_CONFIG_HOME/dwb/extensionsrc and should return a javascript object.

Every extension must implement one function named init that takes one argument, the config for the extension. The function should return true if the extension was successfully loaded, false otherwise. Every extension also may implement a function end that will be called when an extension is unloaded. If an extension registers to signals and binds shortcuts the extension should unregister all signals and unbind all shortcuts in this function. init and end should be returned from the extension.

Example

A extension called foobar in $HOME/.local/share/dwb/extensions/foobar.

function foo(val) {
  ....
}
function bar(val) {
  ....
}
function loadStatusCallback(w) {
  ...
}
return {
  init : function (config) {
    if (config.foo > 36) {
      bar(config.foo);
      foo(config.bar);
      bind("XX", bar, "dobar");
      signals.connect("loadStatus", loadStatusCallback);
      return true;
    }

    return false;
  },
  end : function () {
    unbind(bar);
    signals.disconnectByFunction(loadStatusCallback);
    return true;
  }
};
Example extensionrc
return {
  foobar : { bar : "X", foo : 37 }, // config for extension foobar
  barfoo : {  }                     // config for extension barfoo

};