User Variables

Conkeror has many behaviors that can be customized by setting certain ordinary variables in your rc script. We will try to describe them all here.

NOTE: user variables are not the same as user and session preferences.

active_hint_background_color
String color for the active hint. Default is "#88FF00".
active_img_hint_background_color
String color for the active image hint. Default is "#88FF00".
allow_browser_window_close

If this is set to true, if a content buffer page calls window.close() from JavaScript and is not prevented by the normal Mozilla mechanism that restricts pages from closing a window that was not opened by a script, the buffer will be killed, deleting the window as well if it is the only buffer. Default is true.

auto_mode_list
A list of mappings from URI regular expressions to page modes. This should probably only be changed to add new page modes. See modules/page-modes/ for examples.
block_content_focus_change_duration

Duration (in milliseconds) during which an element is allowed to gain focus following a mouse click or key press, if block_content_focus_change_mode is enabled.

browser_automatic_form_focus_window_duration

note: As of November 2, 2009, this variable was renamed to block_content_focus_change_duration. The documentation for it will be left up for a reasonable amount of time in order to be available to people running an older version of Conkeror from their OS.

Time window (in milliseconds) during which a form element is allowed to gain focus following a mouse click or key press, if browser_prevent_automatic_form_focus_mode is enabled. Default is 20.

browser_default_open_target

Specifies how new window requests by content pages (e.g. by window.open from JavaScript or by using the target attribute of anchor and form elements) will be handled. This will generally be OPEN_NEW_BUFFER, OPEN_NEW_BUFFER_BACKGROUND, or OPEN_NEW_WINDOW. Default is OPEN_NEW_BUFFER.

browser_form_field_xpath_expression

XPath expression matching elements to be selected by browser-focus-next-form-field and browser-focus-previous-form-field. Default is 

  •   "//input[" + (
        //        "translate(@type,'RADIO','radio')!='radio' and " +
        //        "translate(@type,'CHECKBOX','checkbox')!='checkbox' and " +
        "translate(@type,'HIDEN','hiden')!='hidden'"
        //        "translate(@type,'SUBMIT','submit')!='submit' and " +
        //        "translate(@type,'REST','rest')!='reset'"
    ) +  "] | " +
        "//xhtml:input[" + (
            //        "translate(@type,'RADIO','radio')!='radio' and " +
            //        "translate(@type,'CHECKBOX','checkbox')!='checkbox' and " +
            "translate(@type,'HIDEN','hiden')!='hidden'"
            //        "translate(@type,'SUBMIT','submit')!='submit' and " +
            //        "translate(@type,'REST','rest')!='reset'"
        ) +  "] |" +
        "//select | //xhtml:select | " +
        "//textarea | //xhtml:textarea | " +
        "//textbox | //xul:textbox"
browser_relationship_patterns

Patterns used by follow-next and follow-previous. By default, we have 

  •   browser_relationship_patterns[RELATIONSHIP_NEXT] =
    [/^next$/i,
     new RegExp("^>$","i"),
     new RegExp("^(>>|»)$","i"),
     new RegExp("^(>|»)","i"),
     new RegExp("(>|»)$","i"),
     new RegExp("\\bnext","i")
    ];

   browser_relationship_patterns[RELATIONSHIP_PREVIOUS] =
    [/^(prev|previous)$/i,
     new RegExp("^<$","i"),
     new RegExp("^(<<|«)$","i"),
     new RegExp("^(<|«)","i"),
     new RegExp("(<|«)$","i"),
     new RegExp("\\bprev|previous\\b","i")
    ];
can_kill_last_buffer
Boolean controlling whether the kill-buffer command can kill the last buffer in a window.
clicks_in_new_buffer_button
Which mouse button should open links in a new buffer.
  • 0 = left, 1 = middle, 2 = right. Default is 1. (With require("clicks-in-new-buffer.js")).
clicks_in_new_buffer_target
How to open links in a new buffer, in the foreground or the background. Set to one the constants OPEN_NEW_BUFFER or OPEN_NEW_BUFFER_BACKGROUND. Default is OPEN_NEW_BUFFER.
  • (With require("clicks-in-new-buffer.js")).
clock_time_format

Format string for the mode-line clock widget. It takes the same format as strftime() in C. See http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html for details. Default is "%R", which is hours and minutes in 24-hour format.

content_handlers

A mime type table mapping mime types to content handlers. This table will be checked for a match when a navigation event causes Conkeror to encounter a mime type which is not supported by Mozilla. If no appropriate content handler is found in this table, the user will be prompted to choose from among common actions. No handlers are registered by default. See ContentHandlers for details on how to manipulate the table.

cwd

Abbreviation for current working directory. It is used as your default download directory, and the directory for shell commands. Individual buffers and pages may have their own local cwd. The change-directory command sets the buffer-local cwd. The value must be an nsILocalFile object. The function make_file will make an nsILocalFile from a string path. The default value of cwd is your home directory.

daemon_quit_exits

Boolean controlling whether daemon-mode abides the quit command. Default is true.

default_minibuffer_auto_complete_delay
Delay (in milliseconds) after the most recent key stroke before auto-completing. Default is 150.
delete_temporary_files_for_command
If this is set to true (the default), temporary files downloaded to run a command on them will be deleted once the command completes. If not, the file will stay around forever unless deleted outside the browser.
download_buffer_automatic_open_target

Target for download buffers created by open_download_buffer_automatically. The default is OPEN_NEW_WINDOW.

download_buffer_min_update_interval
Minimum interval (in milliseconds) between updates in download progress buffers. Lowering this interval will increase the promptness of the progress display at the cost of using additional processor time. Default is 2000 (ms).
download_temporary_file_open_buffer_delay

Delay (in milliseconds) before a download buffer is opened for temporary downloads. This variable takes effect only if open_download_buffer_automatically is in download_added_hook, as it is by default. Default is 500.

edit_field_in_external_editor_extension
Default is "txt". File extension for the temp files created by edit-current-field-in-external-editor.
editor_shell_command

Shell command used to invoke an external editor. Default is the value of the environment variable EDITOR. It is used as part of a shell command in the following two ways: 

  •     <editor_shell_command> <file>
    <editor_shell_command> +<line> <file>

Windows users should reference ConkerorSpawnHelper and include a trailing .exe on any executables set here. Non-null run_external_editor_function overrides this setting. Default is 

  •   getenv("VISUAL") || getenv("EDITOR") || "emacs"
external_content_handlers
A mime-type table containing associations of mime types to programs that can handle content of that type. Used by commands and actions that entail running an external program on content. The default contents of the table are: 
  •   {
      "*": getenv("EDITOR"),
      text: { "*": getenv("EDITOR") },
      image: { "*": "feh" },
      video: { "*": "mplayer" },
      audio: { "*": "mplayer" },
      application: {
          pdf: "evince",
          postscript: "evince",
          "x-dvi": "evince"
      }
  }

See ContentHandlers for more information about manipulating the table.

eye_guide_context
A setting for the eye-guide commands. Context size in pixels for eye-guide-scroll-down and eye-guide-scroll-up. Default is 50.
eye_guide_interval
A setting for the eye-guide commands. Interval during which the eye guide is visible (in ms). When 0, the eye guide will remain visible. Default is 800.
favicon_image_max_size
Maximum (pixel) width and height of an image document that is considered for use as a favicon. Default is 1024.
forced_charset_list
An alist mapping url regexps to charsets.
hint_background_color
String color name for hints. Default is "yellow".
hints_ambiguous_auto_exit_delay
Delay (in milliseconds) after the most recent key stroke before the first of an ambiguous match is automatically selected. If this is set to 0, automatic selection in ambiguous matches is disabled. Default is 0.
hints_auto_exit_delay
Delay (in milliseconds) after the most recent key stroke before a sole matching element is automatically selected. If this is set to 0, automatic selection is disabled. Default is 0.
hints_display_url_panel
When selecting a hint, the URL can be displayed in a panel above the minibuffer. This is useful for confirming that the correct link is selected and that the URL is not evil. This option is most useful when hints_auto_exit_delay is long or disabled.
homepage
Default url for content buffers.
img_hint_background_color
String color for image hints. Default is "yellow".
index_webjumps_directory

A directory (instance of nsILocalFile) for storing the index files corresponding to index webjumps; the index data can be downloaded from the index URL using webjump-get-index. If the index file is available for an index webjump then the webjump will provide completions for the indexed URLs.

index_xpath_webjump_tidy_command
A command to run on the downloaded index. The xulrunner parser is quite fussy and specifically requires xhtml (or other xml). Running something like html tidy can avoid parser problems.
isearch_keep_selection
Default is false. When true, the selection will always be left visible after completing an isearch.
key_bindings_ignore_capslock

When true, the state of capslock will be overridden for key combos that contain characters. If shift was pressed with the character, the character will be forced to upper-case, and otherwise forced to lower-case. This only affects keys bound to commands. Capslock will still work as normal when typing in input fields. The default value of this variable is false.

keyboard_key_sequence_help_timeout
Delay (in milliseconds) before the current key sequence prefix is displayed in the minibuffer. Default is 0.
kill_whole_line

Default is false. When true, the command cut-to-end-of-line will also cut the newline character at the end, when point is at the beginning of a line.

load_paths

Array of URL prefixes searched in order when loading a module. Each entry must end in a slash, and should begin with file:// or chrome://.

media_scrape_default_regexp
Regular expression used by the default media scraper to match URIs for embedded media in the page source code. Defaults to 
  •   new RegExp("(?:http://[a-zA-Z0-9.\\-]+/)?(?!://)[^=&<>\"'|\\s]+\\.(?:aiff|au|avi|flv|mid|mov|mp3|mpg|mpeg|ogg|ra|rm|spl|wav|wma|wmv)(?!\\w)", "ig")
media_scrapers

Function (or coroutine) to use to scrape the current buffer for embedded media. Default is [media_scrape_default] (see media.js).

mime_type_external_handlers

note: this variable was removed as of October 12, 2009. The documentation for it will be left up for a reasonable amount of time in order to be available to people running an older version of Conkeror from their OS. This variable was replaced by external_content_handlers. See ContentHandlers for details.

An array of two element arrays, associating mime type patterns with handler programs. The patterns are regular expressions. When conkeror looks for an external handler, the program corresponding to the first matching pattern will be used. The default value of mime_type_external_handlers is: 

  • [[/^text\/.*$/, getenv("EDITOR")],
 [/^image\/.*$/, "feh"],
 [/^video\/.*$/, "mplayer"],
 [/^audio\/.*$/, "mplayer"],
 [/^application\/pdf$/, "evince"],
 [/^application\/postscript$/, "evince"],
 [/^application\/x-dvi$/, "evince"],
 [/^.*$/, getenv("EDITOR")]]

    An API exists for manipulating this array; see MimeTypeHandlers for details.

minibuffer_auto_complete_default

Boolean specifying whether to auto-complete by default. The user variable minibuffer_auto_complete_preferences overrides this. Default is false.

minibuffer_auto_complete_preferences
minibuffer_history_max_items
Maximum number of minibuffer history entries stored.Older history entries are truncated after this limit is reached. Default is 100.
minibuffer_input_mode_show_message_timeout
Time duration (in milliseconds) to flash minibuffer messages while in minibuffer input mode. Default is 1000.
minibuffer_read_url_select_initial
Specifies whether a URL presented in the minibuffer for editing should be selected. This affects find-alternate-url. Defaults to true.
read_url_handler_list
A list of handler functions which transform a typed url into a valid
  • url or webjump. If the typed input is not valid then each function on this list is tried in turn. The handler function is called with a single string argument and it should return either a string or null. The result of the first function on the list that returns a string is used in place of the input. Example: 
      read_url_handler_list = [read_url_make_default_webjump_handler("google")];
run_external_editor_function

Coroutine function called to invoke an external editor. If this variable is set to a function, it is used to invoke an external editor in place of editor_shell_command. It is called with the filename as the first argument, and optionally the boolean keyword argument $temporary specifying whether the file should be deleted after the editor is closed, and optionally the keyword argument $line specifying a line number to display. The create_external_editor_launcher function is convenient for generating a function suitable for use as the value of this variable.

title_format_fn
url_completion_use_bookmarks

Boolean Default is true. Controls whether bookmarks will be included in the completion list when prompting the user for an url, for example, with the open-url command.

url_completion_use_history

Boolean Default is false. Controls whether urls in the browse history will be included in the completion list when prompting the user for an url, for example, with the open-url command.

url_completion_use_webjumps

Boolean. Default is true. Controls whether webjumps will be included in the completion list when prompting the user for an url, for example, with the open-url command.

url_remoting_fn

"Url remoting" is the term for invoking Conkeror with an url (for example, from a command line) when a Conkeror process is already running. The new invocation is said to "remote" the url to the already running process. The variable url_remoting_fn is a function to dispatch on urls remoted into Conkeror. The default value is load_url_in_new_window. Though you can easily write your own url remoting function, obvious ones are already included in conkeror:

  • load_url_in_new_window

  • load_url_in_new_buffer

  • load_url_in_current_buffer

view_source_function

May be set to a user-defined function for viewing source code. The function should accept an nsILocalFile of the filename as its one positional argument, and it will also be called with the keyword $temporary, whose value will be true if the file is considered temporary, and therefore the function must take responsibility for deleting it.

view_source_use_external_editor

When true, the view-source command will send its document to your external editor. Default is false.

webjump_partial_match
Default is true. When entering a url, if the input is not a webjump, but would uniquely complete to a webjump, then accept that webjump only if this is true.
window_extra_argument_max_delay
xkcd_add_title
Default is false. When true, xkcd-mode will scrape the alt text from the xkcd comic and insert it into the page below the comic.
youtube_scrape_function
This function is called as the last step of scraping a youtube page, after the basic information needed to build the media url has been extracted. Youtube_scape_function is called with four arguments: a `push' function, the id, the t key, and the text of the page. Its job is to call the push function for each media url desired with the arguments url, file extension, mime type, and description. It should return true if it called the push function at least once, and otherwise false. The default is: 
make_call_each(youtube_scrape_1080p_mp4,
               youtube_scrape_720p_mp4,
               youtube_scrape_hq_mp4,
               youtube_scrape_standard_flv)

UserVariables (last edited 2010-07-07 17:13:24 by JohnFoerch)