Useful Conkeror Browser Objects

It feels like a long time since I’ve written about Conkeror, my web-browser of choice. Today I want to share with you some browser objects. They are the prefixes to Conkeror commands, the ‘nouns’ of the language, so to speak. Today I’ll show you some useful ones which are built into Conkeror along with a couple customized ones of my own.

Quick Introduction

Conkeror’s quick start page lists key sequences for some of the built-in browser objects. The object comes first, then the command to perform on that object. For example:

• i c: Copy the URL for an image.
• n b: Bookmark a link.
• m b: Bookmark a frame.
• e r: Reload a piece of media.

GNU Emacs influences a lot of Conkeror and so we can use Emacs’ C-h k to see documentation about any of the browser objects above, or any key for that matter. Doing so will tell us that the definitions for these browser objects comes from the file modules/element.js in the Conkeror source-code. For example, i is bound to the browser object for images, which Conkeror defines like so:

define_browser_object_class("images",
    "Browser object class for selecting an html:img via hinting.",
    xpath_browser_object_handler("//img | //xhtml:img"),
    $hint = "select image");

The definition uses xpath_browser_object_handler(), a utility function that we will see a lot. Browser objects typically represent one or more HTML tags that contain the data we want to open, save, copy, and so on. That utility function allows us to describe such tags using XPath, a language for addressing arbitrary elements in an HTML or XML document. The expression in the example above tells Conkeror that images, as a browser object, are anything marked with <img/> or <xhtml:img/> tags.

Built-in Unbound Browser Objects

The following is a list of useful browser objects that Conkeror defines but does not bind to any key by default. This is how we can bind keys to browser objects:

define_key(content_buffer_normal_keymap, "i", "browser-object-images");

This specific example is superfluous because Conkeror already binds this key. However, note well how we bind "browser-object-images" to the key. Conkeror automatically creates names for browser objects when we define them. So from our first example:

define_browser_object_class("images", /* … */);

This creates the "browser-object-images" name that we used for the key-binding. That means calling define_browser_object_class("foo", ...) defines the name "browser-object-foo" for us to use elsewhere. This is how we know the names of the browser objects based only on their definitions in files like modules/element.js.

With all of that said, here is an incomplete list of useful browser objects which have no default key-bindings:

• browser-object-mathml: Matches MathML elements like <m:math/>.

• browser-object-paste-url: Automatically uses the URL currently on the clipboard. If one is not available then Conkeror will prompt us to enter a URL. Note: Support for this on non-Linux platforms is shaky.

• browser-object-alt: Matches the content of alt attributes on image tags.

• browser-object-title: Matches the <title/> of a document.

• browser-object-scrape-url: One of my favorites, this presents us with a list of URLs scraped from the source of the page we’re browsing.

Couple of Mine

Here are some custom browser objects I use. To use them you only need to copy them into your configuration and then use the M-x reinit command to load them—easier than closing and re-opening the browser.

define_browser_object_class(
  "rss-feed",
  "Browser object for RSS feeds.",
  xpath_browser_object_handler(
    "//link[@type='application/rss+xml'] | " +
      "//a[@id='rss-link']"),
  $hint = "RSS feeds"
);

I use this one to find RSS links on pages. Normally they appear in <link/> tags, which is what the browser object first searches for. But WordPress sites often have a tag in the form of <a id="rss-link">...</a>, which the object also matches.

define_browser_object_class(
    "form-input",
    "Browser object for selecting input or textarea form fields.",
    xpath_browser_object_handler(
        "//input[not(@type='hidden')] "
            + "| //textarea "
            + "| //*[@contenteditable='true'] "
            + "| //xhtml:input[not(@type='hidden')] "
            + "| //xhtml:textarea"
            + "| //xhtml:*[@contenteditable='true']"),
    $hint = "form inputs"
);

I find this browser object useful in conjunction with the f ‘follow’ command for navigating pages. Some commands will use a default browser object if you do not provide one; f will default to using browser-object-links. But by binding the browser object above to a key sequence—I use ' f—I can easily navigate forms by pressing ' f f.

Conclusion

So there you go, a brief overview of some pre-existing Conkeror browser objects and some examples from my own configuration. If you find yourself even semi-frequently selecting or doing anything with a type of page element then I recommend creating a browser object for it. Once you become comfortable with that I suggest looking in modules/element.js for the definition of browser-object-text, which creates a ‘composable object’, one which you can combine with others. It’s also a topic I will write about another day.