emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture
@ 2022-02-06 14:05 Valentin Herrmann
  2022-04-24  4:57 ` Ihor Radchenko
  2022-10-31  5:49 ` Ihor Radchenko
  0 siblings, 2 replies; 5+ messages in thread
From: Valentin Herrmann @ 2022-02-06 14:05 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: Valentin Herrmann

* lisp/org-capture.el:
(org-capture-templates): Document the new template options.
(org-capture-before-view-hook): Add new hook for parity with the
template options.
(org-capture): Implement the new template options.
(org-capture-finalize): Implement the new template options.
(org-capture-kill): Remove unneeded line.
* doc/org-manual.org (Template elements): Document the new template options

This change comes from my personal config, where I use e.g. the option
`:before-finalize-hook' to capture an task automatically, whenever I
capture using a certain template.
---
 doc/org-manual.org  |  21 ++++++++
 etc/ORG-NEWS        |  26 ++++++++++
 lisp/org-capture.el | 123 +++++++++++++++++++++++++++-----------------
 3 files changed, 124 insertions(+), 46 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 2c54fde87..5efc2d797 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -7817,6 +7817,27 @@ 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.
 
+  - ~:before-view-hook~ ::
+
+    Hook that is run right after the capture buffer is made current.
+    The buffer is still narrowed.
+
+  - ~:prepare-finalize-hook~ ::
+
+    Hook that is run before the finalization starts.
+    The capture buffer is current and still narrowed.
+
+  - ~:before-finalize-hook~ ::
+
+    Hook that is run right before a capture process is finalized.
+    The capture buffer is still current when this hook runs and it is
+    widened to the entire buffer.
+
+  - ~:after-finalize-hook~ ::
+
+    Hook that is run right after a capture process is finalized.
+    Suitable for window cleanup.
+
 **** Template expansion
 :PROPERTIES:
 :DESCRIPTION: Filling in information about time and context.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 5a94e737e..25441027f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -63,6 +63,32 @@ list of various table options (between brackets in LaTeX export),
 since certain tabular environments, such as longtblr of the
 tabularray LaTeX package, provides this structure.
 
+*** New hook =org-capture-before-view-hook= for =org-capture= before view
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:before-view-hook= for =org-capture=
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:prepare-finalize-hook= for =org-capture=
+
+Hook that is run before the finalization starts.
+The capture buffer is current and still narrowed.
+
+*** New option =:before-finalize-hook= for =org-capture=
+
+Hook that is run right before a capture process is finalized.
+The capture buffer is still current when this hook runs and it is
+widened to the entire buffer.
+
+*** New option =:after-finalize-hook= for =org-capture=
+
+Hook that is run right after a capture process is finalized.
+Suitable for window cleanup.
+
 ** New functions and changes in function arguments
 
 *** New function ~org-element-cache-map~ for quick mapping across Org elements
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 5195b785e..27dd72ef8 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -235,64 +235,77 @@ template     The template for creating the capture item.
 The rest of the entry is a property list of additional options.  Recognized
 properties are:
 
- :prepend            Normally newly captured information will be appended at
-                     the target location (last child, last table line,
-                     last list item...).  Setting this property will
-                     change that.
+ :prepend               Normally newly captured information will be appended at
+                        the target location (last child, last table line,
+                        last list item...).  Setting this property will
+                        change that.
 
- :immediate-finish   When set, do not offer to edit the information, just
-                     file it away immediately.  This makes sense if the
-                     template only needs information that can be added
-                     automatically.
+ :immediate-finish      When set, do not offer to edit the information, just
+                        file it away immediately.  This makes sense if the
+                        template only needs information that can be added
+                        automatically.
 
- :jump-to-captured   When set, jump to the captured entry when finished.
+ :jump-to-captured      When set, jump to the captured entry when finished.
 
- :refile-targets     When exiting capture mode via `org-capture-refile', the
-                     variable `org-refile-targets' will be temporarily bound
-                     to the value of this property.
+ :refile-targets        When exiting capture mode via `org-capture-refile', the
+                        variable `org-refile-targets' will be temporarily bound
+                        to the value of this property.
 
- :empty-lines        Set this to the number of lines that should be inserted
-                     before and after the new item.  Default 0, only common
-                     other value is 1.
+ :empty-lines           Set this to the number of lines that should be inserted
+                        before and after the new item.  Default 0, only common
+                        other value is 1.
 
- :empty-lines-before Set this to the number of lines that should be inserted
-                     before the new item.  Overrides :empty-lines for the
-                     number lines inserted before.
+ :empty-lines-before    Set this to the number of lines that should be inserted
+                        before the new item.  Overrides :empty-lines for the
+                        number lines inserted before.
 
- :empty-lines-after  Set this to the number of lines that should be inserted
-                     after the new item.  Overrides :empty-lines for the
-                     number of lines inserted after.
+ :empty-lines-after     Set this to the number of lines that should be inserted
+                        after the new item.  Overrides :empty-lines for the
+                        number of lines inserted after.
 
- :clock-in           Start the clock in this item.
+ :clock-in              Start the clock in this item.
 
- :clock-keep         Keep the clock running when filing the captured entry.
+ :clock-keep            Keep the clock running when filing the captured entry.
 
- :clock-resume       Start the interrupted clock when finishing the capture.
-                     Note that :clock-keep has precedence over :clock-resume.
-                     When setting both to t, the current clock will run and
-                     the previous one will not be resumed.
+ :clock-resume          Start the interrupted clock when finishing the capture.
+                        Note that :clock-keep has precedence over :clock-resume.
+                        When setting both to t, the current clock will run and
+                        the previous one will not be resumed.
 
- :time-prompt        Prompt for a date/time to be used for date/week trees
-                     and when filling the template.
+ :time-prompt           Prompt for a date/time to be used for date/week trees
+                        and when filling the template.
 
- :tree-type          When `week', make a week tree instead of the month-day
-                     tree.  When `month', make a month tree instead of the
-                     month-day tree.
+ :tree-type             When `week', make a week tree instead of the month-day
+                        tree.  When `month', make a month tree instead of the
+                        month-day tree.
 
- :unnarrowed         Do not narrow the target buffer, simply show the
-                     full buffer.  Default is to narrow it so that you
-                     only see the new stuff.
+ :unnarrowed            Do not narrow the target buffer, simply show the
+                        full buffer.  Default is to narrow it so that you
+                        only see the new stuff.
 
- :table-line-pos     Specification of the location in the table where the
-                     new line should be inserted.  It should be a string like
-                     \"II-3\", meaning that the new line should become the
-                     third line before the second horizontal separator line.
+ :table-line-pos        Specification of the location in the table where the
+                        new line should be inserted.  It should be a string like
+                        \"II-3\", meaning that the new line should become the
+                        third line before the second horizontal separator line.
 
- :kill-buffer        If the target file was not yet visited by a buffer when
-                     capture was invoked, kill the buffer again after capture
-                     is finalized.
+ :kill-buffer           If the target file was not yet visited by a buffer when
+                        capture was invoked, kill the buffer again after capture
+                        is finalized.
 
- :no-save            Do not save the target file after finishing the capture.
+ :no-save               Do not save the target file after finishing the capture.
+
+ :before-view-hook      Hook that is run right after the capture buffer is made current.
+                        The buffer is still narrowed.
+
+ :prepare-finalize-hook Hook that is run before the finalization starts.
+                        The capture buffer is current and still narrowed.
+
+ :before-finalize-hook  Hook that is run right before a capture process is finalized.
+                        The capture buffer is still current when this hook runs and it is
+                        widened to the entire buffer.
+
+ :after-finalize-hook   Hook that is run right after a capture process is finalized.
+                        Suitable for window cleanup.
 
 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
@@ -476,6 +489,13 @@ The capture buffer is current and still narrowed."
   :version "24.1"
   :type 'hook)
 
+(defcustom org-capture-before-view-hook nil
+  "Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed."
+  :group 'org-capture
+  :version "28.1"
+  :type 'hook)
+
 (defcustom org-capture-bookmark t
   "When non-nil, add bookmark pointing at the last stored position when capturing."
   :group 'org-capture
@@ -705,6 +725,10 @@ of the day at point (if any) or the current HH:MM time."
 	   (error "Capture template `%s': %s"
 		  (org-capture-get :key)
 		  (error-message-string error))))
+
+        (run-hooks 'org-capture-before-view-hook)
+        (if-let ((bvh (org-capture-get :before-view-hook)))
+            (funcall bvh))
 	(when (and (derived-mode-p 'org-mode) (org-capture-get :clock-in))
 	  (condition-case nil
 	      (progn
@@ -745,6 +769,8 @@ captured item after finalizing."
     (error "This does not seem to be a capture buffer for Org mode"))
 
   (run-hooks 'org-capture-prepare-finalize-hook)
+  (when-let ((pfh (org-capture-get :prepare-finalize-hook)))
+    (funcall pfh))
 
   ;; Update `org-capture-plist' with the buffer-local value.  Since
   ;; captures can be run concurrently, this is to ensure that
@@ -817,7 +843,11 @@ captured item after finalizing."
       (org-capture-store-last-position)
 
       ;; Run the hook
-      (run-hooks 'org-capture-before-finalize-hook))
+      (unless org-note-abort
+        (run-hooks 'org-capture-before-finalize-hook)
+
+        (when-let ((bfh (org-capture-get :before-finalize-hook)))
+          (funcall bfh))))
 
     (when (org-capture-get :decrypted)
       (save-excursion
@@ -865,6 +895,8 @@ captured item after finalizing."
       (set-window-configuration return-wconf))
 
     (run-hooks 'org-capture-after-finalize-hook)
+    (when-let ((afh (org-capture-get :after-finalize-hook)))
+      (funcall afh))
     ;; Special cases
     (cond
      (abort-note
@@ -918,8 +950,7 @@ for `entry'-type templates"))
   (interactive)
   ;; FIXME: This does not do the right thing, we need to remove the
   ;; new stuff by hand it is easy: undo, then kill the buffer
-  (let ((org-note-abort t)
-	(org-capture-before-finalize-hook nil))
+  (let ((org-note-abort t))
     (org-capture-finalize)))
 
 (defun org-capture-goto-last-stored ()
-- 
2.33.1



^ permalink raw reply related	[flat|nested] 5+ messages in thread
* [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture
@ 2022-02-06  9:22 Valentin Herrmann
  2022-10-31  5:50 ` Ihor Radchenko
  0 siblings, 1 reply; 5+ messages in thread
From: Valentin Herrmann @ 2022-02-06  9:22 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: Valentin Herrmann

* lisp/org-capture.el:
(org-capture-templates): Document the new template options.
(org-capture-before-view-hook): Add new hook for parity with the
template options.
(org-capture): Implement the new template options.
(org-capture-finalize): Implement the new template options.
(org-capture-kill): Remove unneeded line.
* doc/org-manual.org (Template elements): Document the new template options

This change comes from my personal config, where I use e.g. the option
`:before-finalize-hook' to capture an task automatically, whenever I
capture using a certain template.
---
 doc/org-manual.org  |  21 ++++++++
 etc/ORG-NEWS        |  26 ++++++++++
 lisp/org-capture.el | 123 +++++++++++++++++++++++++++-----------------
 3 files changed, 124 insertions(+), 46 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 2c54fde87..5efc2d797 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -7817,6 +7817,27 @@ 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.
 
+  - ~:before-view-hook~ ::
+
+    Hook that is run right after the capture buffer is made current.
+    The buffer is still narrowed.
+
+  - ~:prepare-finalize-hook~ ::
+
+    Hook that is run before the finalization starts.
+    The capture buffer is current and still narrowed.
+
+  - ~:before-finalize-hook~ ::
+
+    Hook that is run right before a capture process is finalized.
+    The capture buffer is still current when this hook runs and it is
+    widened to the entire buffer.
+
+  - ~:after-finalize-hook~ ::
+
+    Hook that is run right after a capture process is finalized.
+    Suitable for window cleanup.
+
 **** Template expansion
 :PROPERTIES:
 :DESCRIPTION: Filling in information about time and context.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 5a94e737e..25441027f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -63,6 +63,32 @@ list of various table options (between brackets in LaTeX export),
 since certain tabular environments, such as longtblr of the
 tabularray LaTeX package, provides this structure.
 
+*** New hook =org-capture-before-view-hook= for =org-capture= before view
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:before-view-hook= for =org-capture=
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:prepare-finalize-hook= for =org-capture=
+
+Hook that is run before the finalization starts.
+The capture buffer is current and still narrowed.
+
+*** New option =:before-finalize-hook= for =org-capture=
+
+Hook that is run right before a capture process is finalized.
+The capture buffer is still current when this hook runs and it is
+widened to the entire buffer.
+
+*** New option =:after-finalize-hook= for =org-capture=
+
+Hook that is run right after a capture process is finalized.
+Suitable for window cleanup.
+
 ** New functions and changes in function arguments
 
 *** New function ~org-element-cache-map~ for quick mapping across Org elements
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 5195b785e..27dd72ef8 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -235,64 +235,77 @@ template     The template for creating the capture item.
 The rest of the entry is a property list of additional options.  Recognized
 properties are:
 
- :prepend            Normally newly captured information will be appended at
-                     the target location (last child, last table line,
-                     last list item...).  Setting this property will
-                     change that.
+ :prepend               Normally newly captured information will be appended at
+                        the target location (last child, last table line,
+                        last list item...).  Setting this property will
+                        change that.
 
- :immediate-finish   When set, do not offer to edit the information, just
-                     file it away immediately.  This makes sense if the
-                     template only needs information that can be added
-                     automatically.
+ :immediate-finish      When set, do not offer to edit the information, just
+                        file it away immediately.  This makes sense if the
+                        template only needs information that can be added
+                        automatically.
 
- :jump-to-captured   When set, jump to the captured entry when finished.
+ :jump-to-captured      When set, jump to the captured entry when finished.
 
- :refile-targets     When exiting capture mode via `org-capture-refile', the
-                     variable `org-refile-targets' will be temporarily bound
-                     to the value of this property.
+ :refile-targets        When exiting capture mode via `org-capture-refile', the
+                        variable `org-refile-targets' will be temporarily bound
+                        to the value of this property.
 
- :empty-lines        Set this to the number of lines that should be inserted
-                     before and after the new item.  Default 0, only common
-                     other value is 1.
+ :empty-lines           Set this to the number of lines that should be inserted
+                        before and after the new item.  Default 0, only common
+                        other value is 1.
 
- :empty-lines-before Set this to the number of lines that should be inserted
-                     before the new item.  Overrides :empty-lines for the
-                     number lines inserted before.
+ :empty-lines-before    Set this to the number of lines that should be inserted
+                        before the new item.  Overrides :empty-lines for the
+                        number lines inserted before.
 
- :empty-lines-after  Set this to the number of lines that should be inserted
-                     after the new item.  Overrides :empty-lines for the
-                     number of lines inserted after.
+ :empty-lines-after     Set this to the number of lines that should be inserted
+                        after the new item.  Overrides :empty-lines for the
+                        number of lines inserted after.
 
- :clock-in           Start the clock in this item.
+ :clock-in              Start the clock in this item.
 
- :clock-keep         Keep the clock running when filing the captured entry.
+ :clock-keep            Keep the clock running when filing the captured entry.
 
- :clock-resume       Start the interrupted clock when finishing the capture.
-                     Note that :clock-keep has precedence over :clock-resume.
-                     When setting both to t, the current clock will run and
-                     the previous one will not be resumed.
+ :clock-resume          Start the interrupted clock when finishing the capture.
+                        Note that :clock-keep has precedence over :clock-resume.
+                        When setting both to t, the current clock will run and
+                        the previous one will not be resumed.
 
- :time-prompt        Prompt for a date/time to be used for date/week trees
-                     and when filling the template.
+ :time-prompt           Prompt for a date/time to be used for date/week trees
+                        and when filling the template.
 
- :tree-type          When `week', make a week tree instead of the month-day
-                     tree.  When `month', make a month tree instead of the
-                     month-day tree.
+ :tree-type             When `week', make a week tree instead of the month-day
+                        tree.  When `month', make a month tree instead of the
+                        month-day tree.
 
- :unnarrowed         Do not narrow the target buffer, simply show the
-                     full buffer.  Default is to narrow it so that you
-                     only see the new stuff.
+ :unnarrowed            Do not narrow the target buffer, simply show the
+                        full buffer.  Default is to narrow it so that you
+                        only see the new stuff.
 
- :table-line-pos     Specification of the location in the table where the
-                     new line should be inserted.  It should be a string like
-                     \"II-3\", meaning that the new line should become the
-                     third line before the second horizontal separator line.
+ :table-line-pos        Specification of the location in the table where the
+                        new line should be inserted.  It should be a string like
+                        \"II-3\", meaning that the new line should become the
+                        third line before the second horizontal separator line.
 
- :kill-buffer        If the target file was not yet visited by a buffer when
-                     capture was invoked, kill the buffer again after capture
-                     is finalized.
+ :kill-buffer           If the target file was not yet visited by a buffer when
+                        capture was invoked, kill the buffer again after capture
+                        is finalized.
 
- :no-save            Do not save the target file after finishing the capture.
+ :no-save               Do not save the target file after finishing the capture.
+
+ :before-view-hook      Hook that is run right after the capture buffer is made current.
+                        The buffer is still narrowed.
+
+ :prepare-finalize-hook Hook that is run before the finalization starts.
+                        The capture buffer is current and still narrowed.
+
+ :before-finalize-hook  Hook that is run right before a capture process is finalized.
+                        The capture buffer is still current when this hook runs and it is
+                        widened to the entire buffer.
+
+ :after-finalize-hook   Hook that is run right after a capture process is finalized.
+                        Suitable for window cleanup.
 
 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
@@ -476,6 +489,13 @@ The capture buffer is current and still narrowed."
   :version "24.1"
   :type 'hook)
 
+(defcustom org-capture-before-view-hook nil
+  "Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed."
+  :group 'org-capture
+  :version "28.1"
+  :type 'hook)
+
 (defcustom org-capture-bookmark t
   "When non-nil, add bookmark pointing at the last stored position when capturing."
   :group 'org-capture
@@ -705,6 +725,10 @@ of the day at point (if any) or the current HH:MM time."
 	   (error "Capture template `%s': %s"
 		  (org-capture-get :key)
 		  (error-message-string error))))
+
+        (run-hooks 'org-capture-before-view-hook)
+        (if-let ((bvh (org-capture-get :before-view-hook)))
+            (funcall bvh))
 	(when (and (derived-mode-p 'org-mode) (org-capture-get :clock-in))
 	  (condition-case nil
 	      (progn
@@ -745,6 +769,8 @@ captured item after finalizing."
     (error "This does not seem to be a capture buffer for Org mode"))
 
   (run-hooks 'org-capture-prepare-finalize-hook)
+  (when-let ((pfh (org-capture-get :prepare-finalize-hook)))
+    (funcall pfh))
 
   ;; Update `org-capture-plist' with the buffer-local value.  Since
   ;; captures can be run concurrently, this is to ensure that
@@ -817,7 +843,11 @@ captured item after finalizing."
       (org-capture-store-last-position)
 
       ;; Run the hook
-      (run-hooks 'org-capture-before-finalize-hook))
+      (unless org-note-abort
+        (run-hooks 'org-capture-before-finalize-hook)
+
+        (when-let ((bfh (org-capture-get :before-finalize-hook)))
+          (funcall bfh))))
 
     (when (org-capture-get :decrypted)
       (save-excursion
@@ -865,6 +895,8 @@ captured item after finalizing."
       (set-window-configuration return-wconf))
 
     (run-hooks 'org-capture-after-finalize-hook)
+    (when-let ((afh (org-capture-get :after-finalize-hook)))
+      (funcall afh))
     ;; Special cases
     (cond
      (abort-note
@@ -918,8 +950,7 @@ for `entry'-type templates"))
   (interactive)
   ;; FIXME: This does not do the right thing, we need to remove the
   ;; new stuff by hand it is easy: undo, then kill the buffer
-  (let ((org-note-abort t)
-	(org-capture-before-finalize-hook nil))
+  (let ((org-note-abort t))
     (org-capture-finalize)))
 
 (defun org-capture-goto-last-stored ()
-- 
2.33.1



^ permalink raw reply related	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2022-10-31  5:50 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-02-06 14:05 [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture Valentin Herrmann
2022-04-24  4:57 ` Ihor Radchenko
2022-10-31  5:49 ` Ihor Radchenko
  -- strict thread matches above, loose matches on Subject: below --
2022-02-06  9:22 Valentin Herrmann
2022-10-31  5:50 ` Ihor Radchenko

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).