diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d9957a..114de4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ ### Removed ### Changed - [#1795](https://github.com/org-roam/org-roam/pull/1795) buffer: optimized reflinks fetch +- [#1809](https://github.com/org-roam/org-roam/pull/1809) capture: the mandatory `:if-new` property of each capture template is now renamed to `:target` ### Fixed - [#1798](https://github.com/org-roam/org-roam/pull/1798) org-roam-node-at-point: do not skip invisible headings diff --git a/doc/org-roam.org b/doc/org-roam.org index ae19127..33817d6 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -698,7 +698,7 @@ extension in your Org-roam capture templates. For example: #+begin_src emacs-lisp (setq org-roam-capture-templates '(("d" "default" plain "%?" - :if-new (file+head "${slug}.org.gpg" + :target (file+head "${slug}.org.gpg" "#+title: ${title}\n") :unnarrowed t))) #+end_src @@ -899,7 +899,7 @@ of the template are similar to ~org-capture~ templates. #+BEGIN_SRC emacs-lisp (("d" "default" plain "%?" - :if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org" + :target (file+head "%<%Y%m%d%H%M%S>-${slug}.org" "#+title: ${title}\n") :unnarrowed t)) #+END_SRC @@ -913,8 +913,12 @@ of the template are similar to ~org-capture~ templates. here. 5. ~"%?"~ is the template inserted on each call to ~org-roam-capture-~. This template means don't insert any content, but place the cursor here. -6. ~:if-new~ is a compulsory specification in the Org-roam capture template. - This indicates the location for the new node. +6. ~:target~ is a compulsory specification in the Org-roam capture template. The + first element of the list indicates the type of the target, the second + element indicates the location of the captured node, and the rest of the + elements indicate prefilled template that will be inserted and the position + of the point will be adjusted for. The latter behavior various from type to + type of the capture target. 7. ~:unnarrowed t~ tells org-capture to show the contents for the whole file, rather than narrowing to just the entry. This is part of the Org-capture templates. @@ -1054,7 +1058,7 @@ Here is a sane default configuration: (setq org-roam-dailies-capture-templates '(("d" "default" entry "* %?" - :if-new (file+head "%<%Y-%m-%d>.org" + :target (file+head "%<%Y-%m-%d>.org" "#+title: %<%Y-%m-%d>\n")))) #+end_src diff --git a/doc/org-roam.texi b/doc/org-roam.texi index ed06eff..dc310c8 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -1062,7 +1062,7 @@ extension in your Org-roam capture templates. For example: @lisp (setq org-roam-capture-templates '(("d" "default" plain "%?" - :if-new (file+head "$@{slug@}.org.gpg" + :target (file+head "$@{slug@}.org.gpg" "#+title: $@{title@}\n") :unnarrowed t))) @end lisp @@ -1305,7 +1305,7 @@ of the template are similar to @code{org-capture} templates. @lisp (("d" "default" plain "%?" - :if-new (file+head "%<%Y%m%d%H%M%S>-$@{slug@}.org" + :target (file+head "%<%Y%m%d%H%M%S>-$@{slug@}.org" "#+title: $@{title@}\n") :unnarrowed t)) @end lisp @@ -1331,8 +1331,12 @@ here. This template means don't insert any content, but place the cursor here. @item -@code{:if-new} is a compulsory specification in the Org-roam capture template. -This indicates the location for the new node. +@code{:target} is a compulsory specification in the Org-roam capture +template. The first element of the list indicates the type of the +target, the second element indicates the location of the captured +node, and the rest of the elements indicate prefilled template that +will be inserted and the position of the point will be adjusted for. +The latter behavior various from type to type of the capture target. @item @code{:unnarrowed t} tells org-capture to show the contents for the whole file, @@ -1519,7 +1523,7 @@ Here is a sane default configuration: (setq org-roam-dailies-capture-templates '(("d" "default" entry "* %?" - :if-new (file+head "%<%Y-%m-%d>.org" + :target (file+head "%<%Y-%m-%d>.org" "#+title: %<%Y-%m-%d>\n")))) @end lisp diff --git a/extensions/org-roam-dailies.el b/extensions/org-roam-dailies.el index 686a9fc..4534783 100644 --- a/extensions/org-roam-dailies.el +++ b/extensions/org-roam-dailies.el @@ -62,7 +62,7 @@ This path is relative to `org-roam-directory'." (defcustom org-roam-dailies-capture-templates `(("d" "default" entry "* %?" - :if-new (file+head "%<%Y-%m-%d>.org" + :target (file+head "%<%Y-%m-%d>.org" "#+title: %<%Y-%m-%d>\n"))) "Capture templates for daily-notes in Org-roam. Note that for daily files to show up in the calendar, they have to be of format @@ -92,7 +92,7 @@ See `org-roam-capture-templates' for the template documentation." (function :tag "Template function"))) (plist :inline t ;; Give the most common options as checkboxes - :options (((const :format "%v " :if-new) + :options (((const :format "%v " :target) (choice :tag "Node location" (list :tag "File" (const :format "" file) diff --git a/extensions/org-roam-protocol.el b/extensions/org-roam-protocol.el index e4c8bf8..bb58487 100644 --- a/extensions/org-roam-protocol.el +++ b/extensions/org-roam-protocol.el @@ -48,7 +48,7 @@ (defcustom org-roam-capture-ref-templates '(("r" "ref" plain "%?" - :if-new (file+head "${slug}.org" + :target (file+head "${slug}.org" "#+title: ${title}") :unnarrowed t)) "The Org-roam templates used during a capture from the roam-ref protocol. @@ -77,7 +77,7 @@ See `org-roam-capture-templates' for the template documentation." (function :tag "Template function"))) (plist :inline t ;; Give the most common options as checkboxes - :options (((const :format "%v " :if-new) + :options (((const :format "%v " :target) (choice :tag "Node location" (list :tag "File" (const :format "" file) diff --git a/org-roam-capture.el b/org-roam-capture.el index 78045b7..edbe339 100644 --- a/org-roam-capture.el +++ b/org-roam-capture.el @@ -40,7 +40,7 @@ ;;; Options (defcustom org-roam-capture-templates '(("d" "default" plain "%?" - :if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org" + :target (file+head "%<%Y%m%d%H%M%S>-${slug}.org" "#+title: ${title}\n") :unnarrowed t)) "Templates for the creation of new entries within Org-roam. @@ -92,30 +92,41 @@ template The template for creating the capture item. in order to get a template from a file, or dynamically from a function. -The template contains a compulsory :if-new property. This determines the -location of the new node. The :if-new property contains a list, supporting -the following options: +The template contains a compulsory :target property. The :target property +contains a list, where: + - The first element indicates the type of the target. + - The second element indicates the location of the captured node. + - And the rest of the list indicate the prefilled template, that will be + inserted and the position of the point will be adjusted for. + This behavior various from type to type. + +The following options are supported for the :target property: (file \"path/to/file\") The file will be created, and prescribed an ID. (file+head \"path/to/file\" \"head content\") The file will be created, prescribed an ID, and head content will be - inserted into the file. + inserted if the node is a newly captured one. (file+olp \"path/to/file\" (\"h1\" \"h2\")) - The file will be created, prescribed an ID. The OLP (h1, h2) will be - created, and the point placed after. + The file will be created, prescribed an ID. If the file doesn't contain + the outline path (h1, h2), it will be automatically created. The point + will be adjusted to the last element in the OLP. (file+head+olp \"path/to/file\" \"head content\" (\"h1\" \"h2\")) The file will be created, prescribed an ID. Head content will be - inserted at the start of the file. The OLP (h1, h2) will be created, - and the point placed after. + inserted at the start of the file if the node is a newly captured one. + If the file doesn't contain the outline path (h1, h2), it will be + automatically created. The point will be adjusted to the last element in + the OLP. - (file+datetree \"path/to/file\" day) - The file will be created, prescribed an ID. Head content will be - inserted at the start of the file. The datetree will be created, - available options are day, week, month. + (file+datetree \"path/to/file\" tree-type) + The file will be created, prescribed an ID. A date based outline path + will be created for today's date. The tree-type can be one of the + following symbols: day, week or month. The point will adjusted to the + last element in the tree. To prompt for date instead of using today's, + use the :time-prompt property. (node \"title or alias or ID of an existing node\") The point will be placed for an existing node, based on either, its @@ -289,7 +300,7 @@ streamlined user experience in Org-roam." (function :tag "Template function"))) (plist :inline t ;; Give the most common options as checkboxes - :options (((const :format "%v " :if-new) + :options (((const :format "%v " :target) (choice :tag "Node location" (list :tag "File" (const :format "" file) @@ -377,7 +388,7 @@ during the Org-roam capture process.") This variable is populated dynamically, and is only non-nil during the Org-roam capture process.") -(defconst org-roam-capture--template-keywords (list :if-new :id :link-description :call-location +(defconst org-roam-capture--template-keywords (list :target :id :link-description :call-location :region) "Keywords used in `org-roam-capture-templates' specific to Org-roam.") @@ -445,8 +456,9 @@ the capture)." (defun org-roam-capture--prepare-buffer () "Prepare the capture buffer for the current Org-roam based capture template. This function will initialize and setup the capture buffer, -create the target node (`:if-new') if it doesn't exist, and place -the point for further processing by `org-capture'. +position the point to the current :target (and if necessary, +create it if it doesn't exist), and place the point for further +processing by `org-capture'. Note: During the capture process this function is run by `org-capture-set-target-location', as a (function ...) based @@ -464,8 +476,7 @@ capture target." "Initialize the buffer, and goto the location of the new capture. Return the ID of the location." (let (p new-file-p) - (pcase (or (org-roam-capture--get :if-new) - (user-error "Template needs to specify `:if-new'")) + (pcase (org-roam-capture--get-target) (`(file ,path) (setq path (org-roam-capture--target-truepath path) new-file-p (org-roam-capture--new-file-p path)) @@ -564,6 +575,11 @@ Return the ID of the location." (org-id-get-create) (run-hooks 'org-roam-capture-new-node-hook))))) +(defun org-roam-capture--get-target () + "Get the current capture :target for the capture template in use." + (or (org-roam-capture--get :target) + (user-error "Template needs to specify `:target'"))) + (defun org-roam-capture--target-truepath (path) "From PATH get the correct path to the current capture target and return it. PATH is a string that can optionally contain templated text in diff --git a/org-roam-compat.el b/org-roam-compat.el index a976e08..62fce91 100644 --- a/org-roam-compat.el +++ b/org-roam-compat.el @@ -153,6 +153,29 @@ nodes." org-id-locations-file) (expand-file-name ".orgids" (file-truename org-roam-directory))) (apply fn args))))))) +(with-eval-after-load 'org-roam-capture + ;; :if-new capture template property is deprecated in favor of :target + (add-to-list 'org-roam-capture--template-keywords :if-new) + + (advice-add 'org-roam-capture--get-target :around #'org-roam-capture--get-if-new-target-a) + (let ((warning-was-displayed 'dont-display)) ; REVIEW Set this to nil close to next major release + (defun org-roam-capture--get-if-new-target-a (fn &rest args) + "Get the current capture target using deprecated :if-new property." + (if-let ((target (org-roam-capture--get :if-new))) + (prog1 target + (unless warning-was-displayed + (lwarn 'org-roam-capture :warning + (mapconcat + #'identity + ["`:if-new' property is deprecated in favor of `:target'." + "This warning will popup once per each session. In order to get" + "rid of it, rename all the references to the `:if-new' property" + "in your capture templates to `:target'."] + "\n")) + ;; Don't irritate the user too much. Displaying the warning once per session should be enough. + (setq warning-was-displayed t))) + (apply fn args))))) + ;;; Obsolete aliases (remove after next major release) (define-obsolete-function-alias 'org-roam-setup