Function: org-protocol-capture

org-protocol-capture is a byte-compiled function defined in org-protocol.el.gz.

Signature

(org-protocol-capture INFO)

Documentation

Process an org-protocol://capture style url with INFO.

The sub-protocol used to reach this function is set in org-protocol-protocol-alist.

This function detects an URL, title and optional text, separated by /. The location for a browser's bookmark looks like this:

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

or to keep compatibility with Org versions from 9.0 to 9.4:

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

By default, it uses the character org-protocol-default-template-key, which should be associated with a template in org-capture-templates. You may specify the template with a template= query parameter, like this:

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

Now template ?b will be used.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-protocol.el.gz
(defun org-protocol-capture (info)
  "Process an org-protocol://capture style url with INFO.

The sub-protocol used to reach this function is set in
`org-protocol-protocol-alist'.

This function detects an URL, title and optional text, separated
by `/'.  The location for a browser's bookmark looks like this:

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

or to keep compatibility with Org versions from 9.0 to 9.4:

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

By default, it uses the character `org-protocol-default-template-key',
which should be associated with a template in `org-capture-templates'.
You may specify the template with a template= query parameter, like this:

  javascript:location.href = \\='org-protocol://capture?template=b\\='+ ...

Now template ?b will be used."
  (let* ((parts
	  (pcase (org-protocol-parse-parameters info)
	    ;; New style links are parsed as a plist.
	    ((let `(,(pred keywordp) . ,_) info) info)
	    ;; Old style links, with or without template key, are
	    ;; parsed as a list of strings.
	    (p
	     (let ((k (if (= 1 (length (car p)))
			  '(:template :url :title :body)
			'(:url :title :body))))
	       (org-protocol-assign-parameters p k)))))
	 (template (or (plist-get parts :template)
		       org-protocol-default-template-key))
	 (url (and (plist-get parts :url)
		   (org-protocol-sanitize-uri (plist-get parts :url))))
	 (type (and url
		    (string-match "^\\([a-z]+\\):" url)
		    (match-string 1 url)))
	 (title (or (plist-get parts :title) ""))
	 (region (or (plist-get parts :body) ""))
	 (orglink
	  (if (null url) title
	    (org-link-make-string url (or (org-string-nw-p title) url))))
	 ;; Avoid call to `org-store-link'.
	 (org-capture-link-is-already-stored t))
    ;; Only store link if there's a URL to insert later on.
    (when url (push (list url title) org-stored-links))
    (org-link-store-props :type type
			  :link url
			  :description title
			  :annotation orglink
			  :initial region
			  :query parts)
    (raise-frame)
    (org-capture nil template)
    (message "Item captured.")
    ;; Make sure we do not return a string, as `server-visit-files',
    ;; through `server-edit', would interpret it as a file name.
    nil))