org-contrib/org-protocol.org: Linus setup for KDE
[worg.git] / 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