1. Overview

Conkeror has several default external handlers for MIME types. These are defined in the variable mime_type_external_handlers. (See UserVariables for more information.) Several functions exist to manipulate this data structure, allowing you to change the default handlers and to add new MIME types to be handled.

2. API

2.1. define_mime_type_external_handler(mime_type, handler, before)

This function creates or updates a handler for the specified MIME type. For example, the current default handler for the application/pdf MIME type is evince. To change the handler to xpdf, add the following to your RC:

define_mime_type_external_handler("application/pdf", "xpdf");

The current default handler for the video/* MIME type glob is mplayer. To change the handler to xine, add the following to your RC:

define_mime_type_external_handler("video/*", "xine");

A catch-all MIME type glob of * may be added which will handle all MIME types which do not have an explicit handler.

define_mime_type_external_handler("*", "emacs");

The before parameter is optional, but must be a MIME type. When present, the handler for mime_type will be added to the mime_type_external_handlers list just before the type denoted by before. Because the first matching MIME type in the handler list is selected to handle a type, before is useful for ensuring that special cases take precedent over globbed MIME types.

For example, the MIME type glob video/* matches all video MIME types, and is set to mplayer by default. To use a different player, say vlc, for a particular video type, say video/ogg-theora, add the following to your RC:

define_mime_type_external_handler("video/ogg-theora", "vlc", "video/*");

This ensures that the handler for video/ogg-theora appears in the handler list before the handler for video/*, so that theora files will be opened with vlc while all other video files will be opened with mplayer.

This behavior is actually automatic if before is omitted. When you add a handler for a type of the form foo/bar, if a handler for a type of the form foo/* exists in the handler list, then foo/bar will automatically be added before it.

If you omit before when adding a catch-all handler of the form *, then it will be added as the last element of the handler list.

Otherwise, if a new MIME type is defined and before is omitted, it will be added to the end of the list (but before the catch-all *, if it exists).

If a handler is defined for an existing MIME type and before is omitted, then the MIME type will retain its current position in the list, and its handler will be updated.

If a handler is defined for an existing MIME type and before is specified, then the MIME type will be relocated in the list according to before, unless the type denoted by before is not in the list, in which case the type will be added to the end of the list (but before the catch-all *, if it exists).

2.2. get_mime_type_external_handler(mime_type) => handler

Returns the handler for mime_type, or undefined if no handler exists.

2.3. remove_mime_type_external_handler(mime_type) => handler

Removes the handler for mime_type from the list and returns it, or undefined if no handler exists.

3. Other Considerations

3.1. Viewing the handler list

As the handler list is order-dependent, you may need to view it to be able to provide the correct before argument. You can dump the handler list to the console with the following command:

M-: dump(dump_obj(mime_type_external_handlers));

3.2. Passing MIME types as regexps

The mime_type and before arguments for all three functions may be regexps. But be careful. The regexp's source property is used to manage the types and handlers in the list, so to get or remove a MIME type handler you have added as a regexp, you must pass in a regexp instance created from the exact same source code as the one used to define it.

Know that under the hood, when you define a string MIME type such as video/theora, it is converted to the regexp /^video\/theora$ and added to the handler list. Globs such as video/* are converted to the regexp /^video\/.*$. Thus the following will work:

define_mime_type_external_handler("video/ogg-theora", "vlc");
remove_mime_type_external_handler(/^video\/ogg-theora$/);

...as will...

define_mime_type_external_handler(/^video\/ogg-theora$/, "vlc");
remove_mime_type_external_handler("video/ogg-theora");

...as well as...

define_mime_type_external_handler(/^video\/ogg-theora$/, "vlc", /^video\/.*$/);
remove_mime_type_external_handler("video/ogg-theora");

The following yields the same result:

get_mime_type_external_handler("video/ogg-theora");
get_mime_type_external_handler(/^video\/ogg-theora$/);

Use of regexps allows you to match MIME types in creative ways, but generally, you shouldn't need to use regexps, so don't unless you have a good reason.

3.3. TODO

• Mechanism to automatically perform actions for particular MIME types rather than prompting for an action. E.g., always 'o'pen .pdf or .txt files; always 's'ave .doc files. This functionality may already exist; must investigate and document it if it does; else implement and document it.