From 780194a5af6a8a6c7fbb602e834dcbec78016070 Mon Sep 17 00:00:00 2001
From: Nicholas Vollmer <iarchivedmywholelife@gmail.com>
Date: Tue, 27 Sep 2022 05:44:33 -0400
Subject: [PATCH] org-capture: Add template hook properties

* lisp/org-capture.el (org-capture-templates): Document template hook properties.
(org-capture-finalize): execute :prepare/:before/:after-finalize functions.
(org-capture-place-template): execute :hook functions.

* doc/org-manual.org Document template hook properties.
---
 doc/org-manual.org  | 20 ++++++++++++++++++++
 lisp/org-capture.el | 29 +++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index ab8a295e5..c1321f6cd 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -7838,6 +7838,26 @@ Now lets look at the elements of a template definition.  Each entry in
   - ~:refile-targets :: Temporarily set ~org-refile-targets~ to the
     value of this property.
 
+  - ~:hook~ ::
+
+    A function or list of functions run before `org-capture-mode-hook'
+    when the template is selected.
+
+ - ~:prepare-finalize~ ::
+
+    A function or list of functions run before `org-capture-prepare-finalize-hook'
+    when the template is selected.
+
+ - ~:before-finalize~ ::
+
+    A function or list of functions run before `org-capture-before-finalize-hook'
+    when the template is selected.
+
+ - ~:after-finalize~ ::
+
+    A function or list of functions run before `org-capture-after-finalize-hook'
+    when the template is selected.
+
 **** Template expansion
 :PROPERTIES:
 :DESCRIPTION: Filling in information about time and context.
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 428d0ac0e..e5528a849 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -297,6 +297,21 @@ properties are:
 
  :no-save            Do not save the target file after finishing the capture.
 
+ :hook               A function or list of functions run before
+                     `org-capture-mode-hook' when the template is selected.
+
+ :prepare-finalize   A function or list of functions run before
+                     `org-capture-prepare-finalize-hook'
+                     when the template is selected.
+
+ :before-finalize    A function or list of functions run before
+                     `org-capture-before-finalize-hook'
+                     when the template is selected.
+
+ :after-finalize     A function or list of functions run before
+                     `org-capture-after-finalize-hook'
+                     when the template is selected.
+
 The template defines the text to be inserted.  Often this is an
 Org mode entry (so the first line should start with a star) that
 will be filed as a child of the target headline.  It can also be
@@ -740,6 +755,14 @@ of the day at point (if any) or the current HH:MM time."
 	(format "* Template function %S not found" f)))
      (_ "* Invalid capture template"))))
 
+(defun org-capture--run-template-functions (keyword &optional local)
+  "Run template's KEYWORD functions.
+If LOCAL is non-nil use the buffer-local value of `org-capture-plist'."
+  (let ((value (org-capture-get keyword local)))
+    (if (functionp value)
+        (funcall value)
+      (mapc #'funcall value))))
+
 (defun org-capture-finalize (&optional stay-with-capture)
   "Finalize the capture process.
 With prefix argument STAY-WITH-CAPTURE, jump to the location of the
@@ -751,6 +774,7 @@ captured item after finalizing."
 	       (buffer-base-buffer (current-buffer)))
     (error "This does not seem to be a capture buffer for Org mode"))
 
+  (org-capture--run-template-functions :prepare-finalize t)
   (run-hooks 'org-capture-prepare-finalize-hook)
 
   ;; Update `org-capture-plist' with the buffer-local value.  Since
@@ -823,6 +847,7 @@ captured item after finalizing."
       ;; the indirect buffer has been killed.
       (org-capture-store-last-position)
 
+      (org-capture--run-template-functions :before-finalize t)
       ;; Run the hook
       (run-hooks 'org-capture-before-finalize-hook))
 
@@ -871,6 +896,9 @@ captured item after finalizing."
       ;; Restore the window configuration before capture
       (set-window-configuration return-wconf))
 
+    ;; Do not use the local arg to `org-capture-get' here.
+    ;; The buffer-local value has been stored on `org-capture-plist'.
+    (org-capture--run-template-functions :after-finalize)
     (run-hooks 'org-capture-after-finalize-hook)
     ;; Special cases
     (cond
@@ -1147,6 +1175,7 @@ may have been stored before."
     (`item (org-capture-place-item))
     (`checkitem (org-capture-place-item)))
   (setq-local org-capture-current-plist org-capture-plist)
+  (org-capture--run-template-functions :hook t)
   (org-capture-mode 1))
 
 (defun org-capture-place-entry ()
-- 
2.37.3