1 #+TITLE: org-protocol.el -- Intercept calls from emacsclient to trigger custom actions
2 #+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc ^:{} author:nil
4 #+SETUPFILE: ../macros.setupfile
5 #+STYLE: <script type="text/javascript">
6 #+STYLE: <!--/*--><![CDATA[/*><!--*/
7 #+STYLE: function makeUrl() {
8 #+STYLE: return encodeURIComponent(location.href)+
9 #+STYLE: '/'+encodeURIComponent(document.title)+
10 #+STYLE: '/'+encodeURIComponent(window.getSelection());
12 #+STYLE: function storeLink() {
13 #+STYLE: document.location.href='org-protocol://store-link://'+makeUrl();
15 #+STYLE: function remember() {
16 #+STYLE: document.location.href='org-protocol://remember://'+makeUrl();
18 #+STYLE: function capture() {
19 #+STYLE: document.location.href='org-protocol://capture://'+makeUrl();
24 [[file:index.org][{Back to Worg's contibutions index}]]
26 org-protocol intercepts calls from emacsclient to trigger custom actions without
27 external dependencies. Only one protocol has to be configured with your external
28 applications or the operating system, to trigger an arbitrary number of custom
29 actions. Just register your custom sub-protocol and handler with the variable
30 `org-protocol-protocol-alist'.
33 * About org-protocol.el
35 =org-protocol.el= is based on code and ideas from [[file:./org-annotation-helper.org][org-annotation-helper.el]] and
38 "=org-protocol:/sub-protocol:/=" triggers actions assossiated with =sub-protocol=
39 through the custom variable =org-protocol-protocol-alist=.
41 It comes with four predefined handlers:
42 - =org-protocol-store-link= ::
43 triggered through the sub-protocol "=store-link=". Stores an Org-link and
44 pushes the URL to the =kill-ring=.
45 - =org-protocol-capture= ::
46 Fill a =CAPTURE= buffer with information gathered somewhere else. This
47 handler is triggered through the "=capture=" sub-protocol and uses the
48 function =org-capture=.
49 - =org-protocol-remember= ::
50 Fills a remember buffer with information gathered somewhere else. This
51 handler is triggered through the "=remember=" sub-protocol and still
52 available for backward compatibility. This handler uses =org-remember=. Use
53 the current =org-protocol-capture=.
55 - =org-protocol-open-source= ::
56 "=open-source=". Maps URLs to local filenames. Use this to open sources of
57 already published contents in emacs for editing.
59 =org-protocol= helps creating custom handlers [[file:../org-tutorials/org-protocol-custom-handler.org][(tutorial)]] and so called
60 =org-protocol-projects=.
63 @<b>As of Org mode release 7.01 =org-protocol-remember= is now by =org-protocol-capture=.@</b>
64 If not stated otherwise, you may simply replace each occurrence of
65 /capture/ with /remember/ throughout this document, if you still want to use
66 remember templates. Use =M-x org-version= to find out about the version you're
74 - To load org-protocol.el add the following to your =.emacs=:
77 : (add-to-list 'load-path "~/path/to/org/protocol/")
78 : (require 'org-protocol)
80 * Browser / system setup
82 Windows users proceed to the section [[windows-setup][Windows]].
84 *** Linux Setup (Gnome)
86 For this to work, you'll need the Gnome-Libraries to be installed.
88 : gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/command '/usr/local/bin/emacsclient %s' --type String
89 : gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type Boolean true
95 Windows users may register the "=org-protocol=" once for all by adjusting the
96 following to their facts, save it as *.reg file and double-click it. This
97 worked for me on Windows-XP Professional and the emasc23 from ourcomments.org
98 ([[http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl]]). I'm no Windows user
99 though and enhancements are more than welcome on the org-mode mailinglist. The
100 original file is from http://kb.mozillazine.org/Register_protocol.
105 [HKEY_CLASSES_ROOT\org-protocol]
108 [HKEY_CLASSES_ROOT\org-protocol\shell]
109 [HKEY_CLASSES_ROOT\org-protocol\shell\open]
110 [HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
111 @="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\""
118 Please refer to http://kb.mozillazine.org/Register_protocol and use
119 "org-protocol" as protocol.
124 :CUSTOM_ID: acrobat-reader-setup
127 Adapted from [[http://article.gmane.org/gmane.emacs.orgmode/6810]]
129 You place a javascript file for each menu entry in
130 =~/.adobe/Acrobat/<VERSION>/JavaScripts= on unix-like systems or
131 =c:/Program Files/Adobe/Acrobat <VERSION>/Reader/Javascripts/= on
132 Windows, or wherever your Adobe Reader Installation might look for
135 The examples given here will place new menu entries in the "Tools"
136 menu, after restarting Adobe Reader.
138 # <<acrobat-store-link-js>>
139 ******* org-store-link.js
140 : // from http://article.gmane.org/gmane.emacs.orgmode/6810
141 : app.addMenuItem({cName:"org-store-link", cParent:"Tools",
142 : cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"});
144 # <<acrobat-capture-js>>
145 ******* org-capture.js
146 : // from http://article.gmane.org/gmane.emacs.orgmode/6810
147 : app.addMenuItem({cName:"org-capture", cParent:"Tools",
148 : cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"});
150 And this one, if you still use remember templates:
152 # <<acrobat-remember-js>>
153 ******* org-remember.js
154 : // from http://article.gmane.org/gmane.emacs.orgmode/6810
155 : app.addMenuItem({cName:"org-remember", cParent:"Tools",
156 : cExec:"app.launchURL('org-protocol://remember://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"});
162 Opera setup is described here:
163 http://www.opera.com/support/kb/view/535/.
165 To set up opera for use with org-protocol, follow these steps:
167 1. Choose "/Tools/" -> "/Prefences/" from the menu.
168 2. Select the tab "/Advanced/".
169 3. Choose "/Programs/" from the list on the left.
170 4. Now click the button "/Add/" on the very right.
171 5. In the new dialog window, enter "=org-protocol=" as "/Protocol/", choose the
172 radio button "/Open with other application/" and enter the path to
175 # <<test-org-protocol>>
176 *** Verify the installation
178 After your protocol is registered with your browse/OS, these links here
179 should work. Click on them and see if emacs reacts:
183 <li><a href="javascript:storeLink();">Org store-link</a></li>
184 <li><a href="javascript:capture();">Org capture (select some text if you like)</a></li>
185 <li><a href="javascript:remember();">Org remember (select some text please)</a></li>
190 # <<default-location>>
193 To actually use org-protocol add a bookmark to Firefox or opera.
195 Here is the URL to use as "/Location/" for browser bookmarks. Just remove the
196 line breaks and replace "=sub-protocol=" with the real sub-protocol to use:
198 : javascript:location.href='org-protocol://sub-protocol://'+
199 : encodeURIComponent(location.href)+'/'+
200 : encodeURIComponent(document.title)+'/'+
201 : encodeURIComponent(window.getSelection())
203 This URL may be used for all three standard handlers in =org-protocol.el=. Some
204 of the values will be ignored (e.g. =store-link:/= will use the URL and title
207 # <<org-protocol-store-link>>
208 * Links and bookmarks: =org-protocol-store-link=
210 =org-store-link= stores an Org-link insertable through =M-x org-insert-link= and
211 pushes the URL found onto the =kill-ring= for yanking (=C-y=). The sub-protocol
212 used is "=store-link=":
214 : emacsclient org-protocol:/store-link:/URL/TITLE
216 will store this Org-link:
222 In addition, =URL= will be pushed on the =kill-ring= for yanking ('=C-y='). You will
223 have to encode =URL= and/or =TITLE= if they contain slashes, and probably quote
226 To use this feature, add a bookmark with an arbitrary name (e.g.
227 "/Org: store-link/") and enter this as "=Location=":
229 : javascript:location.href='org-protocol://store-link://'+encodeURIComponent(location.href)
232 # <<org-protocol-capture>>
233 * Note taking and citations: =org-protocol-capture=
235 This one is triggered through the sub-protocol "=capture=" and consumes up to
238 : emacsclient org-protocol:/capture:/URL/TITLE/BODY
240 will pop up an /*Capture*/ buffer and fill the template with the data
243 To use this feature, add a bookmark with an arbitrary name (e.g.
244 "/Org: capture/") and enter this as "=Location=":
246 : javascript:location.href='org-protocol://capture://'+
247 : encodeURIComponent(location.href)+'/'+
248 : encodeURIComponent(document.title)+'/'+
249 : encodeURIComponent(window.getSelection())
251 The result depends on the template used. See [[example-template][An example capture template]]
254 Note, that this one, as opposed to the other two standard handlers, does not
255 mix with more parameters to emacsclient. All parameters but the
256 #'=org-protocol://org-capture://...=' one will be discarded.
258 # <<which-capture-template>>
259 *** Which capture template is used?
261 :ID: org:f56bcb9a-20e7-4b37-99f1-839a8821cc4b
264 You don't need to setup a capture template to use =org-protocol-capture=,
265 since Org-mode provides a default template for those cases. Newer versions
266 provide an interactive interface for choosing a template. You may provide a
267 template to be used by customizing the variable
268 =org-capture-default-template= [fn:1].
270 The problem with this solution would be, that only one template can be used
271 with the fuction. Luckily, =org-protocol-capture= understands a slightly
272 extended syntax to choose between several templates: If the first field of
273 the data submitted is exactly one character in length, this character will
274 be used to select the template.
276 Here we choose to use the "=x=" template:
278 : emacsclient org-protocol:/capture:/x/URL/TITLE/BODY
280 And, again, as bookmark location:
281 : javascript:location.href='org-protocol://capture://x/'+
282 : encodeURIComponent(location.href)+'/'+
283 : encodeURIComponent(document.title)+'/'+
284 : encodeURIComponent(window.getSelection())
286 # <<example-template>>
287 ***** An example capture template
289 #+begin_src emacs-lisp
290 (setq org-capture-templates
295 (file+headline "~/org/capture.org" "Notes")
296 "* %^{Title}\n\n Source: %u, %c\n\n %i"
298 ;; ... more templates here ...
302 - "=w=" :: makes this one the default template used for
303 "=org-protocol://capture://=" URLs.
304 - =entry= :: makes it a regular entry with a headline.
305 - =file+headline= :: files the note in file "=~/org/capture.org=" as child of
306 the headline "=Notes="
307 - '=%c=' :: will be replaced by an Org-link pointing to the location of the
308 page you have been visiting when clicking on the link. The page
309 title will be the links description.
310 - '=%i=' :: will be replaced by the selected text in your browser window if
313 In addition, you may use the following placeholders in your template:
315 | Placeholders | Replacement |
316 |---------------+---------------------------|
317 | =%:link= | URL of the web-page |
318 | =%:description= | The title of the web-page |
319 | =%:initial= | Selected text. |
321 You may read more about templates and their special escape characters in the
322 [[http://orgmode.org/manual/Capture-templates.html#Capture-templates][Org-mode manual]].
325 # <<org-protocol-remember>>
326 *** Org-protocol-remember
328 The =org-protocol-remember= handler is now obsolete. How ever, the handler is
329 still available for backward compatibility. To use this handler, closely
330 follow the setup for the current =org-protocol-capture= handler, and simply
331 replace each occurrence of /capture/ with /remember/.
333 As remember templates look slightly different than capture templates, we
334 provide an example here.
336 # <<example-remember-template>>
337 ***** An example remember template
339 #+begin_src emacs-lisp
340 (setq org-remember-templates
341 '((?w "* %^{Title}\n\n Source: %u, %c\n\n %i" nil "Notes")))
344 - '=?w=' :: makes this one the default template used for
345 "=org-protocol://remember://=" URLs.
346 - '=%c=' :: will be replaced by an Org-link pointing to the location of the
347 page you have been visiting when clicking on the link. The page
348 title will be the links description.
349 - '=%i=' :: will be replaced by the selected text in your browser window if
352 In addition, you may use the following placeholders in your template:
354 | Placeholders | Replacement |
355 |---------------+---------------------------|
356 | =%:link= | URL of the web-page |
357 | =%:description= | The title of the web-page |
358 | =%:initial= | Selected text. |
360 You may read more about templates and their special escape characters in the
361 [[http://orgmode.org/manual/Remember-templates.html#Remember-templates][Org-mode manual]].
364 * Edit published content: =org-protocol-open-source=
366 This one was designed to help with opening sources for editing when browsing
367 in the first place. =org-protocol-open-source= uses the custom variable
368 =org-protocol-project-alist= to map URLs to (local) filenames.
370 Let's take http://orgmode.org/worg/ as our example.
372 Our intention is to click a bookmark (or link) to open the source of the
373 published file we are reading in our favourite editor. The bookmark-URL above
374 could be used again. But since =org-protocol-open-source= regards the first
375 field only, this here will do:
377 : javascript:location.href='org-protocol://open-source://'+encodeURIComponent(location.href)
379 To open files publihed on Worg locally, =org-protocol-project-alist= should look
380 like this (you may skip the second project):
382 #+begin_src emacs-lisp
383 (setq org-protocol-project-alist
385 :base-url "http://orgmode.org/worg/"
386 :working-directory "/home/user/worg/"
387 :online-suffix ".html"
388 :working-suffix ".org")
389 ("My local Org-notes"
390 :base-url "http://localhost/org/"
391 :working-directory "/home/user/org/"
392 :online-suffix ".php"
393 :working-suffix ".org")))
396 If you're now browsing http://orgmode.org/worg/org-tutorials/org-protocol.php
397 and find a typo or have an idea how to enhance the documentation, simply click
398 the bookmark and start editing.
400 There are to functions to help you filling =org-protocol-project-alist= with
401 valid contents. First of which is =org-protocol-create= that guides you through
402 the process. If you're editing an Org-mode file that is part of a publishing
403 project in =org-publish-project-alist=, try
405 : M-x org-protocol-create-for-org RET
407 # <<open-source-rewritten-urls>>
408 *** Handle rewritten URLs
410 In some cases, replacing =:base-url= with =:working-directory= and
411 =:online-suffix= with =:working-suffix= will not yield the desired results.
413 Suppose you maintain an online store located at =http://example.com/=. The
414 local sources reside in =/home/user/example/=. While most of the URLs map
415 directly to local file names by stripping URL parameters from the end and
416 replacing the =:base-url= with =:working-diretory= and =:online-suffix= with
417 =working-suffix=, this might not work for rewritten URLs. It's common
418 practice, to serve all products in such a store through one file and rewrite
419 URLs, that do not match an existing file on the server.
421 That way, a request to =http://example.com/print/posters-A4.html= might be
422 rewritten on the server to something like
423 =http://example.com/shop/products.php/posters-A4.html.php=, where
424 =/posters-A4-digital.html.php= is the so called path info. Note, that the
425 browser will not notice the rewrite.
427 If you now click your =org-protocol://open-source://= bookmark, the handler
428 will probably not find a file named
429 =/home/user/example/print/posters-A4.html.php= and fail.
431 Or, even more simple, assume your browsing to =http://example.com/=. A file
432 named =/home/user/example/.php= is not likely to exist.
434 Since Org-mode commit =69b46e10aab3b2374ecbc1a963ba56e77102a9a4= from 15nth
435 Nov. 2009, such an entry in =org-protocol-project-alist= may hold an
436 additional property =:rewrites=. This property is a list of cons cells, each
437 of which maps a regular expression to a path, relative to the
438 =:working-directory=.
440 Now map the URL to the path =/home/user/example/products.php= by adding the
441 =:rewrites= property like this:
443 #+begin_src emacs-lisp
444 (setq org-protocol-project-alist
446 :base-url "http://example.com/"
447 :working-directory "/home/user/example/"
448 :online-suffix ".php"
449 :working-suffix ".php"
450 :rewrites (("example.com/print/" . "products.php")
451 ("example.com/$" . "index.php"))
455 Guess what the second =:rewrites= element does. Since =example.com/$= is used as
456 a regular expression, it maps =http://example.com/=, =https://example.com=,
457 =http://www.example.com/= and similar to =/home/user/example/index.php=.
459 The =:rewrites= are searched as a last resort if, and only if no existing file
466 Setting up org-protocol in [[http://conkeror.org/][Conkeror]] (an emacs inspired Mozilla web
467 browser) requires a slightly different method. You may simply add the
468 following snippets of code to your .conkerorrc file.[fn:tassilosblog]
470 For org-store-link, add the following to .conkerorrc:
472 : function org_store_link (url, title, window) {
473 : var cmd_str = 'emacsclient \"org-protocol://store-link://'+url+'/'+title+'\"';
474 : if (window != null) {
475 : window.minibuffer.message('Issuing ' + cmd_str);
477 : shell_command_blind(cmd_str);
480 : interactive("org-store-link", "Stores [[url][title]] as org link and copies url to emacs kill ring",
482 : org_store_link(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), I.window);
485 For org-capture (or org-remember --- just exchange /capture/ with /remember/), use
488 : function org_capture (url, title, selection, window) {
489 : var cmd_str = 'emacsclient \"org-protocol://capture://'+url+'/'+title+'/'+selection+'\"';
490 : if (window != null) {
491 : window.minibuffer.message('Issuing ' + cmd_str);
493 : shell_command_blind(cmd_str);
496 : interactive("org-capture", "Clip url, title, and selection to capture via org-protocol",
498 : org_capture(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), encodeURIComponent(I.buffer.top_frame.getSelection()), I.window);
501 Now, you should be able to invoke the commands from within conkeror
502 with =M-x org-store-link= and =M-x org-capture= (or remember).
504 Or, if you'd like your familiar emacs keybindings, you can add the
505 following to your .conkerorrc:
507 : define_key(content_buffer_normal_keymap, "C-c r", "org-capture");
508 : define_key(content_buffer_normal_keymap, "C-c l", "org-store-link");
510 [fn:tassilosblog] Adapted from Tassilo Horn's blog, "Calling
511 org-remember from inside conkeror," November 14, 2008.
512 http://tsdh.wordpress.com/2008/11/14/calling-org-remember-from-inside-conkeror/
519 Uzbl is a minimalistic webkit browser for Unix/Linux.
521 - [[http://www.uzbl.org/]]
523 You can pass encoded url data from uzbl to org-protocol by adding the
524 following lines to =.config/uzbl/config=.
530 @cbind \\r = sh 'emacsclient "org-protocol://capture://\@<encodeURIComponent(window.location.href)>\@/\@<encodeURIComponent(document.title)>\@/\@<document.getSelection()>\@"'
531 @cbind \\l = sh 'emacsclient "org-protocol://capture://\@<encodeURIComponent(window.location.href)>\@/\@<encodeURIComponent(document.title)>\@"'
535 These bind org-protocol-capture and org-store-line to "\r" and "\l" respectively.
537 # <<firefox-keybindings>>
538 * Keybindings for Firefox
540 You can add key bindings for the =org-protocol= commands using the keyconfig
543 First, install keyconfig from http://mozilla.dorando.at/keyconfig.xpi.
545 Open the keyconfig dialog by going to Tools and then Keyconfig.
547 Click the 'Add a new Key' button. Enter "Org store link" as the name.
548 Enter the following in the box with /* CODE */ in it:
550 : var orgProtoString = 'org-protocol://store-link://'+
551 : encodeURIComponent(gBrowser.currentURI.spec) + '/' +
552 : encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
553 : encodeURIComponent(gBrowser.contentWindow.getSelection());
555 : gBrowser.loadURI(orgProtoString);
557 Click OK. You will then need to bind a key by clicking in the box next to the
558 'Apply' button and pressing whatever key combination you want. Click 'Apply' to
559 store the keybinding.
561 Repeat the steps, but call the next key "Org capture" and use the code below:
563 : var orgProtoString = 'org-protocol://capture://'+
564 : encodeURIComponent(gBrowser.currentURI.spec) + '/' +
565 : encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
566 : encodeURIComponent(window.getSelection());
568 : gBrowser.loadURI(orgProtoString);
570 Click Close, then OK, and then restart Firefox. You should then be able to
571 access the org-protocol functions with your chosen keys.
573 # <<screencast-intro>>
574 * Screencast: small introduction to org-protocol.el
577 <object width="640" height="464"><param name="allowfullscreen"
578 value="true" /><param name="allowscriptaccess" value="always" /><param
580 value="http://vimeo.com/moogaloop.swf?clip_id=5662410&server=vimeo.com&show_title=1&show_byline=1&show_portrait=1&color=FF7700&fullscreen=1"
582 src="http://vimeo.com/moogaloop.swf?clip_id=5662410&server=vimeo.com&show_title=1&show_byline=1&show_portrait=1&color=FF7700&fullscreen=1"
583 type="application/x-shockwave-flash" allowfullscreen="true"
584 allowscriptaccess="always" width="640" height="464"></embed></object>
587 This screencast shows off some nice things you can do with Firefox,
588 Emacs, Org-mode and org-protocol.el.
590 It first shows how to create two bookmarklets, =org-capture= and
591 =org-store-link=. These bookmarklets enable your Firefox to talk to
592 emacsclient via a new protocol (=org-protocol://=); emacsclient then
593 parses the request and tells Emacs to capture or store stuff at the
594 relevant places in your Org files.
596 At the end of the screencast, we create two ubiquity commands from these
597 bookmarklets. Now in Firefox =ALT-SPC org-capture RET= creates a note
603 [fn:1] Before commit =fc49c1ec96b2c789f573ae1ba936b930a8494402=, 3rd Sept. 2010,
604 if a template with the key string "=w=" was defined, this one was choosen by
605 default. This was done to make bookmarks used for [[file:./org-annotation-helper.el][org-annotation-helper]] work
606 without changing the template.