API-Version: 1.9

extensions

Handles extensions. If scripts should be managed by dwbem they must be implemented as an extension. In contrast to regular scripts extensions can be enabled/disabled on the fly without reloading all userscripts. Every extension must contain two special tags, /&42;<INFO ... INFO>*/ that will be used by dwbem to find information about the extension and //<DEFAULT_CONFIG ... //>DEFAULT_CONFIG that will be used by dwbem to find the default configuration Every extension must also return an object that can have up to five properties.

Properties:
Name Type Argument Description
apiVersion Number <optional>

The minimum apiversion required for the extension

defaultConfig Object <optional>

The default configuration, will be passed to util.mixin

end extensions~onEnd

A function that will be called when the extension is unloaded, can be used to disconnect from signals/unbind shortcuts, ...

exports Object <optional>

An object that exports some functionality or the configuration, the object can be retrieved in other scripts with require

init extensions~onInit

A function that will be called when an extension is loaded

Source:

Example

// ext:set ft=javascript:

/*<INFO 
Extension that does some awesome things
INFO>*/

var defaultConfig = { 
//<DEFAULT_CONFIG
// Foo
foo : 37, 
// Shortcut to do some action
shortcut : "foo"
//>DEFAULT_CONFIG
};

var myConfig = {};

function action() {
     ...
} 
function onNavigation() {
     ...
} 
var myExtension = {
     apiVersion : 1.7, 
     defaultConfig : defaultConfig, 
     exports : {
         action : action
     },
     init : function(config) {
         myConfig = config; 

         bind(config.shortcut, action); 
         Signal.connect("navigation", onNavigation); 

         this.exports.config = config;

         return true;
     },
     end : function() {
         Signal.disconnect(onNavigation);
         unbind(action);

         return true;
     }
};
return myExtension;

Methods

<static> bind(name, shortcut, options)

Binds an extension to a shortcut

Parameters:
Name Type Description
name String

Name of the extension

shortcut String

The shortcut that will be used to toggle the extension

options Object
Properties
Name Type Description
load Boolean

Whether to initially load the extension

config Boolean

The configuration passed to extensions.load

command String

Command that can be used from dwb's command line to toggle the extension

Source:

<static> disableAll()

Disables all extensions, calls extensions.unload for every extension

Source:

<static> error(name, message)

Print an error message to stderr

Parameters:
Name Type Description
name String

Name of the extension

message String

The message to print

Source:

<static> load(name, configuration)

Loads an extension, the default path for an extension is data.userDataDir/extensions/name_of_extension or data.systemDataDir/extensions/name_of_extension

Parameters:
Name Type Description
name String

The name of the extension

configuration Object

The configuration that will be used for the extension

Source:

<static> loadChrome(wv, uri) → {Boolean}

Loads a registered chrome document, used internally

Parameters:
Name Type Description
wv WebKitWebView

The webview that loads the chrome document

uri String

The uri

Since:
  • 1.6
Source:
Returns:

True if the chrome page had been registered and loaded

Type
Boolean

<static> message(name, message)

Print message to stderr

Parameters:
Name Type Description
name String

Name of the extension

message String

The message to print

Source:

<static> registerChrome(name, callback)

Registers a chrome page

Parameters:
Name Type Description
name String

Name of the chrome document, can be loaded with dwb-chrome://

callback extensions~onLoadChrome

Callback function called when the chrome document is requested.

Since:
  • 1.6
Source:

<static> toggle(name, configuration) → {Boolean}

Toggles an extension, if it is loaded toggle will unload it, otherwise it will load it.

Parameters:
Name Type Description
name String

Name of the extension

configuration Object

Configuration that will be passed to extensions.load

Source:
Returns:

true if the extension was loaded, false if it was unloaded

Type
Boolean

<static> unload(name) → {Boolean}

Unloads an extension, calls extension.end when the extensions is unloaded

Parameters:
Name Type Description
name String

The name of the extension

Source:
Returns:

true if the extension was found and unloaded

Type
Boolean

<static> unregisterChrome(name)

Unregisters a chrome page

Parameters:
Name Type Description
name String

Name of the chrome document

Since:
  • 1.6
Source:

<static> warning(name, message)

Print a warning message to stderr

Parameters:
Name Type Description
name String

Name of the extension

message String

The message to print

Source:

Type Definitions

onEnd() → {Boolean}

Called when an extension is unloaded

Source:
Returns:

Return true if the extension was successfully unloaded

Type
Boolean

onInit(configuration) → {Boolean or Deferred}

Called when an extension is loaded

Parameters:
Name Type Description
configuration Object

The configuration passed to extensions.load

Source:
Returns:

Return true if the extension was successfully initialized, for asynchronous initializations the callback can return a Deferred, to indicate a successful initialization either call deferred.resolve(true), to indicate an error either call deferred.resolve(false) or deferred.reject(reason) on the deferred

Type
Boolean or Deferred

onLoadChrome(wv, uri) → {String}

Callback when a chrome document should be loaded.

Parameters:
Name Type Description
wv WebKitWebView

The webview that requested the chrome document

uri String

The uri of the chrome document

Source:
Returns:

The html-document that should be loaded

Type
String