From 9cbaf959a3518cbcf3aa50a45c26061566861c57 Mon Sep 17 00:00:00 2001 From: Charles Choi Date: Fri, 30 May 2025 17:46:50 -0700 Subject: [PATCH 2/2] Rewrite Org Protocol Page (org-protocol.org) - Rewrite to support Emacs 30.1 and currently released OS in May 2025. --- .../images/org-protocol-architecture.svg | 49 ++ org-contrib/org-protocol.org | 657 +++--------------- 2 files changed, 154 insertions(+), 552 deletions(-) create mode 100644 org-contrib/images/org-protocol-architecture.svg diff --git a/org-contrib/images/org-protocol-architecture.svg b/org-contrib/images/org-protocol-architecture.svg new file mode 100644 index 00000000..277cb55a --- /dev/null +++ b/org-contrib/images/org-protocol-architecture.svg @@ -0,0 +1,49 @@ + + + + + + +Org Protocol Architecture + + + +a + +External App + + + +b + +Scheme Handler +(OS-specific) + + + +a->b + + +org-protocol:// +request + + + +c + +Emacs +(server) + + + +b->c + + +socket +request + + + diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org index 08d191b4..797c9148 100644 --- a/org-contrib/org-protocol.org +++ b/org-contrib/org-protocol.org @@ -1,25 +1,7 @@ -#+TITLE: org-protocol.el -- Intercept calls from emacsclient to trigger custom actions +#+TITLE: Org Protocol - Trigger custom actions in Emacs via a custom URL scheme #+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 #+STARTUP: odd #+SETUPFILE: ../macros.setupfile -#+HTML_HEAD_EXTRA: #+HTML_LINK_UP: index.html #+HTML_LINK_HOME: https://orgmode.org/worg/ @@ -27,76 +9,100 @@ # Free Documentation license v1.3 or later, code examples are released # under the GNU General Public License v3 or later. -org-protocol intercepts calls from emacsclient to trigger custom actions without -external dependencies. Only one protocol has to be configured with your external -applications or the operating system, to trigger an arbitrary number of custom -actions. Just register your custom sub-protocol and handler with the variable -`org-protocol-protocol-alist'. +* Org Protocol -* About org-protocol.el +Org Protocol is a custom URL scheme used to trigger custom actions in Emacs. The URL scheme is ~org-protocol://~. A common use case for Org Protocol is data import (for example a web clipper), where an external application can make a URL request with scheme ~org-protocol://~ to send data to Emacs. - =org-protocol.el= is based on code and ideas from - [[file:./org-annotation-helper.org][org-annotation-helper.el]] and =org-browser-url.el=. +The host part of the URL is interpreted as a /sub-protocol/. There are three pre-defined sub-protocols provided by Org Protocol: - "=org-protocol:/sub-protocol:/=" triggers actions associated with =sub-protocol= - through the custom variable =org-protocol-protocol-alist=. +- ~store-link~ Store a link, push URL to kill-ring. +- ~capture~ Fill a buffer with external information. +- ~open-source~ Edit published contents. - It comes with four predefined handlers: - - =org-protocol-store-link= :: - triggered through the sub-protocol "=store-link=". Stores an Org-link and - pushes the URL to the =kill-ring=. - - =org-protocol-capture= :: - Fill a =CAPTURE= buffer with information gathered somewhere else. This - handler is triggered through the "=capture=" sub-protocol and uses the - function =org-capture=. - - =org-protocol-remember= :: - Fills a remember buffer with information gathered somewhere else. This - handler is triggered through the "=remember=" sub-protocol and still - available for backward compatibility. This handler uses =org-remember=. Use - the current =org-protocol-capture=. +Custom sub-protocols for Org Protocol can be defined in the variable ~org-protocol-protocol-alist~. - - =org-protocol-open-source= :: - "=open-source=". Maps URLs to local filenames. Use this to open sources of - already published contents in emacs for editing. +The diagram below illustrates how an Org Protocol request is handled. - =org-protocol= helps creating custom handlers [[file:../org-tutorials/org-protocol-custom-handler.org][(tutorial)]] and so called - =org-protocol-projects=. +#+BEGIN_SRC dot :file images/org-protocol-architecture.svg :cmdline -Tsvg :exports none :results raw +digraph "Org Protocol Architecture" { + rankdir=LR; + node [shape="rect", color="black", style="filled", fillcolor="white", fontcolor="black", fontsize=12, fontname="Helvetica"]; + edge [fontname="Helvetica", fontsize=10]; + + a[label="External App"]; + b[label="Scheme Handler\n(OS-specific)"]; + c[label="Emacs\n(server)"] - #+begin_infobox - @As of Org mode release 7.01 =org-protocol-remember= is now by =org-protocol-capture=.@ - If not stated otherwise, you may simply replace each occurrence of - /capture/ with /remember/ throughout this document, if you still want to use - remember templates. Use =M-x org-version= to find out about the version you're - using. - #+end_infobox + a -> b [label="org-protocol://\nrequest"]; + b -> c [label="socket\nrequest"]; +} +#+END_SRC + +[[file:images/org-protocol-architecture.svg]] + +The scheme handler for GNU/Linux and Windows is typically ~emacsclient~. On recent versions (since Ventura) of macOS, security policy prevents external applications from running programs like ~emacsclient~ outside of their sandbox. A commercial offering ([[http://yummymelon.com/scrim][Scrim]]) is available to serve as a macOS-trusted scheme handler for Org Protocol requests. Users running a version of macOS older than Ventura can still use ~emacsclient~ as a scheme handler for Org Protocol. + +*NOTE*: This document is a rewrite of the [[../archive/org-contrib/org-protocol.org][Org Protocol page that is archived]]. + +* Version +All guidance provided on this page should conform to GNU Emacs 30.1. * Installation +*** Server - - To load org-protocol.el add the following to your =.emacs=: +Generally, Org Protocol requires that Emacs server is running to relay an Org Protocol request from an external app to Emacs. The transport between the scheme handler and Emacs server is via socket communication. By default, a local domain socket is used. - : (server-start) - : (add-to-list 'load-path "~/path/to/org/protocol/") - : (require 'org-protocol) +***** GNU/Linux and Unix variants -* Browser / system setup +Add the following lines to the Emacs initialization file (~init.el~, ~$HOME/.emacs~) to start Emacs server. - - [[GNU/Linux setup]] - - [[Windows setup]] - - [[Mac OS X setup]] - - [[*Applications][Applications]] - - [[*Verify the installation][Verify the installation]] +: (server-start) +: (require 'org-protocol) -*** GNU/Linux setup +***** Windows - Most common desktop environments (Gnome, KDE et al) comply with the [[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html][XDG Desktop Entry Specification]]. - This means setting up =emacsclient= as the =org-protocol= handler using a .desktop file can be regarded - as a, in most cases, standard way to set this up in most common desktop environments. +Native Windows has no support for a local domain socket. As such a TCP socket is used instead. Add the following lines to the Emacs initialization file (~init.el~, ~$HOME/.emacs~) to start Emacs server. - Some environments, e.g. Gnome as of Gnome 3, have deprecated other configuration methods, - e.g. =gconftool-2= to set-up protocol handling. +: (setopt server-use-tcp t) +: (server-start) +: (require 'org-protocol) - Create an =org-protocol.desktop= file either in =~/.local/share/applications/= to set-up =emacsclient= as the - =org-protocol= handler for the current user or in =/usr/share/applications= to set-up a system-wide +***** macOS + +Recent versions of macOS (since Ventura) disallow the use of a local domain socket for inter-process communication between apps with separate sandboxes. Users using [[http://yummymelon.com/scrim][Scrim]] can instead setup a TCP socket. Add the following lines to the Emacs initialization file (~init.el~, ~$HOME/.emacs~) to start Emacs server. + +: (setopt server-use-tcp t) +: (server-start) +: (require 'org-protocol) + +Note that users of the [[https://bitbucket.org/mituharu/emacs-mac/src/master/][Yamamoto Mitsuharu fork of Emacs]] (aka "Emacs Mac App") do not have to do the above as Org Protocol support is /natively/ supported where the scheme handler is /built-in/ to Emacs. + +*** Scheme Handler + +The scheme handler is generally an OS-level configuration. With recent releases of Emacs (≥ 30.1) and OS, this is little to nothing for the user to do. + +***** GNU/Linux and Unix variants +Emacs 30.1+ now has ~emacsclient.desktop~ configured to handle Org Protocol URL requests. For users with older versions of Emacs, refer to [[*Legacy Scheme Handler Install][Legacy Scheme Handler Install]]. + +***** Windows + +#+HTML:

NOTE: This section needs UPDATING. Need verification from a Windows user in 2025.

+ +Refer to [[*Legacy Scheme Handler Install][Legacy Scheme Handler Install]] for instructions on configuring Windows to handle the Org Protocol URL scheme. + +***** macOS + +Users using [[http://yummymelon.com/scrim][Scrim]] automatically have the Org Protocol scheme ~org-protocol://~ registered with macOS upon its install. For macOS versions 13+ (Ventura) and above, this is the only known Org Protocol solution. + +Users of a macOS release that is older than Ventura can refer to the [[*Legacy Scheme Handler Install][Legacy Scheme Handler Install]]. + +***** Legacy Scheme Handler Install +******* GNU/Linux and Unix Variants + Most common desktop environments (Gnome, KDE et al) comply with the [[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html][XDG Desktop Entry Specification]]. This means setting up =emacsclient= as the =org-protocol= handler using a .desktop file can be regarded as a, in most cases, standard way to set this up in most common desktop environments. + + Some environments, e.g. Gnome as of Gnome 3, have deprecated other configuration methods, e.g. =gconftool-2= to set-up protocol handling. + + Create an =org-protocol.desktop= file either in =~/.local/share/applications/= to set-up =emacsclient= as the =org-protocol= handler for the current user or in =/usr/share/applications= to set-up a system-wide configuration: #+begin_example @@ -117,14 +123,11 @@ actions. Just register your custom sub-protocol and handler with the variable : update-desktop-database ~/.local/share/applications/ -*** Windows setup +******* Windows - Windows users may register the "=org-protocol=" once for all by adjusting the - following to their facts, save it as *.reg file and double-click it. This - worked for me on Windows-XP Professional and the emasc23 from ourcomments.org - ([[http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl]]). I'm no Windows user - though and enhancements are more than welcome on the org-mode mailinglist. The - original file is from http://kb.mozillazine.org/Register_protocol. +#+HTML:

NOTE: This section is STALE. Need verification from a Windows user in 2025.

+ +Windows users may register the "=org-protocol=" once for all by adjusting the following to their facts, save it as *.reg file and double-click it. This worked for me on Windows-XP Professional and the emasc23 from ourcomments.org ([[http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl]]). I'm no Windows user though and enhancements are more than welcome on the org-mode mailinglist. The original file is from http://kb.mozillazine.org/Register_protocol. #+begin_example REGEDIT4 @@ -138,493 +141,43 @@ actions. Just register your custom sub-protocol and handler with the variable @="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\"" #+end_example -*** Mac OS X setup +******* macOS - Follow the directions for installing EmacsClient.app from https://github.com/neil-smithline-elisp/EmacsClient.app. This should configure the org-protocol for all Mac OS X browsers. - - After installing EmacsClient.app you should then [[Verify the installation]]. Once verified, you can begin [[Using org-protocol]]. +#+HTML:

NOTE: This section is STALE. Need verification from macOS users using an release older than Ventura (13).

+ 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. + If that doesn't work, you might check https://github.com/xuchunyang/setup-org-protocol-on-mac for building a custom handler, combined with the per-browser config information below. -*** Applications +* Using Org Protocol -***** Firefox - If you are using Firefox on Mac OS X, see [[Mac OS X setup]]. +It is the responsibility for the external app to construct the Org Protocol URL and make the request. The URL construction is dependent on the /sub-protocol/ that is used. - - Please refer to http://kb.mozillazine.org/Register_protocol and use - "org-protocol" as protocol. +*** External App Configuration -***** Acrobat Reader - :PROPERTIES: - :CUSTOM_ID: acrobat-reader-setup - :END: +Most web browsers (Chrome, Firefox, Safari) can support a bookmark whose address is JavaScript code that will construct the Org Protocol URL. For example, a ~store-link~ bookmark address is shown below. This solution works across different platforms. - Adapted from [[https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org]] +#+begin_src js +javascript:location.href='org-protocol://store-link?url='+encodeURIComponent(window.location.href)+'&title='+encodeURIComponent(document.title); +#+end_src - You place a javascript file for each menu entry in - =~/.adobe/Acrobat//JavaScripts= on unix-like systems or - =c:/Program Files/Adobe/Acrobat /Reader/Javascripts/= on - Windows, or wherever your Adobe Reader Installation might look for - javascript. - The examples given here will place new menu entries in the "Tools" - menu, after restarting Adobe Reader. +*** Capture Sub-protocol -******* org-store-link.js - : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org - : app.addMenuItem({cName:"org-store-link", cParent:"Tools", - : cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"}); +Users interested in "web-clipper" functionality will want to use the ~capture~ sub-protocol that is integrated with the Org Capture feature. -******* org-capture.js - : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org - : app.addMenuItem({cName:"org-capture", cParent:"Tools", - : cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"}); +With it, a JavaScript bookmark as shown below can be used to capture selected text alongside a web page's URL and title. - And this one, if you still use remember templates: +#+begin_src js +javascript:location.href='org-protocol://capture?url='+encodeURIComponent(window.location.href)+'&title='+encodeURIComponent(document.title)+'&body='+encodeURIComponent(window.getSelection()); +#+end_src -******* org-remember.js - : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org - : app.addMenuItem({cName:"org-remember", cParent:"Tools", - : cExec:"app.launchURL('org-protocol://remember://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"}); +Beforehand though, a number of Emacs variables should be set to have this Org Protocol ~capture~ working. -***** Opera +- ~org-capture-templates~ +- ~org-protocol-default-template-key~ +- ~org-directory~ +- ~org-default-notes-file~ - If you are using Opera on Mac OS X, see [[Mac OS X setup]]. +Refer to the Org documentation to understand the workings of the above in constructing capture templates for Org Protocol. - Opera setup is described here: - http://www.opera.com/support/kb/view/535/. - - To set up opera for use with org-protocol, follow these steps: - - 1. Choose "/Tools/" -> "/Prefences/" from the menu. - 2. Select the tab "/Advanced/". - 3. Choose "/Programs/" from the list on the left. - 4. Now click the button "/Add/" on the very right. - 5. In the new dialog window, enter "=org-protocol=" as "/Protocol/", choose the - radio button "/Open with other application/" and enter the path to - emacsclient. - -***** Safari - Safari is only supported on Mac systems, not iOS systems. - - See [[Mac OS X setup]] for directions. - -*** Verify the installation - - After your protocol is registered with your browser/OS, these links here - should work. Click on them and see if emacs reacts: - - #+begin_export html - - #+end_export - -* Using org-protocol - - To actually use org-protocol add a bookmark to Firefox or Opera. - - Here is the URL to use as "/Location/" for browser bookmarks. Just remove the - line breaks and replace "=sub-protocol=" with the real sub-protocol to use: - - : javascript:location.href='org-protocol://sub-protocol://'+ - : encodeURIComponent(location.href)+'/'+ - : encodeURIComponent(document.title)+'/'+ - : encodeURIComponent(window.getSelection()) - - This URL may be used for all three standard handlers in =org-protocol.el=. Some - of the values will be ignored (e.g. =store-link:/= will use the URL and title - only). - -* Links and bookmarks: =org-protocol-store-link= - - =org-store-link= stores an Org-link insertable through =M-x org-insert-link= and - pushes the URL found onto the =kill-ring= for yanking (=C-y=). The sub-protocol - used is "=store-link=": - - : emacsclient org-protocol:/store-link:/URL/TITLE - - will store this Org-link: - - #+begin_example - [[URL][TITLE]] - #+end_example - - In addition, =URL= will be pushed on the =kill-ring= for yanking ('=C-y='). You will - have to encode =URL= and/or =TITLE= if they contain slashes, and probably quote - those for the shell. - - To use this feature, add a bookmark with an arbitrary name (e.g. - "/Org: store-link/") and enter this as "=Location=": - - : javascript:location.href='org-protocol://store-link://'+encodeURIComponent(location.href) - -* Note taking and citations: =org-protocol-capture= - - This one is triggered through the sub-protocol "=capture=" and consumes up to - three data fields: - - : emacsclient org-protocol:/capture:/URL/TITLE/BODY - - will pop up an /*Capture*/ buffer and fill the template with the data - submitted. - - To use this feature, add a bookmark with an arbitrary name (e.g. - "/Org: capture/") and enter this as "=Location=": - - : javascript:location.href='org-protocol://capture://'+ - : encodeURIComponent(location.href)+'/'+ - : encodeURIComponent(document.title)+'/'+ - : encodeURIComponent(window.getSelection()) - - The result depends on the template used. See [[*An example capture template][An example capture template]] further down. - - Note, that this one, as opposed to the other two standard handlers, does not - mix with more parameters to emacsclient. All parameters but the - #'=org-protocol://org-capture://...=' one will be discarded. - -*** Which capture template is used? - :PROPERTIES: - :ID: org:f56bcb9a-20e7-4b37-99f1-839a8821cc4b - :END: - - You don't need to setup a capture template to use - =org-protocol-capture=, since Org-mode provides a default template - for those cases. Newer versions provide an interactive interface - for choosing a template. You may provide a template to be used by - customizing the variable =org-capture-default-template= [fn:1]. - - The problem with this solution would be, that only one template - can be used with the fuction. Luckily, =org-protocol-capture= - understands a slightly extended syntax to choose between several - templates: If the first field of the data submitted is exactly one - character in length, this character will be used to select the - template. - - Here we choose to use the "=x=" template: - - : emacsclient org-protocol:/capture:/x/URL/TITLE/BODY - - And, again, as bookmark location: - : javascript:location.href='org-protocol://capture://x/'+ - : encodeURIComponent(location.href)+'/'+ - : encodeURIComponent(document.title)+'/'+ - : encodeURIComponent(window.getSelection()) - -***** An example capture template - - #+begin_src emacs-lisp - (setq org-capture-templates - (quote - (("w" - "Default template" - entry - (file+headline "~/org/capture.org" "Notes") - "* %^{Title}\n\n Source: %u, %c\n\n %i" - :empty-lines 1) - ;; ... more templates here ... - ))) - #+end_src - - - "=w=" :: makes this one the default template used for - "=org-protocol://capture://=" URLs. - - =entry= :: makes it a regular entry with a headline. - - =file+headline= :: files the note in file "=~/org/capture.org=" as child of - the headline "=Notes=" - - '=%c=' :: will be replaced by an Org-link pointing to the location of the - page you have been visiting when clicking on the link. The page - title will be the link's description. - - '=%i=' :: will be replaced by the selected text in your browser window if - any. - - In addition, you may use the following placeholders in your template: - - | Placeholders | Replacement | - |---------------+---------------------------| - | =%:link= | URL of the web-page | - | =%:description= | The title of the web-page | - | =%:initial= | Selected text. | - - You may read more about templates and their special escape characters in the - [[https://orgmode.org/manual/Capture-templates.html#Capture-templates][Org-mode manual]]. - -*** Org-protocol-remember - - The =org-protocol-remember= handler is now obsolete. However, the handler is - still available for backward compatibility. To use this handler, closely - follow the setup for the current =org-protocol-capture= handler, and simply - replace each occurrence of /capture/ with /remember/. - - As remember templates look slightly different than capture templates, we - provide an example here. - -***** An example remember template - - #+begin_src emacs-lisp -(setq org-remember-templates - '((?w "* %^{Title}\n\n Source: %u, %c\n\n %i" nil "Notes"))) - #+end_src - - - '=?w=' :: makes this one the default template used for - "=org-protocol://remember://=" URLs. - - '=%c=' :: will be replaced by an Org-link pointing to the location of the - page you have been visiting when clicking on the link. The page - title will be the link's description. - - '=%i=' :: will be replaced by the selected text in your browser window if - any. - - In addition, you may use the following placeholders in your template: - - | Placeholders | Replacement | - |---------------+---------------------------| - | =%:link= | URL of the web-page | - | =%:description= | The title of the web-page | - | =%:initial= | Selected text. | - - You may read more about templates and their special escape characters in the - [[https://orgmode.org/manual/Capture-templates.html#Capture-templates][Org-mode manual]]. - -* Edit published content: =org-protocol-open-source= - - This one was designed to help with opening sources for editing when browsing - in the first place. =org-protocol-open-source= uses the custom variable - =org-protocol-project-alist= to map URLs to (local) filenames. - - Let's take https://orgmode.org/worg/ as our example. - - Our intention is to click a bookmark (or link) to open the source of the - published file we are reading in our favourite editor. The bookmark-URL above - could be used again. But since =org-protocol-open-source= regards the first - field only, this here will do: - - : javascript:location.href='org-protocol://open-source://'+encodeURIComponent(location.href) - - To open files publihed on Worg locally, =org-protocol-project-alist= should look - like this (you may skip the second project): - - #+begin_src emacs-lisp -(setq org-protocol-project-alist - '(("Worg" - :base-url "https://orgmode.org/worg/" - :working-directory "/home/user/worg/" - :online-suffix ".html" - :working-suffix ".org") - ("My local Org-notes" - :base-url "http://localhost/org/" - :working-directory "/home/user/org/" - :online-suffix ".php" - :working-suffix ".org"))) - #+end_src - - If you're now browsing https://orgmode.org/worg/org-contrib/org-protocol.html - and find a typo or have an idea how to enhance the documentation, simply click - the bookmark and start editing. - - There are two functions to help you fill =org-protocol-project-alist= with - valid contents. One possibility is =org-protocol-create= that guides you through - the process. If you're editing an Org-mode file that is part of a publishing - project in =org-publish-project-alist=, try - - : M-x org-protocol-create-for-org RET - -*** Handle rewritten URLs - - In some cases, replacing =:base-url= with =:working-directory= and - =:online-suffix= with =:working-suffix= will not yield the desired results. - - Suppose you maintain an online store located at =http://example.com/=. The - local sources reside in =/home/user/example/=. While most of the URLs map - directly to local file names by stripping URL parameters from the end and - replacing the =:base-url= with =:working-diretory= and =:online-suffix= with - =:working-suffix=, this might not work for rewritten URLs. It's common - practice to serve all products in such a store through one file and rewrite - URLs that do not match an existing file on the server. - - That way, a request to =http://example.com/print/posters-A4.html= might be - rewritten on the server to something like - =http://example.com/shop/products.php/posters-A4.html.php=, where - =/posters-A4-digital.html.php= is the so called path info. Note that the - browser will not notice the rewrite. - - If you now click your =org-protocol://open-source://= bookmark, the handler - will probably not find a file named - =/home/user/example/print/posters-A4.html.php= and fail. - - Or, even more simple, assume you're browsing =http://example.com/=. A file - named =/home/user/example/.php= is not likely to exist. - - Since Org-mode commit =69b46e10aab3b2374ecbc1a963ba56e77102a9a4= from 15th - Nov. 2009, such an entry in =org-protocol-project-alist= may hold an - additional property =:rewrites=. This property is a list of cons cells, each - of which maps a regular expression to a path relative to the - =:working-directory=. - - Now map the URL to the path =/home/user/example/products.php= by adding the - =:rewrites= property like this: - - #+begin_src emacs-lisp - (setq org-protocol-project-alist - '(("example.com" - :base-url "http://example.com/" - :working-directory "/home/user/example/" - :online-suffix ".php" - :working-suffix ".php" - :rewrites (("example.com/print/" . "products.php") - ("example.com/$" . "index.php")) - ))) - #+end_src - - Guess what the second =:rewrites= element does. Since =example.com/$= is used as - a regular expression, it maps =http://example.com/=, =https://example.com=, - =http://www.example.com/= and similar to =/home/user/example/index.php=. - - The =:rewrites= are searched as a last resort if and only if no existing file - name is matched. - -* Other browsers - -*** Conkeror setup - - Setting up org-protocol in [[http://conkeror.org/][Conkeror]] (an emacs inspired Mozilla web - browser) requires a slightly different method. You may simply add the - following snippets of code to your .conkerorrc file[fn:2]. - - For org-store-link, add the following to .conkerorrc: - - : function org_store_link (url, title, window) { - : var cmd_str = 'emacsclient \"org-protocol://store-link://'+url+'/'+title+'\"'; - : if (window != null) { - : window.minibuffer.message('Issuing ' + cmd_str); - : } - : shell_command_blind(cmd_str); - : } - : - : interactive("org-store-link", "Stores [[url][title]] as org link and copies url to emacs kill ring", - : function (I) { - : org_store_link(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), I.window); - : }); - - For org-capture (or org-remember --- just exchange /capture/ with /remember/), use - the following: - - : function org_capture (url, title, selection, window) { - : var cmd_str = 'emacsclient \"org-protocol://capture://'+url+'/'+title+'/'+selection+'\"'; - : if (window != null) { - : window.minibuffer.message('Issuing ' + cmd_str); - : } - : shell_command_blind(cmd_str); - : } - : - : interactive("org-capture", "Clip url, title, and selection to capture via org-protocol", - : function (I) { - : org_capture(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), encodeURIComponent(I.buffer.top_frame.getSelection()), I.window); - : }); - - Now, you should be able to invoke the commands from within conkeror - with =M-x org-store-link= and =M-x org-capture= (or remember). - - Or, if you'd like your familiar emacs keybindings, you can add the - following to your .conkerorrc: - - : define_key(content_buffer_normal_keymap, "C-c r", "org-capture"); - : define_key(content_buffer_normal_keymap, "C-c l", "org-store-link"); - -*** Uzbl - :PROPERTIES: - :CUSTOM_ID: uzbl - :END: - - Uzbl is a minimalistic webkit browser for Unix/Linux. - - - [[http://www.uzbl.org/]] - - You can pass encoded url data from uzbl to org-protocol by adding the - following lines to =.config/uzbl/config=. - - #+begin_example - - # Org-protocol - - @cbind \\r = sh 'emacsclient "org-protocol://capture://\@\@/\@\@/\@\@"' - @cbind \\l = sh 'emacsclient "org-protocol://capture://\@\@/\@\@"' - - #+end_example - - These bind org-protocol-capture and org-store-line to "\r" and - "\l" respectively. - -* Keybindings for Firefox - - You can add key bindings for the =org-protocol= commands using the - keyconfig Firefox extension. - - First, install keyconfig from - http://mozilla.dorando.at/keyconfig.xpi. - - Open the keyconfig dialog by going to Tools and then Keyconfig. - - Click the 'Add a new Key' button. Enter "Org store link" as the name. - Enter the following in the box with /* CODE */ in it: - - : var orgProtoString = 'org-protocol://store-link://'+ - : encodeURIComponent(gBrowser.currentURI.spec) + '/' + - : encodeURIComponent(gBrowser.contentWindow.document.title) + '/' + - : encodeURIComponent(gBrowser.contentWindow.getSelection()); - : - : gBrowser.loadURI(orgProtoString); - - Click OK. You will then need to bind a key by clicking in the box - next to the 'Apply' button and pressing whatever key combination you - want. Click 'Apply' to store the keybinding. - - Repeat the steps, but call the next key "Org capture" and use the - code below: - - : var orgProtoString = 'org-protocol://capture://'+ - : encodeURIComponent(gBrowser.currentURI.spec) + '/' + - : encodeURIComponent(gBrowser.contentWindow.document.title) + '/' + - : encodeURIComponent(content.window.getSelection()); - : - : gBrowser.loadURI(orgProtoString); - - Click Close, then OK, and then restart Firefox. You should then be - able to access the org-protocol functions with your chosen keys. - -* Screencast: small introduction to org-protocol.el - - #+begin_export html - - #+end_export - - This screencast shows off some nice things you can do with Firefox, - Emacs, Org-mode and org-protocol.el. - - It first shows how to create two bookmarklets, =org-capture= and - =org-store-link=. These bookmarklets enable your Firefox to talk to - emacsclient via a new protocol (=org-protocol://=); emacsclient then - parses the request and tells Emacs to capture or store stuff at the - relevant places in your Org files. - - At the end of the screencast, we create two ubiquity commands from - these bookmarklets. Now in Firefox =ALT-SPC org-capture RET= creates - a note in my Org files. - -* Footnotes - -[fn:1] Before commit =fc49c1ec96b2c789f573ae1ba936b930a8494402=, 3rd -Sept. 2010, if a template with the key string "=w=" was defined, this -one was chosen by default. This was done to make bookmarks used for -[[file:./org-annotation-helper.org][org-annotation-helper]] work without changing the template. - -[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 -from inside conkeror," November 14, 2008. -- 2.49.0