welcome: please sign in
location: Diff for "BreakingChanges"
Differences between revisions 121 and 122
Revision 121 as of 2014-05-01 18:06:23
Size: 31341
Editor: retroj
Comment: update
Revision 122 as of 2016-02-05 03:13:53
Size: 31432
Editor: scottjad
Comment: Mention MinVersion=2.0
Deletions are marked like this. Additions are marked like this.
Line 9: Line 9:

== February 4, 2016 ==

Conkeror now requires Xulrunner 2.0 (Firefox 4) or greater.

This page is about changes to Conkeror that may make it necessary for you to update your rc, or that change UI behavior in a non-trivial way. We recommend subscribing to this page, so that you will be notified by email of important changes to Conkeror.


February 4, 2016

Conkeror now requires Xulrunner 2.0 (Firefox 4) or greater.

May 1, 2014

The keyword $match_required was renamed to $require_match. (Following Emacs convention.)

Completers are now instantiated with the new keyword, so calls like "all_word_completer(...)" become "new all_word_completer(...)".

javascript_completer no longer treats the current buffer or window as special. Instead of taking a buffer as its argument, it takes any object, and that object is the scope from which it draws completions.

define_webjump keyword $description was renamed to $doc.

define_webjump keyword $argument has been removed. It was found unnecessary for this value to be provided explicitly by webjumps, as it can be derived from other webjump properties.

get_shell_command_completer replaced by shell_command_completer (instantiated with new).

'require_match' is now a property of webjumps instead of a property of completions objects. Further discussion of this change is here below:

  • Nested completers present a hard problem with respect to the require_match property, and where exactly this flag belongs when a nested completer, like webjump_completer, needs it (in some cases). As a UI concern, it is clear that it breaks abstraction to use completions objects to carry this flag from webjump to reader, and it necessitates overmuch plumbing to do so. It makes more sense to put the property on webjumps, because it is in a very literal sense a property of the webjumps that a match is required. But the reader doesn't know anything about webjumps, so in order to communicate

December 5, 2012

Spellchecking is no longer enabled by default. To allow Gecko to decorate your text boxes with red marks, put the following in your rc:

session_pref("layout.spellcheckDefault", 1);

December 2, 2012

The deprecated procedures add_delicious_webjumps and add_lastfm_webjumps have now been removed. Use define_delicious_webjumps and define_lastfm_webjumps instead.

April 6, 2012

hints-minibuffer-annotation-mode is now enabled by default. To disable:


March 10, 2012

Variable hints_display_url_panel removed. Instead of the url-panel, Conkeror now has hints-minibuffer-annotation-mode. To use it:


February 15, 2012

buffer_loaded_hook now fires only for the main document of the buffer, not documents in subframes.

February 12, 2012

The test property of page-mode objects is now an array.

January 31, 2012

  • in_module removed

  • The module system introduced 2010-03-19 had a fatal flaw in its design. We have known about this for quite some time, but fixing it was a complex undertaking. Now the 'in_module' procedure has been removed from the program, because it doesn't work, and a new module system has been added, the jsx module system.
  • Anybody who has written a module that is not part of Conkeror will need to update their code. Remove uses of 'in_module'. If you only did 'in_module(null);' then you can just remove that line and you are done. If you used 'in_module("module_name");' you will need to remove that, and rename your file to have the extension ".jsx". The rest of the filename should match the name of the module, except using hyphens to separate words.
  • skip_module_load removed

  • casual-spelling.js renamed to casual-spelling.jsx

January 29, 2012

  • The "up-url" browser object will now trim a #ref fragment as one of its steps.
  • New buffers with an opener buffer in the same window open to the right of their opener.

January 27, 2012

  • build_url_regex renamed to build_url_regexp

  • choice_regex renamed to choice_regexp

  • Call forms of define_buffer_mode and define_page_mode changed.

  • auto_mode_alist no longer exists.

  • The way to deactivate page-modes has changed.
  • Instead of the old way of doing complicated array manipulations on 'auto_mode_list', the new way is much simpler. If I want to deactivate xkcd-mode for example (make it so it won't automatically turn on when I visit xkcd), I do the following:
  • The call form to enable or disable a buffer-mode or page-mode in javascript has changed.
  • (Note the distinction between 'deactivating' and 'disabling'.) Instead of the mode being a function that takes a flag -1/+1 or true/false (like in emacs), it is now an object with 'enable' and 'disable' methods:

January 5, 2012

clusty webjump removed. clusty no longer exists.

October 13, 2011

Conkeror now depends on XULRunner 1.9.1 or higher.

September 23, 2011

The copy command now copies the action attribute of the form when called on a submit button.

September 22, 2011

Google-maps: changed bindings '+' and '-' to 'C-c +' and 'C-c -', because it is poor practice to override basic browsing keys then they are still clearly useful on the site in question.

September 16, 2011

Renamed get_file_in_path to find_file_in_path.

September 6, 2011

Formfill is now enabled by default. To turn it off, do: session_pref("browser.formfill.enable", false);

September 5, 2011

youtube_scrape_function and associated helpers removed.


Note: after version 0.9.3, the Conkeror project switched to a more traditional version number scheme. There was one final milestone in the old system, called 0.9.4, then we began preparing for a 1.0 release. Consequently, as you read this page, the meaning of version numbers changes at this point. Under the old system (below this paragraph on this page), the listed changes took place during that version. For example, the changes under the head 0.9.3 took place while Conkeror's version was 0.9.3. Under the new system (above this paragraph), the listed changes took place in the runup to the release of the listed version.


January 6, 2011

In the new-tabs module, the widgets that show the buffer index in each tab now have the class "tab2-index" instead of "tab2-icon". This change affects anybody who has written a theme which styles the new-tabs tab bar.

December 31, 2010

  • The variable edit_field_in_external_editor_extension has been removed, and superseded by a mime-type table external_editor_extension_overrides which maps mime types to extensions. If you previously used this variable to set the temp file extension to "foo", for example, you would update your rc to now do the following:

    external_editor_extension_overrides.set("text/plain", "foo");
  • The function get_filename_for_current_textfield has been superseded by external_editor_make_base_filename, which takes as its arguments the root element being edited and the top document of the buffer containing the element. The top document is more useful than the element's own ownerDocument in some cases, such as when about:blank is used for the document of an editable iframe. The new function returns only the base filename, with no extension, as the extension is generated by means described above.

December 29, 2010

  • buffer_favicon_change_hook renamed to buffer_icon_change_hook

  • current_buffer_favicon_change_hook renamed to current_buffer_icon_change_hook

December 20, 2010

Reddit-mode is no longer loaded by default. Consensus was that it is a confusing mode, mainly because of how it overrides several default browser objects. If you use this mode, you will now need to load it by putting the following in your rc:


December 6, 2010

The environment variable 'HOME' is now checked on Windows, in get_home_directory. This counts as a breaking change because windows users who happen to have this variable set may now need to adjust their setup, as Conkeror will look for the rc in 'HOME' before it looks in 'USERPROFILE' or 'HOMEDRIVE'+'HOMEPATH'.

November 5, 2010

Module search-engine.js replaced by opensearch.js. API for defining opensearch webjumps has changed to be more conventional. Opensearch webjumps can now be defined like either of the following:

define_opensearch_webjump("foo", make_file("/opensearch/files/foo.xml"));

define_opensearch_webjump("foo", "foo.xml");

November 3, 2010

The browser object browser-object-links, which is used by follow, copy, etc, no longer matches anchors which do not have an href attribute.

October 12, 2010

The eval-expression command (M-:) now evaluates directly in application scope. This lets you do things like set user variables and define functions without fully qualifying names with "conkeror.".

October 9, 2010

Page-modes no longer bind alternative keys for keys that they shadow in the normal keymaps. These were bindings like 'C-c f' for follow, etc. The key C-z can now be used as a prefix to access bindings that are shadowed by a page-mode keymap.


September 26, 2010

Input-modes removed. Instead of an input-mode display in the minibuffer, there is now a keymaps-display.

  • quote-next-input-mode renamed to quote-next-mode

  • gmail_edit_keymap removed (no longer necessary)

  • buffer-reset-input-mode command removed (no longer necessary)

overlink_mode rewritten

  • content_buffer_overlink_change_hook removed

  • current_content_buffer_overlink_change_hook removed

September 17, 2010

Hinting now performs a case-sensitive match if the user's text includes upper-case letters.

September 15, 2010

Renamed stackoverflow-mode to stackexchange-mode.

June 24, 2010

  • Editing in the minibuffer is now done with the normal editing commands instead of a special set of editing commands. All of the editing commands which begin with the prefix "minibuffer-" have been removed. Also, editing commands are now bound in the keymap text_keymap instead of content_buffer_text_keymap and minibuffer_base_keymap. If you have written custom bindings for editing in your rc, you will need to change [pairs of] bindings like this:

define_key(minibuffer_base_keymap, "C-l", "minibuffer-forward-char");
define_key(content_buffer_text_keymap, "C-l", "forward-char");

to this:

define_key(text_keymap, "C-l", "forward-char");
  • In hinting mode, right and left are no longer bound to next/previous-hint. Hinting mode now supports editing in the minibuffer, so right and left move the cursor. Down, up, C-n, C-p, C-s, and C-r are all bound to next/previous-hint.

May 19, 2010

Due to a change in Mozilla as of XULRunner 1.9.3a5pre, Conkeror's feature of automatically loading glue code for extensions is no longer possible. This means that when you have one of the previously supported extensions installed, you will no longer automatically have Conkeror commands for using the extension. The extensions that were previously supported in this way were adblockplus, dom-inspector, noscript, and venkman. If you have any of these extensions installed, you will now have to load the glue module from your rc, with a line like the following, substituting in the appropriate module name:


With some of these modules, loading the module when the extension is not installed could result in an error, so to be safe, you could wrap the call to 'require' in a try/catch block:

try { require("dom-inspector"); } catch (e) {}

Further information: http://bugs.conkeror.org/issue272

May 8, 2010

The variable download_buffer_automatic_open_target can no longer be an array of two targets. This is a reversion from 2009-06-07 back to how it was before. The behavior of the download-show command is now configured independently of this variable. To configure download-show, use set_handler and alternates. The following handlers are provided: download_show_new_window, download_show_new_buffer, download_show_new_buffer_background. The default handler of download_show is alternates(download_show_new_buffer, download_show_new_window).

April 6, 2010

Function load_rc no longer supports loading arbitrary js files. Use load instead.

Function load_rc_file removed. Use load instead.

April 5, 2010

The module casual-spelling now loads into the scope casual_spelling. Its functions and variables were renamed accordingly.

March 22, 2010

call_after_load now takes a feature name, not a filename. In general this simply means trimming off any ".js" extension.

Modules should have an in_module assertion as their first expression. For modules to be loaded directly into application scope, it should be in_module(null);

Modules should have as their last expression a provide call, like provide("feature"); where "feature" is the name of the feature provided by the module.


March 7, 2010

emacswiki webjump removed. better version posted on Webjumps.

February 28, 2010

M-< and home keys now scroll to the top left corner of the buffer.

February 25, 2010

minibuffer.read_url now returns a load_spec instead of a simple string.

February 21, 2010

The command confirm-quit has been removed. To have a quit confirmation, put the following in your rc:

         function () {
             var w = get_recent_conkeror_window();
             var result = (w == null) ||
                 "y" == (yield w.minibuffer.read_single_character_option(
                     $prompt = "Quit Conkeror? (y/n)",
                     $options = ["y", "n"]));
             yield co_return(result);

November 22, 2009

Youtube scraper functions renamed to more accurate names. This affects anyone who has customized youtube_scrape_function in his or her rc.

  • youtube_scrape_standard






Also, a scraper youtube_scrape_1080p was added.

November 19, 2009

Gitweb summary webjumps are now implemented as index webjumps. The webjump-get-index command and index_webjumps_directory variable are used rather than the previous gitweb equivalents. Existing gitweb opml files can be moved to the new locations using something like:

cd ~/.conkerorrc
mkdir index-webjumps
for f in gitweb-webjumps-opml/*.opml; do
  mv $f index-webjumps/$(basename $f .opml).index
rmdir gitweb-webjumps-opml

The $completer option is no longer available.

November 6, 2009

  • hints_auto_exit_delay: change default to 0
  • This change means that by default, the user has to hit return to exit the hints interaction. This change makes Conkeror's UI more predictable for new users, less prone to run unintended commands because of extra keystrokes outside the timeout window, and removes assumptions about people's typing speed, browsing style, and focus of attention when using the hints system.
  • To use the hints-auto-exit feature, put a line like the following in your rc, adjusting the number to suit your preference. 500 was the old default.

hints_auto_exit_delay = 500;
  • Additionally, many people like to also have an auto-exit in the ambiguous case:

hints_ambiguous_auto_exit_delay = 500;
  • Since this is a popular feature, we are also documenting it more prominently with the recently added contrib/config/commmon.js as well as on the wiki.

November 5, 2009

  • youporn-mode removed
  • Youporn-mode doesn't work, but even if it did, it serves no purpose. It uses Conkeror's media-scraper system to find the url of the flv file for an embedded media player. However, youporn.com already provides a hyperlink to download that flv file. Additionally, even if you do want to use the media-scraper system instead of the hyperlink to download the file, Conkeror's built-in media_scrape_default finds the url just fine. In summary and conclusion, there is no reason, in triplicate, for this mode to exist.

November 3, 2009

  • browser_prevent_automatic_form_focus_mode has been renamed and put in its own file. To use this mode, simply do this:

  • The variable browser_automatic_form_focus_window_duration was renamed to block_content_focus_change_duration.

  • the commands follow-current, follow-current-new-buffer, follow-current-new-buffer-background, and follow-current-new-window have been removed. Instead of binding to these commands, you can just do this:

define_key(content_buffer_anchor_keymap, "d", "follow",
           $browser_object = browser_object_focused_element);

October 20, 2009

  • define_buffer_mode, define_input_mode, and define_page_mode no longer take display_name or doc as positional arguments. They are now given as keyword arguments: $display_name and $doc.

October 12, 2009

  • mime_type_external_handlers removed. Replaced by external_content_handlers, which works like this:

external_content_handlers.set("application/pdf", "xpdf");
external_content_handlers.set("image/*", "display");

0.9 and earlier

September 22, 2009

  • define_browser_object_class: removed second argument, label. Replaced with keyword argument, $hint. The text of hint should contain both a verb and a noun, short description of what the user will do with this browser object class. Browser object classes whic do not use the minibuffer do not need to provide $hint, which is the reason for it being a keyword instead of a positional argument.

  • browser object class pasteurl renamed to paste-url

  • some variables renamed:









September 1, 2009

  • Removed M-<arrow> bindings (focus-next-link, focus-previous-link) because the feature request for which they were originally added was based on mistaken information about the Opera UI. The focus-next-link and focus-previous-link commands are still available though, just not on any keys by default until we have a clear reason.

August 30, 2009

  • Removed xulplanet webjump, because that site no longer exists.

August 26, 2009

  • Renamed the commands go-home, go-up, go-back, go-forward, and help-with-tutorial to home, up, back, forward, and tutorial.

  • Renamed wikipedia-mode.js to wikipedia.js for consistency across the page modes. Breaking Change notice from August 12 updated.

  • unfocus command: clear selection now has higher precedence than unfocus element.

August 24, 2009

  • unfocus command was rewritten, and its behavior is a bit different. unfocus does one of the following things, in this order of precedence: 1) unfocus a hyperlink or form field; 2) clear the selection; 3) unfocus a frame, iframe, or plugin.
  • gmail-focus-primary-frame command no longer exists, as the job is now done by other means.

August 12, 2009

  • Wikipedia webjumps are moved from its own module to the new Wikipedia mode. Update your rc file by replacing any occurrence of wikipedia-webjumps.js by page-modes/wikipedia.js. Note that this also enables Wikipedia mode which at the time of writing (August 25 2009) only has one keybinding, C-c C-o.

  • The Wikipedia "Did You Mean" module is also affected by the change described above, so change any occurrence of wikipedia-didyoumean.js by page-modes/wikipedia.js as well. Note that the file wikipedia-didyoumean.js was not removed until August 25.

June 6, 2009

  • noscript.js was moved from contrib to modules/extensions

June 5, 2009

  • The command line switch -uu was renamed to +u. Mozilla consumes -u, which is our first choice for this purpose. +u is a more aesthetic alternative to -uu. As a side-effect, the + character is now a synonym for - with all non-special command-line switches (everything but -q and -E).

  • The key bindings << and >> are now simply < and > to have a more responsive UI.

  • page-mode keymaps are now declared in the define_page_mode form with a new keyword argument, $keymaps. See WritingPageModes for more information about the new style.

  • default_directory and set_default_directory have been removed and replaced by the variable cwd. The value of cwd must be an nsILocalFile object. For practical purposes, this means that setting cwd in your rc will now look something like this:

  • cwd = make_file("/foo/bar/");
  • buffer-local variables are now indexed by buffer.local.foo. page-local variables are indexed by buffer.page.local.foo. Within an interactive command, the top of the locality stack is referred to by I.local.foo.

  • The command send-ret was removed since it is redundant of the module global-overlay-keymap. If you used it, do this instead:

  • require("global-overlay-keymap.js");
    define_key_alias("C-m", "return");
  • Buffer-local cwd is no longer set or inherited automatically. The following code in your rc will bring back the old behavior:
  • /**
     * This bit of code is how auto-cwd and cwd-inheritance can be done.
     * Auto-cwd means that buffers created from a command-line action will
     * get their cwd set to the working directory of the command-line
     * invocation.  Cwd-inheritance means that new buffers will inherit
     * their cwd from the buffer that caused them to be created.  For
     * auto-cwd, buffer.opener will be `instanceof interactive_context'.
     * For cwd-inheritance, buffer.opener will be `instanceof buffer'.
    function cwd_setup (buffer) {
        if (buffer.opener && buffer.opener.local) {
            if (buffer.opener.local.hasOwnProperty('cwd')) {
                buffer.local.cwd = buffer.opener.local.cwd;
    add_hook('create_buffer_hook', cwd_setup);
  • download-cancel is now bound to d instead of C-g, and it asks for confirmation. The d key was chosen based on similar bindings in dired-mode and other modes in Emacs. C-g was cited by users as confusing in this situation, and an additional reason for removing the binding is that it is not forward-compatible with our desire to one day have download buffers that may show more than one download.

April 27, 2009

Reddit-mode no longer automatically goes to the next (or previous) page when the end of the link list is reached. To get the old behavior back, put the following in your rc:

reddit_end_behavior = 'page';

March 20, 2009

In order to make Conkeror compatible with native toolkit theming, Conkeror's themes have undergone a big rewrite.

  • Conkeror no longer specifies its own gui colors.
  • The blackened theme no longer exists.
  • It is no longer possible to theme scrollbars.

From now on, the right way to change Conkeror's gui colors is to do so at the OS level, for example, with a GTK theme.

February 20, 2009

browser_prevent_automatic_form_focus_mode is no longer enabled by default. To use it, put the following in your rc:


February 8, 2009

The alternative url (which is used when no argument is supplied by the user when invoking a webjump) should now be specified explicitly using the $alternative keyword to define_webjump. The previous method of specifying the handler as an array of two strings was peculiar and has been removed.

Please change webjumps like

  •   define_webjump("example", ["http://www.example-search.com/search?term=%s",


  •   define_webjump("example", "http://www.example-search.com/search?term=%s",
                                $alternative = "http://www.example.com/");

January 28, 2009

The command change-current-directory was renamed to change-directory.

January 8, 2009

The -cwd command-line argument (which allowed setting the cwd for new buffers created), and would typically be used via the syntax -cwd $PWD, has been removed.

Instead, the cwd is obtained automatically, so there is no need to specify it explicitly anymore.

January 1, 2009

define_wikipedia_webjumps now names webjumps with the prefix wikipedia- by default. To get the old behavior back, do:

wikipedia_webjumps_format = "%s";

The "ALL" cookie was removed from the call style of define_wikipedia_webjumps. Now, define_wikipedia_webjumps defines all webjumps when called with no args.

December 31, 2008

The alias add_webjump was removed. Please use define_webjump.

The $no_argument keyword to define_webjump was replaced by $argument, and the term "maybe" was replaced by "optional". See WritingWebjumps for more details.

December 23, 2008

String webjumps must now include an url scheme. For example, a webjump to "www.example.com" will no longer work. It has to be "http://www.example.com". This is to properly support auto-generation of the "alternative" webjump when a string webjump is called without an argument.

December 22, 2008

There will be temporary breakage of the describe-bindings command while key categories are re-implemented as command categories.

The call form of define_sticky_modifier has changed. The second argument should now be a string containing just the letters representing the modifiers. For example, the string "CM" would represent Control and Meta.

define_key no longer accepts the keyword $category.

The names of some keys in the call form of define_key have changed. With the exception of "space", all punctuation characters are now given as the characters themselves, rather than the name of the character. Also, characters such as "*" can now be given directly instead of the old form "S-8".

save_uri in save.js now uses the cache by default. This affects the behavior of all of the save commands.

December 18, 2008

xkcd-mode: no longer insert title by default. The variable xkcd_add_title now controls this behavior. To make xkcd-mode add the title text below the comic, put this in your rc:

  • xkcd_add_title = true;

This change was made because it is a reasonable expectation that under default configuration, conkeror should display all web pages as intended by their authors. Since xkcd-mode has an additional feature (follow-next and follow-previous patterns for navigating xkcd) which is non-breaking, it seemed best to keep this page mode as one that loads by default, but to make its content-editing feature one that must be explicitly enabled by the user.

October 27, 2008

Conkeror no longer loads gmail-mode automatically. This default was changed because gmail mode changes so many key bindings that it renders the browser practically unusable without a mouse, for people who do not know all of gmail's special key bindings. To enable gmail-mode in your rc, do the following:

  • require("page-modes/gmail.js");

October 27, 2008

The functions open_in_browser and browser_element_follow were removed. If you use these function in your rc, you can replace all calls to it with calls to browser_object_follow. However, most direct uses of this in the rc are now unnecessary, because interactive commands can now inherit their behavior from existing commands, such as follow.

September 15, 2008

Caret-mode no longer clears the selection when enabled. This was to make it possible to modify an existing selection with caret-mode. The old behavior should be able to be duplicated via caret_mode_enable_hook. If anyone does up such code, please post it here.

September 15, 2008

The copy command now focuses focus-able elements.

September 11-12, 2008

The docstring and handler arguments of the function interactive are now positional. Null may be passed for the docstring. This change affects anyone defining commands in their rc.

September 10, 2008

Conkeror now loads .conkerorrc in the user's home directory as the default rc if the preference conkeror.rcfile is not set. Conkeror can be made to not try to load any rc by setting the preference conkeror.rcfile to the empty string. See Conkeror RC for more details.

August 21, 2008

Changed interactive declaration form, and key binding form, for prefix commands such as universal argument and the browser-object-classes.

August 19, 2008

The auxiliary program spawn-process-helper was renamed to conkeror-spawn-helper so that its name can identify what package it belongs to when installed to a system bin directory.

August 14, 2008

Previously, isearch would always start from the top of the viewport. Now it starts from the location of the caret, when that exists. Typical situations when the caret will have a location are: when you have used caret-mode to place the caret somewhere; when you have made a selection; when you have previously performed an isearch. Note: the caret need not be visible to have a location. To clear to location of the caret, use the unfocus command, which is normally bound to escape. This change in behavior was made to accomodate vi-style non-interactive isearch repeat (the relevant commads are isearch-continue-forward and isearch-continue-backward).

June 3, 2008

The command line switches -e and -f now suppress the default action, meaning that you do not need to give -batch on the command line with either of these switches to prevent a homepage window from opening.

April 12, 2008

tab-bar.js is no longer loaded by default. tab-bar.js now automatically enables tab-bar-mode when loaded. To turn on tab-bar-mode, put this in your rc:

  • require("tab-bar.js");

Conkeror.org: BreakingChanges (last edited 2016-02-05 03:13:53 by scottjad)