org-protocol.el – Intercept calls from emacsclient to trigger custom actions

Most common desktop environments (Gnome, KDE et al) comply with the XDG Desktop Entry Specification. This means setting up emacsclient as the org-protocol handler using a .desktop file can be regarded as a, in most cases, standard way to set this up in most common desktop environments.

Some environments, e.g. Gnome as of Gnome 3, have deprecated other configuration methods, e.g. gconftool-2 to set-up protocol handling.

Create an org-protocol.desktop file either in ~/.local/share/applications/ to set-up emacsclient as the org-protocol handler for the current user or in /usr/share/applications to set-up a system-wide configuration:

[Desktop Entry]
Name=org-protocol
Comment=Intercept calls from emacsclient to trigger custom actions
Categories=Other;
Keywords=org-protocol;
Icon=emacs
Type=Application
Exec=emacsclient -- %u
Terminal=false
StartupWMClass=Emacs
MimeType=x-scheme-handler/org-protocol;

Update the cache database of MIME types handled by desktop files via:

update-desktop-database ~/.local/share/applications/

Windows users may register the "org-protocol" once for all by adjusting the following to their facts, save it as *.reg file and double-click it. This worked for me on Windows-XP Professional and the emasc23 from ourcomments.org (http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl). I'm no Windows user though and enhancements are more than welcome on the org-mode mailinglist. The original file is from http://kb.mozillazine.org/Register_protocol.

REGEDIT4

[HKEY_CLASSES_ROOT\org-protocol]
@="URL:Org Protocol"
"URL Protocol"=""
[HKEY_CLASSES_ROOT\org-protocol\shell]
[HKEY_CLASSES_ROOT\org-protocol\shell\open]
[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
@="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\""

Follow the directions for installing EmacsClient.app from https://github.com/neil-smithline-elisp/EmacsClient.app. This should configure the org-protocol for all Mac OS X browsers.

After installing EmacsClient.app you should then Verify the installation. Once verified, you can begin Using org-protocol.

If that doesn't work, you might check https://github.com/xuchunyang/setup-org-protocol-on-mac for building a custom handler, combined with the per-browser config information below.

After your protocol is registered with your browser/OS, these links here should work. Click on them and see if emacs reacts:

• Org store-link
• Org capture (select some text if you like)
• Org remember (select some text please)

You don't need to setup a capture template to use org-protocol-capture, since Org-mode provides a default template for those cases. Newer versions provide an interactive interface for choosing a template. You may provide a template to be used by customizing the variable org-capture-default-template ¹.

The problem with this solution would be, that only one template can be used with the fuction. Luckily, org-protocol-capture understands a slightly extended syntax to choose between several templates: If the first field of the data submitted is exactly one character in length, this character will be used to select the template.

Here we choose to use the "x" template:

emacsclient org-protocol:/capture:/x/URL/TITLE/BODY

And, again, as bookmark location:

javascript:location.href='org-protocol://capture://x/'+
      encodeURIComponent(location.href)+'/'+
      encodeURIComponent(document.title)+'/'+
      encodeURIComponent(window.getSelection())

The org-protocol-remember handler is now obsolete. However, the handler is still available for backward compatibility. To use this handler, closely follow the setup for the current org-protocol-capture handler, and simply replace each occurrence of capture with remember.

As remember templates look slightly different than capture templates, we provide an example here.

In some cases, replacing :base-url with :working-directory and :online-suffix with :working-suffix will not yield the desired results.

Suppose you maintain an online store located at http://example.com/. The local sources reside in /home/user/example/. While most of the URLs map directly to local file names by stripping URL parameters from the end and replacing the :base-url with :working-diretory and :online-suffix with :working-suffix, this might not work for rewritten URLs. It's common practice to serve all products in such a store through one file and rewrite URLs that do not match an existing file on the server.

That way, a request to http://example.com/print/posters-A4.html might be rewritten on the server to something like http://example.com/shop/products.php/posters-A4.html.php, where /posters-A4-digital.html.php is the so called path info. Note that the browser will not notice the rewrite.

If you now click your org-protocol://open-source:// bookmark, the handler will probably not find a file named /home/user/example/print/posters-A4.html.php and fail.

Or, even more simple, assume you're browsing http://example.com/. A file named /home/user/example/.php is not likely to exist.

Since Org-mode commit 69b46e10aab3b2374ecbc1a963ba56e77102a9a4 from 15th Nov. 2009, such an entry in org-protocol-project-alist may hold an additional property :rewrites. This property is a list of cons cells, each of which maps a regular expression to a path relative to the :working-directory.

Now map the URL to the path /home/user/example/products.php by adding the :rewrites property like this:

(setq org-protocol-project-alist
      '(("example.com"
         :base-url "http://example.com/"
         :working-directory "/home/user/example/"
         :online-suffix ".php"
         :working-suffix ".php"
         :rewrites (("example.com/print/" . "products.php")
                    ("example.com/$" . "index.php"))
         )))

Guess what the second :rewrites element does. Since example.com/$ is used as a regular expression, it maps http://example.com/, https://example.com, http://www.example.com/ and similar to /home/user/example/index.php.

The :rewrites are searched as a last resort if and only if no existing file name is matched.

Setting up org-protocol in Conkeror (an emacs inspired Mozilla web browser) requires a slightly different method. You may simply add the following snippets of code to your .conkerorrc file².

For org-store-link, add the following to .conkerorrc:

function org_store_link (url, title, window) {
    var cmd_str = 'emacsclient \"org-protocol://store-link://'+url+'/'+title+'\"';
    if (window != null) {
	window.minibuffer.message('Issuing ' + cmd_str);
    }
    shell_command_blind(cmd_str);
}

interactive("org-store-link", "Stores [[url][title]] as org link and copies url to emacs kill ring",
	    function (I) {
		org_store_link(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), I.window);
	    });

For org-capture (or org-remember — just exchange capture with remember), use the following:

function org_capture (url, title, selection, window) {
    var cmd_str = 'emacsclient \"org-protocol://capture://'+url+'/'+title+'/'+selection+'\"';
    if (window != null) {
	window.minibuffer.message('Issuing ' + cmd_str);
    }
    shell_command_blind(cmd_str);
}

interactive("org-capture", "Clip url, title, and selection to capture via org-protocol",
	    function (I) {
		org_capture(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), encodeURIComponent(I.buffer.top_frame.getSelection()), I.window);
	    });

Now, you should be able to invoke the commands from within conkeror with M-x org-store-link and M-x org-capture (or remember).

Or, if you'd like your familiar emacs keybindings, you can add the following to your .conkerorrc:

define_key(content_buffer_normal_keymap, "C-c r", "org-capture");
define_key(content_buffer_normal_keymap, "C-c l", "org-store-link");

Uzbl is a minimalistic webkit browser for Unix/Linux.

• http://www.uzbl.org/

You can pass encoded url data from uzbl to org-protocol by adding the following lines to .config/uzbl/config.

# Org-protocol

@cbind 	\\r = sh 'emacsclient "org-protocol://capture://\@<encodeURIComponent(window.location.href)>\@/\@<encodeURIComponent(document.title)>\@/\@<document.getSelection()>\@"'
@cbind 	\\l = sh 'emacsclient "org-protocol://capture://\@<encodeURIComponent(window.location.href)>\@/\@<encodeURIComponent(document.title)>\@"'

These bind org-protocol-capture and org-store-line to "\r" and "\l" respectively.