This document describes the module system that was introduced with version 0.9.2.

glossary

application (or global) scope

This refers to the scope of the singleton conkeror object, defined in components/application.js.

feature

A symbol (given as a string) added to the features list by a module, which other modules can use to tell if that module has been loaded. Features should be lower case, using only hyphens for punctuation. A module which provides a given feature should have that feature name as its file name, plus a .js extension.

load

The default behavior of load is to try to load the module directly into application scope.

require

Require is simply a conditional load. Require parses passed module spec (filename) and guesses what feature that file provides. If that feature has already been provided, it returns without loading. The default behavior of require is to try to load the module in its own namespace.

Optional Modules

Conkeror has a number of core module that are required for Conkeror to run and which are always loaded at startup. In addition, though, there are a growing number of optional modules that provide additional functionality. Such modules include

• bindings/default/bindings.js - provides the default key bindings;

• tab-bar.js - provides a Firefox-style tab bar;

• clicks-in-new-buffer.js - load middle-clicked links in new buffers. See Tips for more information.

• mode-line.js - provides an Emacs-style mode line;

• daemon.js - provides support for pre-loading Conkeror without opening any Windows and allowing it to remain running even after all open windows have closed;

• extensions/dom-inspector.js - provides a Conkeror-specific interface to the DOM inspector extension;

• various page modes, analogous to Emacs major modes, that provide certain Greasemonkey-like functionality for individual sites including Youtube, Google Video, Google Reader, Google Mail, Google search results pages, and Reddit.

Certain Mozilla preferences are used to specify which, if any, of these optional modules are loaded at startup. Specifically, whether a particular module <module-name>.js (where <modules-name> might be extensions/dom-inspector as an example) is loaded automatically at startup (note that you can also load modules explicitly in your ConkerorRC file, and that is unrelated to these preferences) is controlled by the three preferences

• conkeror.loadDefaultModules - "tristate" integer, defaulting to 1 (it is "tristate" in that it has only three distinct meanings, dependent on whether it is positive, zero, or negative);

• conkeror.loadModules - string specifying a regular expression to match against <module-name> (i.e. it should not attempt to match a .js extension), defaulting to the empty string, which doesn't match anything;

• conkeror.load.<module-name> - "tristate" integer, which may default to either 1 or 0, or alternatively may be unset, but most if not all optional modules have a default setting for this preference; whether this preference has a user-set value as opposed to just its default value is significant.

The module is loaded according to the following rules:

• The module is never loaded unless conkeror.load.<module-name> has a non-negative value. In particular, if this preference has no value set, then the module is not loaded.

• If conkeror.loadDefaultModules is positive and conkeror.load.<module-name> has a positive value, then the module is loaded.

• If conkeror.loadDefaultModules is zero and conkeror.load.<module-name> has a positive user-set value (i.e. not merely a default value that is positive), then the module is also loaded.

• Regardless of the setting of conkeror.loadDefaultModules, if the regular expression conkeror.loadModules matches <module-name> completely (i.e. a partial match is not sufficient), then the module is still loaded.

• Otherwise, the module is not loaded.

Modules that meet these condiions are loaded in an arbitrary order consistent with their dependencies (where the dependencies are given by any calls to the require function in the module itself).

Note that the conkeror.loadModules preference only has an effect if conkeror.loadDefaultModules is non-positive. It can be useful for concisely specifying that only certain classes of modules are desired by default. For example, if it is set to "(bindings/default|extensions|page-modes)/.*", exactly the set of modules in the directories bindings/default/ (the default key bindings), extensions/ (extension support modules), and page-modes/ that have a conkeror.load.<module-name> preference set to a non-negative value (all modules by default) will be loaded automatically at startup.