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")];
- 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:
- 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)