welcome: please sign in
location: ReadUrlHandlers

The read-url prompt can be configured to transform patterns of input to urls, beyond the simple capabilities of the webjump system. This configuration is done through read-url handlers, and they take effect when an input to the prompt is neither url-like nor a webjump. Input is a webjump when the first token before any inner space is the name of a webjump. When input is 'url-like' is a subtler question..

1. URL-like

When text is entered at the url prompt, Conkeror needs to decide whether the text should be treated as an url, a webjump, or passed to the read-url handlers. Deciding what counts as an url is not as trivial as it might appear at first, because if Mozilla is given a string which is not a well-formed url, it will still attempt to resolve it by prepending http://, append .com, and so on. The default behavior of read-url is to consider any string as url-like if it does not have any inner spaces before the first '/'. This behavior can be changed by overriding the function possibly_valid_url in your rc.

1.1. possibly_valid_url

Here is an alternative version which requires the string to contain either a dot, a slash, or a colon to be considered url-like. This version works better when you have configured a default webjump because it means a single bare word will not be considered url-like: it allows your default webjump to be called instead.

function possibly_valid_url (str) {
    return /^\s*[^\/\s]*(\/|\s*$)/.test(str)
        && /[:\/\.]/.test(str);
}

2. read_url_handler_list

Now that we know when read-url handlers are called, how do we use them? The variable read_url_handler_list is an array of semipredicates. When the input is neither url-like nor a webjump, the handlers are tried in order until one returns non-null, and that handler's value is taken as the value for the prompt. This mechanism can be used to extend the url prompt with handlers for special syntaxes, provide a default webjump, or more. Some utilities are provided for common uses.

2.1. read_url_make_default_webjump_handler

This function takes the name of a webjump and returns a read-url handler that transforms the input into a call to that webjump with the given input. This is how you make a default webjump.

2.2. read_url_make_blank_url_handler

This function takes an url as its argument and returns a read-url handler that returns the url if the input is blank. This allows you to have a default url or javascript bookmarklet for empty input.

3. Examples

In each of the following examples, for sake of completeness, we give a line that assigns an array containing the handler from the particular example to read_url_handler_list. If you want to use more than one read-url handler, then you would provide a different value for this variable — an array containing all of the handlers you want to use.

3.1. Default Webjump

read_url_handler_list = [read_url_make_default_webjump_handler("conkerorwiki")];

3.2. Google translate

This transforms input like "xx|yy foo" into a Google translate url, translating the string "foo" from language code "xx" to language code "yy". Example: la|en semper ubi sub ubi

function read_url_google_translate_handler (input) {
    var m = /^(\S+\|\S+)\s+(.*)/.exec(input);
    if (m)
        return "http://translate.google.com/#"+m[1]+"|"+m[2];
    return null;
}
read_url_handler_list = [read_url_google_translate_handler];

Conkeror.org: ReadUrlHandlers (last edited 2012-03-06 00:56:08 by retroj)