#pragma section-numbers on

<<TableOfContents(2)>>

{{{#!wiki caution
This API is obsolete as of October 12, 2009.  The documentation will remain available for a reasonable period of time, until the versions of Conkeror packages for the major OSes have caught up.  See [[ContentHandlers]] for details about the system that replaced `mime_type_external_handlers`.
}}}

= 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.

= API =

== 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).

== get_mime_type_external_handler(mime_type) => handler ==

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

== 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.

= Other Considerations =

== 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));
}}}

== 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.

== 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.