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

For this to work, you'll need the Gnome-Libraries to be installed.

gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/command '/usr/local/bin/emacsclient %s' --type String
gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type Boolean true

Add a file org.protocol to ~/.kde/share/kde4/services/:

# -*- conf -*-
[Protocol]
protocol=org-protocol
exec=/usr/bin/emacsclient '%u'
input=none
output=none
helper=true
listing=
reading=false
writing=false
makedir=false
deleting=false
Icon=emacs
Description=A protocol for org-mode

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.

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.