File: org-protocol.el.html

Intercept calls from emacsclient to trigger custom actions.

This is done by advising server-visit-files to scan the list of filenames for org-protocol-the-protocol and sub-protocols defined in org-protocol-protocol-alist and org-protocol-protocol-alist-default.

Any application that supports calling external programs with an URL as argument could use this functionality. For example, you can configure bookmarks in your web browser to send a link to the current page to Org and create a note from it using org-capture. See Info node (org) Protocols for more information.

Usage:
------

  1.) Add this to your init file (.emacs probably):

      (require 'org-protocol)

  2.) Ensure emacs-server is up and running.
  3.) Try this from the command line (adjust the URL as needed):

      $ emacsclient \
        "org-protocol://store-link?url=http:%2F%2Flocalhost%2Findex.html&title=The%20title"

  4.) Optionally, add custom sub-protocols and handlers:

      (setq org-protocol-protocol-alist
            '(("my-protocol"
               :protocol "my-protocol"
               :function my-protocol-handler-function)))

      A "sub-protocol" will be found in URLs like this:

          org-protocol://sub-protocol?key=val&key2=val2

If it works, you can now setup other applications for using this feature.

Firefox users follow the steps documented on https://kb.mozillazine.org/Register_protocol, Opera setup is described here: http://www.opera.com/support/kb/view/535/

See also: https://orgmode.org/worg/org-contrib/org-protocol.html

Documentation
-------------

org-protocol.el comes with and installs handlers to open sources of published online content, store and insert the browser's URLs and cite online content by clicking on a bookmark in Firefox, Opera and probably other browsers and applications:

  * org-protocol-open-source uses the sub-protocol \"open-source\\" and maps
    URLs to local filenames defined in org-protocol-project-alist.

  * org-protocol-store-link stores an Org link (if Org is present) and
    pushes the browsers URL to the kill-ring for yanking. This handler is
    triggered through the sub-protocol \"store-link\\".

  * Call org-protocol-capture by using the sub-protocol \"capture\\". If
    Org is loaded, Emacs will pop-up a capture buffer and fill the
    template with the data provided. I.e. the browser's URL is inserted as an
    Org-link of which the page title will be the description part. If text
    was select in the browser, that text will be the body of the entry.

You may use the same bookmark URL for all those standard handlers and just adjust the sub-protocol used:

    javascript:location.href='org-protocol://sub-protocol?'+
          new URLSearchParams({
                url: location.href,
                title: document.title,
                body: window.getSelection()})

Alternatively use the following expression that encodes space as \"%20\\" instead of \"+\\", so it is compatible with Org versions from 9.0 to 9.4:

    location.href='org-protocol://sub-protocol?url='+
          encodeURIComponent(location.href)+'&title='+
          encodeURIComponent(document.title)+'&body='+
          encodeURIComponent(window.getSelection())

The handler for the sub-protocol \"capture\\" detects an optional template char that, if present, triggers the use of a special template. Example:

    location.href='org-protocol://capture?'+
          new URLSearchParams({template:'x', /* ... */})

or

    location.href='org-protocol://capture?template=x'+ ...

 uses template ?x.

Note that using double slashes is optional from org-protocol.el's point of view because emacsclient squashes the slashes to one.

Defined variables (7)

Defined functions (14)

Defined faces (0)