#pragma section-numbers on
<<TableOfContents(3)>>

The content handlers system is used to configure Conkeror's behavior for content types which are not supported internally by Mozilla.  Note that before Conkeror gets a chance to handle a given document with these content handlers, Mozilla first looks for plugins such as Acrobat, Flash, Java, et cetera.  Plugins can be disabled in the Plugins tab of the Extensions window (`M-x extensions`).

For versions of Conkeror older than October 12, 2009, see [[MimeTypeHandlers]] instead.


= content_handlers =

When you browse to a document of a content-type that Mozilla cannot view internally, Conkeror normally prompts you for an action to take on the content.  You can customize this on a per-mime-type basis to automatically do what you like by registering a content handler:

{{{
content_handlers.set("application/pdf", content_handler_open);
}}}

`content_handlers` is a mime-type table associating mime-types and mime-type patterns with content handler functions. The following handlers are predefined for your convenience:

 content_handler_save::
 :: Save the document, prompting for path.
 content_handler_open::
 :: Open the document, promting for a command.
 content_handler_open_default_viewer::
 :: Open the document in the viewer registered in `external_content_handlers` for this mime-type, or prompt if none.
 content_handler_open_url::
 :: Prompt for a command, and run it with the URL of the document as its argument.
 content_handler_copy_url::
 :: Copy the URL of the document.
 content_handler_view_internally::
 content_handler_view_as_text::
 content_handler_prompt::
 :: The default prompt---the same as if no handler was defined.

If you set a give `null` instead of a content handler to `content_handlers.set`, it will unset the handler for the given mime type.

You can also use the mime-type wildcard "*".  A mime-type of "*" will match any mime-type.  A mime-type of, for example, "application/*" will match any mime type whose major type is "application".


= external_content_handlers =

This variable is a mime-type table that associates mime types with command names of viewer programs.  Manipulation of the table works just as for `content_handlers`.

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

The default table is:
{{{
{
    "*": getenv("EDITOR"),
    text: { "*": getenv("EDITOR") },
    image: { "*": "feh" },
    video: { "*": "mplayer" },
    audio: { "*": "mplayer" },
    application: {
        pdf: "evince",
        postscript: "evince",
        "x-dvi": "evince"
    }
}
}}}

If you want to discard the defaults and set the entire table in one go, you can do that as follows:
{{{
external_content_handlers =
    {
        "*": "gvim",
        text: { "*": "kate" },
        image: { "*": "display" },
        application: {
            pdf: "xpdf",
            postscript: "gv",
            "x-dvi": "xdvi"
        }
    };
}}}

That trick works for `content_handlers` too.


== Temporary Files and Forking ==

As a measure of basic garbage collecting, by default, Conkeror deletes temporary files as soon as the handler program completes.  This can cause problems if the handler program forks immediately because it dispatches to another program.  Examples include urxvtc, emacsclient with the `-n` flag, or the OS X's `open` command without the `-W` flag.

If you are using urxvtc, or a similar program, just use the non-client version (urxvt) instead.  If you are using emacsclient, don't pass the `-n` flag. If you are using OS X's `open` command, make sure to pass the `-W` flag.

Another option is to write a wrapper script that runs your forking handler, but does not exit until the viewer or editor is done viewing or editing.

As a last result, you can disable the early deletion of temporary files altogether by setting `delete_temporary_files_for_command = false;`.