DESCRIPTION

dwb provides a javascript api that can be used to write userscripts or extensions for dwb.

GETTING STARTED

Scripts that use the javascript api must be located in $XDG_CONFIG_HOME/dwb/userscripts like any other script. Scripts that use the javascript api must either start with

#!javascript

or with

//!javascript

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

• The execution context of userscripts is completely separated 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

Properties

global (Object, read)

Refers to the global object

session (SoupSession, read)

The webkit session

Methods

// 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

or define a module that can be shared:

// included script
var private = 37;
provide("foo", {
 getPrivate : function() {
 return private;
 }
});
// Scripts that includes the above
var i = include("/path/to/script");
require(["foo"], function(foo) {
 var bar = foo.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

io

The io object implements methods for input and output.

system

The system object implements system methods.

tabs

The tabs object is an array like object that can be used to get webviews. It has the following properties.

tabs.current (webview, read)

The currently focused webview

tabs.length (Number, read)

Total number of tabs

tabs.number (Number, read)

Number of the currently focused tab

Additionally tabs implements all ECMAScript 5 array methods like forEach, map, filter, ...

net

Network related functions

timer

Functions for timed execution

util

The util object implements helper methods.

clipboard

gui

Most gtk-widgets can be accessed from scripts, an overview of the layout can be found under https://portix.bitbucket.org/dwb/resources/layout.html.

gui.window (GtkWindow, read)

The main window.

gui.mainBox (GtkBox, read)

The the main container, child of gui.window.

gui.tabBox (GtkBox, read)

The box used for tab labels, child of gui.mainBox.

gui.contentBox (GtkBox, read)

The box used for the main content, it contains all webviews, child of gui.mainBox.

gui.statusWidget (GtkEventBox, read)

The outmost statusbar widget, used for setting the statusbars colors, child of gui.mainBox.

gui.statusAlignment (GtkAlignment, read)

Used for the statusbar alignment, child of gui.statusWidget.

gui.statusBox (GtkBox, read)

The box that contains the statusbar widgets, grandchild of gui.statusAlignment.

gui.messageLabel (GtkLabel, read)

Label used for notifications, first child of gui.statusBox.

gui.entry (GtkEntry, read)

The entry, second child of gui.statusBox.

gui.uriLabel (GtkLabel, read)

Label used for displaying uris, third child of gui.statusBox.

gui.statusLabel (GtkLabel, read)

Label used for status information, fourth child of gui.statusBox.

Cookie

Represents a cookie. dwb only uses one cookie jar for persistent and session cookies. Session cookies can be distinguished from persistent cookies by checking if expires is null. To get a list of cookies currently used by the dwb instance net.allCookies, net.sessionCookies and net.persistentCookies can be used. To implement cookie handling use the addCookie event.

A cookie has the following properties

domain (String, read, write)

The cookie domain.

expires (Date, read)

The cookie expiration date.

httpOnly (Boolean, read, write)

If the cookie shouldn't be exposed to scripts.

name (String, read, write)

The cookie name.

path (String, read, write)

The cookie path.

secure (Boolean, read, write)

If the cookie should only be transferred over ssl.

value (String, read, write)

The cookie value.

A cookie implements following methods:

Deferred

Deferred objects can be used to manage asynchronous operations. It can trigger a callback function when an asynchrounous operation has finished, and allows chaining of callbacks. Deferred basically has 2 callback chains, a done-chain and a fail-chain. If a asynchronous operation is successful the deferred should be resolved and the done callback chain of the deferred is called. If a asynchronous operation fails the deferred should be rejected and the fail callback chain of the deferred is called.

Deferreds implement the following properties and methods:

Deferred.isFulFilled (Boolean, read)

Whether this deferred is resolved or rejected.

function loadUri(uri) {
 var d = new Deferred();
 tabs.current.loadUri(uri, function(wv) {
 if (wv.loadStatus == LoadStatus.finished)
 {
 d.resolve("Finished");
 return true;
 }
 else if (wv.loadStatus == LoadStatus.failed)
 {
 d.reject("Failed");
 return true;
 }
 });
 return d;
}
loadUri("http://www.example.com").then(
 function(response) {
 io.out(response); // Finished
 },
 function(response) {
 io.out(response); // Failed
 }
);

Chaining of a deferred:

function foo()
{
 var d = new Deferred();
 timer.start(2000, function() {
 d.reject("rejected");
 });
 return d;
}
function onResponse(response)
{
 io.out(response);
}
// Will print "rejected" twice to stdout after 2 seconds
foo().fail(onResponse).fail(onResponse);

Note that if the deferred is rejected only the fail chain is called, when it is resolved only the done chain is called.

function foo()
{
 var d = new Deferred();
 timer.start(2000, function() {
 d.reject("rejected");
 // Already rejected, will not execute the done chain
 d.resolve("rejected");
 });
 return d;
}
function onResponse(response)
{
 io.out(response);
}
// Only the fail will be executed
foo().fail(onResponse).done(onResponse);
foo().done(onResponse).fail(onResponse);

Changing the deferred in a callback chain:

function foo(message)
{
 var d = new Deferred();
 timer.start(2000, function() {
 d.resolve(message);
 });
 return d;
}
function callback1(response)
{
 io.out(response); // Prints "foo" after 2 seconds
 // Return a new Deferred, will replace the old one.
 return foo("bar");
}
function callback2(response)
{
 io.out(response); // Prints "bar" after 4 seconds
}
foo("foo").done(callback1).done(callback2);

Using Deferred.when

function asyncOperation() {
 var d = new Deferred();
 ....
 return d;
}
function syncOperation()
{
 var result = {};
 ....
 return result;
}
Deferred.when(asyncOperation(), function() {...});
Deferred.when(syncOperation(), function() {...});

Glob

Globs can be used for pattern matching, they are much simpler than regular expressions, there are only two special characters, the wildcard character * which matches any number of unknown characters and the joker character ? which matches exactly one unknown character. The literal characters "*" and "?" must be escaped with "\\";

settings

Readonly object that can be used to query dwb's current settings, all settings can also be used in camelcase, to modify settings execute can be used.

if (settings.enablePrivateBrowsing == true)
 execute("set enable-private-browsing false");

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;

To check if an object is derived from GObject the instanceof operator can be used:

if (myObject instanceof GObject)
{
 ...
}

General methods

The following methods are implemented by all Objects derived from GObject

webview

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

wv.allFrames (Array of frames, read)

All frames of a webview including the mainframe

wv.focusedFrame (Frame, read)

The focused frame of the webview

wv.historyList (Historylist, read)

The focused frame of the webview

wv.mainFrame (Frame, read)

The main frame of the webview

wv.number (Number, read)

The number of the webview, starting at 0

wv.scrolledWindow (GtkScrollwindow, read)

The parent widget of every webview, it is used for scrolling the webview.

wv.tabWidget (GtkEventBox, read)

The main widget for tab labels, used for coloring tabs, child of gui.tabBox.

wv.tabBox (GtkBox, read)

Horizontal box, child of wv.tabWidget.

wv.tabIcon (GtkImage, read)

Favicon widget, child of wv.tabBox.

wv.tabLabel (GtkLabel, read)

Text label of a tab, child of wv.tabBox.

Some signal callbacks can also be defined directly on webview instances, they can be set multiple times. Event properties that start with on are emitted for every emission of that signal, event properties that start with once are only emitted once and will be disconnected afterwards. Not that it isn't possible to disconnect from signals that are set directly on a webview instance.

wv.onButtonPress

Connects the webview to the buttonPress event.

wv.onceButtonPress

Connects the webview to the buttonPress event once.

wv.onButtonRelease

Connects the webview to the buttonRelease event.

wv.onceButtonRelease

Connects the webview to the buttonRelease event once.

wv.onCloseTab

Connects the webview to the closeTab event.

wv.onceCloseTab

Connects the webview to the closeTab event.

wv.onContextMenu

Connects the webview to the contextMenu event.

wv.onceContextMenu

Connects the webview to the contextMenu event once.

wv.onDocumentLoaded

Connects the webview to the documentLoaded event.

wv.onceDocumentLoaded

Connects the webview to the documentLoaded event once.

wv.onDownload

Connects the webview to the download event.

wv.onceDownload

Connects the webview to the download event once.

wv.onError

Connects the webview to the error event.

wv.onceError

Connects the webview to the error event once.

wv.onFollowHint

Connects the webview to the followHint event.

wv.onceFollowHint

Connects the webview to the followHint event once.

wv.onFrameCreated

Connects the webview to the frameCreated event.

wv.onceFrameCreated

Connects the webview to the frameCreated event once.

wv.onFrameStatus

Connects the webview to the frameStatus event.

wv.onceFrameStatus

Connects the webview to the frameStatus event once.

wv.onKeyPress

Connects the webview to the keyPress event.

wv.onceKeyPress

Connects the webview to the keyPress event once.

wv.onKeyRelease

Connects the webview to the keyRelease event.

wv.onceKeyRelease

Connects the webview to the keyRelease event once.

wv.onLoadCommitted

Connects the webview to the loadCommitted event.

wv.onceLoadCommitted

Connects the webview to the loadCommitted event once.

wv.onLoadFinished

Connects the webview to the loadFinished event.

wv.onceLoadFinished

Connects the webview to the loadFinished event once.

wv.onLoadStatus

Connects the webview to the loadStatus event.

wv.onceLoadStatus

Connects the webview to the loadStatus event once.

wv.onMimeType

Connects the webview to the mimeType event.

wv.onceMimeType

Connects the webview to the mimeType event once.

wv.onMouseMove

Connects the webview to the mouseMove event.

wv.onceMouseMove

Connects the webview to the mouseMove event once.

wv.onNavigation

Connects the webview to the navigation event.

wv.onceNavigation

Connects the webview to the navigation event once.

wv.onResource

Connects the webview to the resource event.

wv.onceResource

Connects the webview to the resource event once.

wv.onScroll

Connects the webview to the scroll event.

wv.onceScroll

Connects the webview to the scroll event once.

wv.onTabButtonPress

Connects the webview to the tabButtonPress event.

wv.onceTabButtonPress

Connects the webview to the tabButtonPress event once.

wv.onTabFocus

Connects the webview to the tabFocus event.

wv.onceTabFocus

Connects the webview to the tabFocus event once.

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.

frame.domain (String, read)

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

frame.host (String, read)

The host name of the frame

download

Corresponds to a WebKitDownload.

historylist

Corresponds to a WebkitWebBackForwardList.

historylist.backLength

Number of items that precede the current item

historylist.forwardLength

Number of items that succeed the current item

GTK WIDGETS

It is possible to create new widgets but only widgets that are currently used by dwb can be created, the widgets used by dwb can be found under http://portix.bitbucket.org/dwb/resources/layout.html.

Constructor

Methods

All created widgets implement the following methods:

var label = new GtkWidget("GtkLabel");
gui.statusBox.packStart(label, false, false, 0);
label.label = "foobar";
label.visible = true;

SOUPURI

Represenst a SoupURI object.

Properties

fragment (String, read)

The fragment part of the uri.

host (String, read)

The host of the uri.

password (String, read)

The password of the uri.

path (String, read)

The path of the uri.

port (String, read)

The port of the uri.

query (String, read)

The query part of the uri.

scheme (String, read)

The scheme of the uri.

user (String, read)

The user part of the uri.

SOUPHEADERS

Represents a header, to modify a request header the "resource" Signal can be used. The requestheaders can be accessed via WebKitNetWorkRequests.

Methods

Signal.connect("resource", function(wv, frame, request) {
 request.message.requestHeaders.remove("referer");
});

SIGNALS

Execute code on certain events. dwb emits some signals, e.g. before a new site is loaded, the signals object can be used to handle these signals. All events are emitted on the signals object itself, for example "signals.keyPress = function() { ... };" would connect to the keyPress signal but it is strongly discouraged to use this pattern since it will only allow to connect one callback to a certain signal. To handle signals Signal-objects can be used, it manages signals, allows one to connect to more than one signal and also allows one to easily disconnect/reconnect to signals.

There is just one convenient pattern that allows setting callbacks directly on signals: if the signal name starts with "on" dwb will internally create a new Signal and connect to it with the given callback function, i.e. using signals.onResource = function () {...} allows one to connect more than one callback to the "resource"-event, however it doesn't give you as much control as creating a Signal. When connected with this pattern it is not possible to disconnect from the signal with signals.onResource = null;, instead Signal.disconnect must be used.

Emitted signals

Custom signals can be created by simply calling

var signal = new Signal("nameOfNewSignal", callbackFunction);

Signals emitted by dwb are the following:

new Signal("addCookie", function(cookie));

Emitted when cookie has changed or a new cookie will be added to the cookie jar. If the callback returns true the cookie won't be added to the jar. To change the cookie the callback must return true and the cookie must be saved manually.

cookie

The cookie that has been added or changed.

new Signal("buttonPress", function(webview, hittestresult, event));

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

event.button

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

event.state

A bitmap of modifiers pressed, see Modifier

event.time

The time in milliseconds when the button was pressed

event.type

A ClickType

event.x

x-position relative to the window

event.xRoot

x-position relative to the screen

event.y

y-position relative to the window

event.yRoot

y-position relative to the screen

new Signal("buttonRelease", function(webview, hittestresult, event));

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

event

Same as buttonPress but without event.type

new Signal("changeMode", function(webview, mode));

Emitted when the mode changes, return true to prevent the change.

webview

The focused webview

mode

A mode, see also Modes for possible modes

new Signal("close", function());

Emitted when dwb is closed

new Signal("closeTab", function(webview));

Emitted when a tab is closed

webview

The webview that corresponds to the tab

new Signal("createTab", function(webview));

Emitted when a tab is created

webview

The webview that corresponds to the created tab

new Signal("documentLoaded", function(webview, frame));

Emitted when a the DOM document of a frame has been loaded.

webview

The webview that emitted the signal

frame

The frame that contains the document

new Signal("download", function(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

new Signal("downloadStart", function(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.

new Signal("downloadStatus", function(download));

Emitted when the DownloadStatus changes.

download

The Download

new Signal("executeCommand", function(commandinfo));

Emitted when a command is executed, return true to prevent execution.

commandinfo.command

The command that is executed

commandinfo.argument

An argument, if the command isn't executed from commandline this will always be null.

commandinfo.nummod

The numerical modifier.

new Signal("followHint", function(wv, resource));

Emitted before a hint is followed, return true to prevent following the hint

wv

The webview that currently has focus

resource

The resource of the hint, can be either a url or @input, @textarea, @radio, @checkbox, @submit, @reset, @button, @role, @unknown or @abort if Escape was pressed.

new Signal("frameCreated", function(webview, frame));

Emitted when a frame is created

webview

The webview the frame belongs to

frame

The frame

new Signal("frameStatus", function(webview, frame));

Emitted when the LoadStatus of a frame changes

webview

The webview the frame belongs to

frame

The frame

new Signal("keyPress", function(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

new Signal("keyRelease", function(webview, json));

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

webview

The focused webview

json

Same as keyPress

new Signal("loadCommitted", function(webview));

Emitted when the load has just committed, 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

new Signal("loadFinished", function(webview));

Emitted when the site has completely loaded.

webview

The webview that emitted the signal

new Signal("loadStatus", function(webview));

Emitted when the load status changes

webview

The webview that emitted the signal

new Signal("mimeType", function(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

new Signal("mouseMove", function(webview, event));

Emitted when the pointer is moved.

webview

The webview that emitted the signal

event

Same as buttonRelease

new Signal("navigation", function(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

new Signal("ready", function());

Emitted once when dwb has been fully initialized.

new Signal("resource", function(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

new Signal("statusBarChange", function(webview, data));

Emitted before the status bar is updated, if the callback returns true dwb will not update the statusbar so it is possible to set the statusbar from the script.

webview

The focused webview

data.canGoBack

Whether it is possible to navigate back in the webview

data.canGoForward

Whether it is possible to navigate forward in the webview

data.isBookmarked

Whether the site is bookmarked

data.isQuickmarked

Whether the site is quickmarked

data.pluginsBlocked

Whether plugins are blocked

data.scriptsBlocked

Whether scripts are blocked

data.ssl

SSL-State of the page, can either be trusted, untrusted or none

data.type

The type of the update, can be status and uri, status means that statusLabel und uriLabel need to be updated, uri means that only the uriLabel needs to be updated.

new Signal("tabButtonPress", function(webview, tabwidget, event));

Emitted when a button is pressed on a tabwidget, return true to prevent the default action

webview

The webview which received the signal

tabwidget

The tabwidget

event

Same as buttonPress

new Signal("tabFocus", function(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

SIGNAL

Object that can be used to connect to certain browser events.

Constructor

Properties

callback (Function, read|write)

The callback that will be called when the signal is emitted, the context of the signal will be the signal itself (i.e. this refers to the connected Signal).

connected (Boolean, read)

Whether the signal is connected

id (Number, read)

Unique id of the signal

name (String, read)

Name of the event

predicate(Function, read|write)_

A predicate function, the signal is only emitted if the predicate function returns true. The predicate function is called with the same arguments as the callback function

Methods

Static methods

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
};

NavigationReason

const NavigationReason = {
 linkClicked : 0,
 formSubmitted : 1,
 backForward : 2,
 reload : 3,
 formResubmitted : 4,
 other : 5
};

Modes

const Modes = {
 NormalMode : 1<<0,
 InsertMode : 1<<1,
 CommandMode : 1<<2
 HintMode : 1<<2
};

Selection

const Selection = {
 primary : 1,
 clipboard : 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.out(number); // undefined
var number2 = 0;
io.out(number2); // 0
// not allowed
foo = function()
{
 io.out("foo");
}
foo(); // fails

For sharing data between scripts either signals or modules can be created.

script and this

In every script the variable script refers to this, the encapsulating function, it has the following properties and methods:

script.path (Object, read)

The path of the script.

script._arguments (Object, read)

arguments object of the encapsulating function

MODULES

With modules it is possible to share objects between scripts. Modules are defined with provide and loaded with require.

Defining modules.

#!javascript
provide("myModule", {
 foo : 37,
 doBar : function() {
 io.out("bar");
 }
});
provide("myOtherModule", {
 act : function (arg) {
 io.out(arg);
 }
});

Getting some modules.

#!javascript
require(["myModule", "myOtherModule"], function(myModule, myOtherModule) {
 if (myModule.foo == 37)
 myModule.doBar();
 myOtherModule.act("foo");
});

Getting all modules.

#!javascript
require(null, function(modules) {
 if (modules.myModule.foo == 37)
 modules.myModule.doBar();
 modules.myOtherModule.act("foo");
});

It is also possible to specify a path in the name array. The name then follows the format name!path:

#!javascript
require(["foo!/path/to/foo"], function(foo) {
 io.out(foo.bar); // 37
});

/path/to/foo.

provide("foo", { bar : 37 });

The resolution chain is as follows, first all modules defined with provide and module names requested by require are stored. If all scripts have been loaded the requirements are resolved. If a requirement contains a path and the module isn't defined yet the module will be loaded, if it is already defined the path is ignored and the stored module will be resolved:

#!javascript
require(["foo!/path/to/foo"], function(foo) {
 io.out(foo.bar); // 42
});
provide("foo", { bar : 42 });

#!javascript
require(["foo"], function(foo) {
 io.out(foo); // undefined
});
require(["foo!/path/to/foo"]);
require(["foo"], function(foo) {
 io.out(foo); // { bar : 37 }
});

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. One advantage of extension also is that they can be loaded/unloaded on the fly.

Prepackaged extensions

extensions.load("perdomainsettings", {
 domains : {
 "example.com" : {
 "enablePlugins" : true
 },
 "example.uk.com" : {
 "enablePlugins" : true,
 "enableScripts" : false
 }
 },
 hosts : {
 "www.example1.com" : {
 "autoLoadImages" : true
 }
 },
 uris : {
 "http://www.example2.com/login.php" : {
 "autoLoadImages" : false
 }
 },
 defaults : {
 "enablePlugins" : false,
 "autoLoadImages" : false,
 "enableScripts" : true
 }
});

extensions.load("userscripts", [ "/path/to/script1", "/path/to/script2" ]);

Using extensions

Extensions can be loaded by an userscript

#!javascript
extensions.load("extension_1");
extensions.load("extension_2", {
 configProp_1 : 22,
 configProp_2 : "val2"
});

To load/unload extensions on the fly extensions.bind can be used:

#!javascript
var myConfig = {
 prop_1 : 37,
 prop_2 : true,
 prop_3 : "foo"
};
extensions.bind("myExtension", "Control m", {
 command : "toggleMyExtension",
 config : myConfig,
 load : false
});
extensions.bind("mySecondExtension", "Control M");

The default searchpaths for extensions are $XDG_DATA_HOME/dwb/extensions/ and /usr/share/dwb/extensions/.

Methods

Writing extensions

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

The configuration for extensions is in $XDG_CONFIG_HOME/dwb/extensionrc 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.

Additionally the returned object can also have a defaultConfig-property and an exports-property. defaultConfig will be mixed into the config before calling the init function and exports can be used to define a public api that can be loaded as a module with require.

function foo(val) {
 ....
}
function bar(val) {
 ....
}
function loadStatusCallback(w) {
 ...
}
var myExtension = {
 defaultConfig : { foo : 37 },
 exports : {
 foo : foo,
 bar : bar
 },
 init : function (config) {
 if (config.foo > 36) {
 bar(config.foo);
 foo(config.bar);
 bind("XX", bar, "dobar");
 Signal.connect("loadStatus", loadStatusCallback);
 return true;
 }
 return false;
 },
 end : function () {
 unbind("dobar");
 Signal.disconnect(loadStatusCallback);
 return true;
 }
};
return myExtension;

return {
 foobar : { bar : "X", foo : 37 }, // config for extension foobar
 barfoo : { } // config for extension barfoo
};