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