org-contrib/org-protocol.org

   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
   3 #+STARTUP: odd
   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());
  11 #+STYLE:   }
  12 #+STYLE:   function storeLink() {
  13 #+STYLE:     document.location.href='org-protocol://store-link://'+makeUrl();
  14 #+STYLE:   }
  15 #+STYLE:   function remember() {
  16 #+STYLE:     document.location.href='org-protocol://remember://'+makeUrl();
  17 #+STYLE:   }
  18 #+STYLE:   function capture() {
  19 #+STYLE:     document.location.href='org-protocol://capture://'+makeUrl();
  20 #+STYLE:   }
  21 #+STYLE:   /*]]>*///-->
  22 #+STYLE:   </script>
  23
  24 [[file:index.org][{Back to Worg's contibutions index}]]
  25
  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'.
  31
  32 # <<about>>
  33 * About org-protocol.el
  34
  35   =org-protocol.el= is based on code and ideas from [[file:./org-annotation-helper.org][org-annotation-helper.el]] and
  36   =org-browser-url.el=.
  37
  38   "=org-protocol:/sub-protocol:/=" triggers actions associated with =sub-protocol=
  39   through the custom variable =org-protocol-protocol-alist=.
  40
  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=.
  54
  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.
  58
  59   =org-protocol= helps creating custom handlers [[file:../org-tutorials/org-protocol-custom-handler.org][(tutorial)]] and so called
  60   =org-protocol-projects=.
  61
  62   {{{BeginInfoBox}}}
  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
  67   using.
  68   {{{EndInfoBox}}}
  69
  70
  71 # <<installation>>
  72 * Installation
  73
  74   - To load org-protocol.el add the following to your =.emacs=:
  75
  76     : (server-start)
  77     : (add-to-list 'load-path "~/path/to/org/protocol/")
  78     : (require 'org-protocol)
  79
  80 * Browser / system setup
  81
  82   - [[Linux setup (Gnome)]]
  83   - [[Linux setup (KDE)]]
  84   - [[Windows setup]]
  85   - [[Mac OS X setup]]
  86
  87 *** Linux setup (Gnome)
  88
  89     For this to work, you'll need the Gnome-Libraries to be installed.
  90
  91     : gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/command '/usr/local/bin/emacsclient %s' --type String
  92     : gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type Boolean true
  93
  94 *** Linux setup (KDE)
  95
  96   Add a file =org.protocol= to =~/.kde/share/kde4/services/=:
  97
  98 #+begin_example
  99 # -*- conf -*-
 100 [Protocol]
 101 protocol=org-protocol
 102 exec=/usr/bin/emacsclient '%u'
 103 input=none
 104 output=none
 105 helper=true
 106 listing=
 107 reading=false
 108 writing=false
 109 makedir=false
 110 deleting=false
 111 Icon=emacs
 112 Description=A protocol for org-mode
 113 #+end_example
 114
 115 # <<windows-setup>>
 116 *** Windows setup
 117
 118   Windows users may register the "=org-protocol=" once for all by adjusting the
 119   following to their facts, save it as *.reg file and double-click it. This
 120   worked for me on Windows-XP Professional and the emasc23 from ourcomments.org
 121   ([[http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl]]). I'm no Windows user
 122   though and enhancements are more than welcome on the org-mode mailinglist. The
 123   original file is from http://kb.mozillazine.org/Register_protocol.
 124
 125 #+begin_example
 126 REGEDIT4
 127
 128 [HKEY_CLASSES_ROOT\org-protocol]
 129 @="URL:Org Protocol"
 130 "URL Protocol"=""
 131 [HKEY_CLASSES_ROOT\org-protocol\shell]
 132 [HKEY_CLASSES_ROOT\org-protocol\shell\open]
 133 [HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
 134 @="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\""
 135 #+end_example
 136
 137 *** Mac OS X setup
 138
 139 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.
 140
 141 After installing EmacsClient.app you should then [[Verify the installation]]. Once verified, you can begin [[Using org-protocol]].
 142
 143 *** Applications
 144 # <<firefox-setup>>
 145 ***** Firefox
 146       If you are using Firefox on Mac OS X, see [[Mac OS X setup]].
 147
 148
 149       Please refer to http://kb.mozillazine.org/Register_protocol and use
 150       "org-protocol" as protocol.
 151
 152 # <<acrobat-setup>>
 153 ***** Acrobat Reader
 154     :PROPERTIES:
 155     :CUSTOM_ID: acrobat-reader-setup
 156     :END:
 157
 158     Adapted from [[http://article.gmane.org/gmane.emacs.orgmode/6810]]
 159
 160     You place a javascript file for each menu entry in
 161     =~/.adobe/Acrobat/<VERSION>/JavaScripts= on unix-like systems or
 162     =c:/Program Files/Adobe/Acrobat <VERSION>/Reader/Javascripts/= on
 163     Windows, or wherever your Adobe Reader Installation might look for
 164     javascript.
 165
 166     The examples given here will place new menu entries in the "Tools"
 167     menu, after restarting Adobe Reader.
 168
 169 # <<acrobat-store-link-js>>
 170 ******* org-store-link.js
 171 : // from http://article.gmane.org/gmane.emacs.orgmode/6810
 172 : app.addMenuItem({cName:"org-store-link", cParent:"Tools",
 173 :    cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"});
 174
 175 # <<acrobat-capture-js>>
 176 ******* org-capture.js
 177 : // from http://article.gmane.org/gmane.emacs.orgmode/6810
 178 : app.addMenuItem({cName:"org-capture", cParent:"Tools",
 179 :    cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"});
 180
 181     And this one, if you still use remember templates:
 182
 183 # <<acrobat-remember-js>>
 184 ******* org-remember.js
 185 : // from http://article.gmane.org/gmane.emacs.orgmode/6810
 186 : app.addMenuItem({cName:"org-remember", cParent:"Tools",
 187 :    cExec:"app.launchURL('org-protocol://remember://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"});
 188
 189
 190 # <<opera-setup>>
 191 ***** Opera
 192
 193   If you are using Opera on Mac OS X, see [[Mac OS X setup]].
 194
 195   Opera setup is described here:
 196   http://www.opera.com/support/kb/view/535/.
 197
 198   To set up opera for use with org-protocol, follow these steps:
 199
 200   1. Choose "/Tools/" -> "/Prefences/" from the menu.
 201   2. Select the tab "/Advanced/".
 202   3. Choose "/Programs/" from the list on the left.
 203   4. Now click the button "/Add/" on the very right.
 204   5. In the new dialog window, enter "=org-protocol=" as "/Protocol/", choose the
 205      radio button "/Open with other application/" and enter the path to
 206      emacsclient.
 207
 208 # <<test-org-protocol>>
 209
 210 ***** Safari
 211       Safari is only supported on Mac systems, not iOS systems.
 212
 213       See [[Mac OS X setup]] for directions.
 214
 215
 216 *** Verify the installation
 217
 218     After your protocol is registered with your browser/OS, these links here
 219     should work. Click on them and see if emacs reacts:
 220
 221 #+begin_html
 222  <ul>
 223   <li><a href="javascript:storeLink();">Org store-link</a></li>
 224   <li><a href="javascript:capture();">Org capture (select some text if you like)</a></li>
 225   <li><a href="javascript:remember();">Org remember (select some text please)</a></li>
 226  </ul>
 227 #+end_html
 228
 229
 230 # <<default-location>>
 231 * Using org-protocol
 232
 233   To actually use org-protocol add a bookmark to Firefox or Opera.
 234
 235   Here is the URL to use as "/Location/" for browser bookmarks. Just remove the
 236   line breaks and replace "=sub-protocol=" with the real sub-protocol to use:
 237
 238   : javascript:location.href='org-protocol://sub-protocol://'+
 239   :       encodeURIComponent(location.href)+'/'+
 240   :       encodeURIComponent(document.title)+'/'+
 241   :       encodeURIComponent(window.getSelection())
 242
 243   This URL may be used for all three standard handlers in =org-protocol.el=. Some
 244   of the values will be ignored (e.g. =store-link:/= will use the URL and title
 245   only).
 246
 247 # <<org-protocol-store-link>>
 248 * Links and bookmarks: =org-protocol-store-link=
 249
 250   =org-store-link= stores an Org-link insertable through =M-x org-insert-link= and
 251   pushes the URL found onto the =kill-ring= for yanking (=C-y=). The sub-protocol
 252   used is "=store-link=":
 253
 254   : emacsclient org-protocol:/store-link:/URL/TITLE
 255
 256   will store this Org-link:
 257
 258 #+begin_example
 259 [[URL][TITLE]]
 260 #+end_example
 261
 262   In addition, =URL= will be pushed on the =kill-ring= for yanking ('=C-y='). You will
 263   have to encode =URL= and/or =TITLE= if they contain slashes, and probably quote
 264   those for the shell.
 265
 266   To use this feature, add a bookmark with an arbitrary name (e.g.
 267   "/Org: store-link/") and enter this as "=Location=":
 268
 269   : javascript:location.href='org-protocol://store-link://'+encodeURIComponent(location.href)
 270
 271
 272 # <<org-protocol-capture>>
 273 * Note taking and citations: =org-protocol-capture=
 274
 275   This one is triggered through the sub-protocol "=capture=" and consumes up to
 276   three data fields:
 277
 278   : emacsclient org-protocol:/capture:/URL/TITLE/BODY
 279
 280   will pop up an /*Capture*/ buffer and fill the template with the data
 281   submitted.
 282
 283   To use this feature, add a bookmark with an arbitrary name (e.g.
 284   "/Org: capture/") and enter this as "=Location=":
 285
 286   : javascript:location.href='org-protocol://capture://'+
 287   :       encodeURIComponent(location.href)+'/'+
 288   :       encodeURIComponent(document.title)+'/'+
 289   :       encodeURIComponent(window.getSelection())
 290
 291   The result depends on the template used. See [[example-template][An example capture template]]
 292   further down.
 293
 294   Note, that this one, as opposed to the other two standard handlers, does not
 295   mix with more parameters to emacsclient. All parameters but the
 296   #'=org-protocol://org-capture://...=' one will be discarded.
 297
 298 # <<which-capture-template>>
 299 *** Which capture template is used?
 300     :PROPERTIES:
 301     :ID:       org:f56bcb9a-20e7-4b37-99f1-839a8821cc4b
 302     :END:
 303
 304     You don't need to setup a capture template to use =org-protocol-capture=,
 305     since Org-mode provides a default template for those cases.  Newer versions
 306     provide an interactive interface for choosing a template.  You may provide a
 307     template to be used by customizing the variable
 308     =org-capture-default-template= [fn:1].
 309
 310     The problem with this solution would be, that only one template can be used
 311     with the fuction. Luckily, =org-protocol-capture= understands a slightly
 312     extended syntax to choose between several templates: If the first field of
 313     the data submitted is exactly one character in length, this character will
 314     be used to select the template.
 315
 316     Here we choose to use the "=x=" template:
 317
 318     : emacsclient org-protocol:/capture:/x/URL/TITLE/BODY
 319
 320     And, again, as bookmark location:
 321     : javascript:location.href='org-protocol://capture://x/'+
 322     :       encodeURIComponent(location.href)+'/'+
 323     :       encodeURIComponent(document.title)+'/'+
 324     :       encodeURIComponent(window.getSelection())
 325
 326 # <<example-template>>
 327 ***** An example capture template
 328
 329 #+begin_src emacs-lisp
 330   (setq org-capture-templates
 331         (quote
 332          (("w"
 333            "Default template"
 334            entry
 335            (file+headline "~/org/capture.org" "Notes")
 336            "* %^{Title}\n\n  Source: %u, %c\n\n  %i"
 337            :empty-lines 1)
 338           ;; ... more templates here ...
 339           )))
 340 #+end_src
 341
 342     - "=w=" :: makes this one the default template used for
 343              "=org-protocol://capture://=" URLs.
 344     - =entry= :: makes it a regular entry with a headline.
 345     - =file+headline= :: files the note in file "=~/org/capture.org=" as child of
 346              the headline "=Notes="
 347     - '=%c=' :: will be replaced by an Org-link pointing to the location of the
 348              page you have been visiting when clicking on the link. The page
 349              title will be the link's description.
 350     - '=%i=' :: will be replaced by the selected text in your browser window if
 351               any.
 352
 353     In addition, you may use the following placeholders in your template:
 354
 355     | Placeholders  | Replacement               |
 356     |---------------+---------------------------|
 357     | =%:link=        | URL of the web-page       |
 358     | =%:description= | The title of the web-page |
 359     | =%:initial=     | Selected text.            |
 360
 361     You may read more about templates and their special escape characters in the
 362     [[http://orgmode.org/manual/Capture-templates.html#Capture-templates][Org-mode manual]].
 363
 364
 365 # <<org-protocol-remember>>
 366 *** Org-protocol-remember
 367
 368     The =org-protocol-remember= handler is now obsolete.  However, the handler is
 369     still available for backward compatibility.  To use this handler, closely
 370     follow the setup for the current =org-protocol-capture= handler, and simply
 371     replace each occurrence of /capture/ with /remember/.
 372
 373     As remember templates look slightly different than capture templates, we
 374     provide an example here.
 375
 376 # <<example-remember-template>>
 377 ***** An example remember template
 378
 379 #+begin_src emacs-lisp
 380 (setq org-remember-templates
 381       '((?w "* %^{Title}\n\n  Source: %u, %c\n\n  %i" nil "Notes")))
 382 #+end_src
 383
 384     - '=?w=' :: makes this one the default template used for
 385               "=org-protocol://remember://=" URLs.
 386     - '=%c=' :: will be replaced by an Org-link pointing to the location of the
 387              page you have been visiting when clicking on the link. The page
 388              title will be the link's description.
 389     - '=%i=' :: will be replaced by the selected text in your browser window if
 390               any.
 391
 392     In addition, you may use the following placeholders in your template:
 393
 394     | Placeholders  | Replacement               |
 395     |---------------+---------------------------|
 396     | =%:link=        | URL of the web-page       |
 397     | =%:description= | The title of the web-page |
 398     | =%:initial=     | Selected text.            |
 399
 400     You may read more about templates and their special escape characters in the
 401     [[http://orgmode.org/manual/Capture-templates.html#Capture-templates][Org-mode manual]].
 402
 403 # <<open-source>>
 404 * Edit published content: =org-protocol-open-source=
 405
 406   This one was designed to help with opening sources for editing when browsing
 407   in the first place. =org-protocol-open-source= uses the custom variable
 408   =org-protocol-project-alist= to map URLs to (local) filenames.
 409
 410   Let's take http://orgmode.org/worg/ as our example.
 411
 412   Our intention is to click a bookmark (or link) to open the source of the
 413   published file we are reading in our favourite editor. The bookmark-URL above
 414   could be used again. But since =org-protocol-open-source= regards the first
 415   field only, this here will do:
 416
 417   : javascript:location.href='org-protocol://open-source://'+encodeURIComponent(location.href)
 418
 419   To open files publihed on Worg locally, =org-protocol-project-alist= should look
 420   like this (you may skip the second project):
 421
 422 #+begin_src emacs-lisp
 423 (setq org-protocol-project-alist
 424       '(("Worg"
 425          :base-url "http://orgmode.org/worg/"
 426          :working-directory "/home/user/worg/"
 427          :online-suffix ".html"
 428          :working-suffix ".org")
 429         ("My local Org-notes"
 430          :base-url "http://localhost/org/"
 431          :working-directory "/home/user/org/"
 432          :online-suffix ".php"
 433          :working-suffix ".org")))
 434 #+end_src
 435
 436   If you're now browsing http://orgmode.org/worg/org-contrib/org-protocol.html
 437   and find a typo or have an idea how to enhance the documentation, simply click
 438   the bookmark and start editing.
 439
 440   There are two functions to help you fill =org-protocol-project-alist= with
 441   valid contents. One possibility is =org-protocol-create= that guides you through
 442   the process. If you're editing an Org-mode file that is part of a publishing
 443   project in =org-publish-project-alist=, try
 444
 445   : M-x org-protocol-create-for-org RET
 446
 447 # <<open-source-rewritten-urls>>
 448 *** Handle rewritten URLs
 449
 450     In some cases, replacing =:base-url= with =:working-directory= and
 451     =:online-suffix= with =:working-suffix= will not yield the desired results.
 452
 453     Suppose you maintain an online store located at =http://example.com/=. The
 454     local sources reside in =/home/user/example/=. While most of the URLs map
 455     directly to local file names by stripping URL parameters from the end and
 456     replacing the =:base-url= with =:working-diretory= and =:online-suffix= with
 457     =:working-suffix=, this might not work for rewritten URLs. It's common
 458     practice to serve all products in such a store through one file and rewrite
 459     URLs that do not match an existing file on the server.
 460
 461     That way, a request to =http://example.com/print/posters-A4.html= might be
 462     rewritten on the server to something like
 463     =http://example.com/shop/products.php/posters-A4.html.php=, where
 464     =/posters-A4-digital.html.php= is the so called path info. Note that the
 465     browser will not notice the rewrite.
 466
 467     If you now click your =org-protocol://open-source://= bookmark, the handler
 468     will probably not find a file named
 469     =/home/user/example/print/posters-A4.html.php= and fail.
 470
 471     Or, even more simple, assume you're browsing =http://example.com/=. A file
 472     named =/home/user/example/.php= is not likely to exist.
 473
 474     Since Org-mode commit =69b46e10aab3b2374ecbc1a963ba56e77102a9a4= from 15th
 475     Nov. 2009, such an entry in =org-protocol-project-alist= may hold an
 476     additional property =:rewrites=. This property is a list of cons cells, each
 477     of which maps a regular expression to a path relative to the
 478     =:working-directory=.
 479
 480     Now map the URL to the path =/home/user/example/products.php= by adding the
 481     =:rewrites= property like this:
 482
 483 #+begin_src emacs-lisp
 484   (setq org-protocol-project-alist
 485         '(("example.com"
 486            :base-url "http://example.com/"
 487            :working-directory "/home/user/example/"
 488            :online-suffix ".php"
 489            :working-suffix ".php"
 490            :rewrites (("example.com/print/" . "products.php")
 491                       ("example.com/$" . "index.php"))
 492            )))
 493 #+end_src
 494
 495    Guess what the second =:rewrites= element does. Since =example.com/$= is used as
 496    a regular expression, it maps =http://example.com/=, =https://example.com=,
 497    =http://www.example.com/= and similar to =/home/user/example/index.php=.
 498
 499    The =:rewrites= are searched as a last resort if and only if no existing file
 500    name is matched.
 501
 502 * Other browsers
 503 #<<conkeror-setup>>
 504 *** Conkeror setup
 505
 506 Setting up org-protocol in [[http://conkeror.org/][Conkeror]] (an emacs inspired Mozilla web
 507 browser) requires a slightly different method. You may simply add the
 508 following snippets of code to your .conkerorrc file.[fn:tassilosblog]
 509
 510 For org-store-link, add the following to .conkerorrc:
 511
 512 : function org_store_link (url, title, window) {
 513 :     var cmd_str = 'emacsclient \"org-protocol://store-link://'+url+'/'+title+'\"';
 514 :     if (window != null) {
 515 :       window.minibuffer.message('Issuing ' + cmd_str);
 516 :     }
 517 :     shell_command_blind(cmd_str);
 518 : }
 519 :
 520 : interactive("org-store-link", "Stores [[url][title]] as org link and copies url to emacs kill ring",
 521 :           function (I) {
 522 :               org_store_link(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), I.window);
 523 :           });
 524
 525 For org-capture (or org-remember --- just exchange /capture/ with /remember/), use
 526 the following:
 527
 528 : function org_capture (url, title, selection, window) {
 529 :     var cmd_str = 'emacsclient \"org-protocol://capture://'+url+'/'+title+'/'+selection+'\"';
 530 :     if (window != null) {
 531 :       window.minibuffer.message('Issuing ' + cmd_str);
 532 :     }
 533 :     shell_command_blind(cmd_str);
 534 : }
 535 :
 536 : interactive("org-capture", "Clip url, title, and selection to capture via org-protocol",
 537 :           function (I) {
 538 :               org_capture(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), encodeURIComponent(I.buffer.top_frame.getSelection()), I.window);
 539 :           });
 540
 541 Now, you should be able to invoke the commands from within conkeror
 542 with =M-x org-store-link= and =M-x org-capture= (or remember).
 543
 544 Or, if you'd like your familiar emacs keybindings, you can add the
 545 following to your .conkerorrc:
 546
 547 : define_key(content_buffer_normal_keymap, "C-c r", "org-capture");
 548 : define_key(content_buffer_normal_keymap, "C-c l", "org-store-link");
 549
 550 [fn:tassilosblog] Adapted from Tassilo Horn's blog, "Calling
 551 org-remember from inside conkeror," November 14, 2008.
 552 http://tsdh.wordpress.com/2008/11/14/calling-org-remember-from-inside-conkeror/
 553
 554 *** Uzbl
 555     :PROPERTIES:
 556     :CUSTOM_ID: uzbl
 557     :END:
 558
 559 Uzbl is a minimalistic webkit browser for Unix/Linux.
 560
 561 - [[http://www.uzbl.org/]]
 562
 563 You can pass encoded url data from uzbl to org-protocol by adding the
 564 following lines to =.config/uzbl/config=.
 565
 566 #+begin_example
 567
 568 # Org-protocol
 569
 570 @cbind  \\r = sh 'emacsclient "org-protocol://capture://\@<encodeURIComponent(window.location.href)>\@/\@<encodeURIComponent(document.title)>\@/\@<document.getSelection()>\@"'
 571 @cbind  \\l = sh 'emacsclient "org-protocol://capture://\@<encodeURIComponent(window.location.href)>\@/\@<encodeURIComponent(document.title)>\@"'
 572
 573 #+end_example
 574
 575 These bind org-protocol-capture and org-store-line to "\r" and "\l" respectively.
 576
 577 # <<firefox-keybindings>>
 578 * Keybindings for Firefox
 579
 580   You can add key bindings for the =org-protocol= commands using the keyconfig
 581   Firefox extension.
 582
 583   First, install keyconfig from http://mozilla.dorando.at/keyconfig.xpi.
 584
 585   Open the keyconfig dialog by going to Tools and then Keyconfig.
 586
 587   Click the 'Add a new Key' button. Enter "Org store link" as the name.
 588   Enter the following in the box with /* CODE */ in it:
 589
 590   : var orgProtoString = 'org-protocol://store-link://'+
 591   :   encodeURIComponent(gBrowser.currentURI.spec) + '/' +
 592   :   encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
 593   :   encodeURIComponent(gBrowser.contentWindow.getSelection());
 594   :
 595   : gBrowser.loadURI(orgProtoString);
 596
 597   Click OK. You will then need to bind a key by clicking in the box next to the
 598   'Apply' button and pressing whatever key combination you want. Click 'Apply' to
 599   store the keybinding.
 600
 601   Repeat the steps, but call the next key "Org capture" and use the code below:
 602
 603   : var orgProtoString = 'org-protocol://capture://'+
 604   :   encodeURIComponent(gBrowser.currentURI.spec) + '/' +
 605   :   encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
 606   :   encodeURIComponent(content.window.getSelection());
 607   :
 608   : gBrowser.loadURI(orgProtoString);
 609
 610   Click Close, then OK, and then restart Firefox. You should then be able to
 611   access the org-protocol functions with your chosen keys.
 612
 613 # <<screencast-intro>>
 614 * Screencast: small introduction to org-protocol.el
 615
 616 #+begin_html
 617 <object width="640" height="464"><param name="allowfullscreen"
 618 value="true" /><param name="allowscriptaccess" value="always" /><param
 619 name="movie"
 620 value="http://vimeo.com/moogaloop.swf?clip_id=5662410&amp;server=vimeo.com&amp;show_title=1&amp;show_byline=1&amp;show_portrait=1&amp;color=FF7700&amp;fullscreen=1"
 621 /><embed
 622 src="http://vimeo.com/moogaloop.swf?clip_id=5662410&amp;server=vimeo.com&amp;show_title=1&amp;show_byline=1&amp;show_portrait=1&amp;color=FF7700&amp;fullscreen=1"
 623 type="application/x-shockwave-flash" allowfullscreen="true"
 624 allowscriptaccess="always" width="640" height="464"></embed></object>
 625 #+end_html
 626
 627 This screencast shows off some nice things you can do with Firefox,
 628 Emacs, Org-mode and org-protocol.el.
 629
 630 It first shows how to create two bookmarklets, =org-capture= and
 631 =org-store-link=. These bookmarklets enable your Firefox to talk to
 632 emacsclient via a new protocol (=org-protocol://=); emacsclient then
 633 parses the request and tells Emacs to capture or store stuff at the
 634 relevant places in your Org files.
 635
 636 At the end of the screencast, we create two ubiquity commands from these
 637 bookmarklets.  Now in Firefox =ALT-SPC org-capture RET= creates a note
 638 in my Org files.
 639
 640
 641 * Footnotes
 642
 643 [fn:1] Before commit =fc49c1ec96b2c789f573ae1ba936b930a8494402=, 3rd Sept. 2010,
 644 if a template with the key string "=w=" was defined, this one was chosen by
 645 default.  This was done to make bookmarks used for [[file:./org-annotation-helper.el][org-annotation-helper]] work
 646 without changing the template.
 647