Basic Page Mode

We will walk through building a whiz-bang little page mode for that most ubiquitous of Internet grottos, example.com.

define_page_mode

The main form of any page mode is the define_page_mode form. Its two required arguments are the symbolic name of the page mode, and the human-readable name. In addition to the required arguments, it accepts several optional keyword arguments. Typically, you will use both $enable and $disable, which give the setup and teardown functions for your mode. Each takes a buffer as its single argument.

define_page_mode("example_mode", "Example",
                 $enable = function (buffer) {
                     // setup
                 },
                 $disable = function (buffer) {
                     // teardown
                 });

auto_mode_list

Telling Conkeror when to turn on your page mode is as simple as adding a handler to auto_mode_list. You make a regular expression that matches the urls for which your page mode is intended, and push that, in association with your page mode function, onto auto_mode_list. This registration should be the last thing in the javascript file for your page mode. We'll start with a short example, then we'll pick it apart.

let (re = build_url_regex($domain = "example",
                          $tlds = ["com", "net", "org"],
                          $allow_www = true)) {
    auto_mode_list.push([re, example_mode]);
};

build_url_regex

Since creating regular expressions to match urls has patterns that are used over and over again, Conkeror has a function to simplify the creation of these regular expressions, called build_url_regex. It takes several keyword arguments that specify parts of an url, and produces a regexp.

$domain

A regexp or a literal string to match the domain name, not including the top-level domain (.com, .net, .org, etc), and not including www., unless the www. is required.

$allow_www

Boolean where true means that the domain name may optionally have the subdomain www.. Default is false.

$tlds

A list of allowed top-level domains. The default is the list ["com"].

$path

A regexp or a literal string to match against the path portion of the url, excluding the initial /. The default matches any path.