org-hooks.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TITLE:      List of org-mode hooks - examples of use
   5 #+AUTHOR:     Worg people
   6 #+EMAIL:      bzg AT altern DOT org
   7 #+LANGUAGE:   en
   8 #+PRIORITIES: A C B
   9 #+CATEGORY:   worg
  10
  11 # This file is the default header for new Org files in Worg.  Feel free
  12 # to tailor it to your needs.
  13
  14 [[file:index.org][{Back to Worg's index}]]
  15
  16 This is the list of Org-mode hooks and function variables, with their
  17 documentation strings:
  18
  19 * Hooks and Function variables
  20
  21 ** =org-load-hook=
  22 Defined in: /org.el/
  23 #+begin_example
  24     Hook that is run after org.el has been loaded.
  25 #+end_example
  26 ** =org-cycle-hook=
  27 Defined in: /org.el/
  28 #+begin_example
  29     Hook that is run after `org-cycle' has changed the buffer visibility.
  30     The function(s) in this hook must accept a single argument which indicates
  31     the new state that was set by the most recent `org-cycle' command.  The
  32     argument is a symbol.  After a global state change, it can have the values
  33     `overview', `content', or `all'.  After a local state change, it can have
  34     the values `folded', `children', or `subtree'.
  35 #+end_example
  36 ** =org-insert-heading-hook=
  37 Defined in: /org.el/
  38 #+begin_example
  39     Hook being run after inserting a new heading.
  40 #+end_example
  41 ** =org-occur-hook=
  42 Defined in: /org.el/
  43 #+begin_example
  44     Hook that is run after `org-occur' has constructed a sparse tree.
  45     This can be used to recenter the window to show as much of the structure
  46     as possible.
  47 #+end_example
  48 ** =org-make-link-description-function=
  49 Defined in: /org.el/
  50 #+begin_example
  51     Function to use to generate link descriptions from links. If
  52     nil the link location will be used. This function must take two
  53     parameters; the first is the link and the second the description
  54     org-insert-link has generated, and should return the description
  55     to use.
  56 #+end_example
  57 ** =org-link-translation-function=
  58 Defined in: /org.el/
  59 #+begin_example
  60     Function to translate links with different syntax to Org syntax.
  61     This can be used to translate links created for example by the Planner
  62     or emacs-wiki packages to Org syntax.
  63     The function must accept two parameters, a TYPE containing the link
  64     protocol name like \"rmail\" or \"gnus\" as a string, and the linked path,
  65     which is everything after the link protocol.  It should return a cons
  66     with possibly modified values of type and path.
  67     Org contains a function for this, so if you set this variable to
  68     `org-translate-link-from-planner', you should be able follow many
  69     links created by planner.
  70 #+end_example
  71 ** =org-follow-link-hook=
  72 Defined in: /org.el/
  73 #+begin_example
  74     Hook that is run after a link has been followed.
  75 #+end_example
  76 ** =org-confirm-shell-link-function=
  77 Defined in: /org.el/
  78 #+begin_example
  79     Non-nil means, ask for confirmation before executing shell links.
  80     Shell links can be dangerous: just think about a link
  81
  82          [[shell:rm -rf ~/*][Google Search]]
  83
  84     This link would show up in your Org-mode document as \"Google Search\",
  85     but really it would remove your entire home directory.
  86     Therefore we advise against setting this variable to nil.
  87     Just change it to `y-or-n-p' of you want to confirm with a
  88     single keystroke rather than having to type \"yes\".
  89 #+end_example
  90 ** =org-confirm-elisp-link-function=
  91 Defined in: /org.el/
  92 #+begin_example
  93     Non-nil means, ask for confirmation before executing Emacs Lisp links.
  94     Elisp links can be dangerous: just think about a link
  95
  96          [[elisp:(shell-command \"rm -rf ~/*\")][Google Search]]
  97
  98     This link would show up in your Org-mode document as \"Google Search\",
  99     but really it would remove your entire home directory.
 100     Therefore we advise against setting this variable to nil.
 101     Just change it to `y-or-n-p' of you want to confirm with a
 102     single keystroke rather than having to type \"yes\".
 103 #+end_example
 104 ** =org-after-todo-state-change-hook=
 105 Defined in: /org.el/
 106 #+begin_example
 107     Hook which is run after the state of a TODO item was changed.
 108     The new state (a string with a TODO keyword, or nil) is available in the
 109     Lisp variable `state'.
 110 #+end_example
 111 ** =org-after-tags-change-hook=
 112 Defined in: /org.el/
 113 #+begin_example
 114     Hook that is run after the tags in a line have changed.
 115 #+end_example
 116 ** =org-columns-modify-value-for-display-function=
 117 Defined in: /org.el/
 118 #+begin_example
 119     Function that modifies values for display in column view.
 120     For example, it can be used to cut out a certain part from a time stamp.
 121     The function must take 2 arguments:
 122
 123     column-title    The title of the column (*not* the property name)
 124     value           The value that should be modified.
 125
 126     The function should return the value that should be displayed,
 127     or nil if the normal value should be used.
 128 #+end_example
 129 ** =org-finish-function=
 130 Defined in: /org.el/
 131 #+begin_example
 132     Function to be called when `C-c C-c' is used.
 133     This is for getting out of special buffers like remember.
 134 #+end_example
 135 ** =org-mode-hook=
 136 Defined in: /org.el/
 137 #+begin_example
 138     Mode hook for Org-mode, run after the mode was turned on.
 139 #+end_example
 140 ** =org-font-lock-hook=
 141 Defined in: /org.el/
 142 #+begin_example
 143     Functions to be called for special font lock stuff.
 144 #+end_example
 145 ** =org-store-link-functions=
 146 Defined in: /org.el/
 147 #+begin_example
 148     List of functions that are called to create and store a link.
 149     Each function will be called in turn until one returns a non-nil
 150     value.  Each function should check if it is responsible for creating
 151     this link (for example by looking at the major mode).
 152     If not, it must exit and return nil.
 153     If yes, it should return a non-nil value after a calling
 154     `org-store-link-props' with a list of properties and values.
 155     Special properties are:
 156
 157     :type         The link prefix. like \"http\".  This must be given.
 158     :link         The link, like \"http://www.astro.uva.nl/~dominik\".
 159                   This is obligatory as well.
 160     :description  Optional default description for the second pair
 161                   of brackets in an Org-mode link.  The user can still change
 162                   this when inserting this link into an Org-mode buffer.
 163
 164     In addition to these, any additional properties can be specified
 165     and then used in remember templates.
 166 #+end_example
 167 ** =org-create-file-search-functions=
 168 Defined in: /org.el/
 169 #+begin_example
 170     List of functions to construct the right search string for a file link.
 171     These functions are called in turn with point at the location to
 172     which the link should point.
 173
 174     A function in the hook should first test if it would like to
 175     handle this file type, for example by checking the major-mode or
 176     the file extension.  If it decides not to handle this file, it
 177     should just return nil to give other functions a chance.  If it
 178     does handle the file, it must return the search string to be used
 179     when following the link.  The search string will be part of the
 180     file link, given after a double colon, and `org-open-at-point'
 181     will automatically search for it.  If special measures must be
 182     taken to make the search successful, another function should be
 183     added to the companion hook `org-execute-file-search-functions',
 184     which see.
 185
 186     A function in this hook may also use `setq' to set the variable
 187     `description' to provide a suggestion for the descriptive text to
 188     be used for this link when it gets inserted into an Org-mode
 189     buffer with \\[org-insert-link].
 190 #+end_example
 191 ** =org-execute-file-search-functions=
 192 Defined in: /org.el/
 193 #+begin_example
 194     List of functions to execute a file search triggered by a link.
 195
 196     Functions added to this hook must accept a single argument, the
 197     search string that was part of the file link, the part after the
 198     double colon.  The function must first check if it would like to
 199     handle this search, for example by checking the major-mode or the
 200     file extension.  If it decides not to handle this search, it
 201     should just return nil to give other functions a chance.  If it
 202     does handle the search, it must return a non-nil value to keep
 203     other functions from trying.
 204
 205     Each function can access the current prefix argument through the
 206     variable `current-prefix-argument'.  Note that a single prefix is
 207     used to force opening a link in Emacs, so it may be good to only
 208     use a numeric or double prefix to guide the search function.
 209
 210     In case this is needed, a function in this hook can also restore
 211     the window configuration before `org-open-at-point' was called using:
 212
 213         (set-window-configuration org-window-config-before-follow-link)
 214 #+end_example
 215 ** =org-blocker-hook=
 216 Defined in: /org.el/
 217 #+begin_example
 218     Hook for functions that are allowed to block a state change.
 219
 220     Each function gets as its single argument a property list, see
 221     `org-trigger-hook' for more information about this list.
 222
 223     If any of the functions in this hook returns nil, the state change
 224     is blocked.
 225 #+end_example
 226 ** =org-trigger-hook=
 227 Defined in: /org.el/
 228 #+begin_example
 229     Hook for functions that are triggered by a state change.
 230
 231     Each function gets as its single argument a property list with at least
 232     the following elements:
 233
 234      (:type type-of-change :position pos-at-entry-start
 235       :from old-state :to new-state)
 236
 237     Depending on the type, more properties may be present.
 238
 239     This mechanism is currently implemented for:
 240
 241     TODO state changes
 242     ------------------
 243     :type  todo-state-change
 244     :from  previous state (keyword as a string), or nil
 245     :to    new state (keyword as a string), or nil
 246 #+end_example
 247 ** =org-after-todo-statistics-hook=
 248 Defined in: /org.el/
 249 #+begin_example
 250     Hook that is called after a TODO statistics cookie has been updated.
 251     Each function is called with two arguments: the number of not-done entries
 252     and the number of done entries.
 253
 254     For example, the following function, when added to this hook, will switch
 255     an entry to DONE when all children are done, and back to TODO when new
 256     entries are set to a TODO status.  Note that this hook is only called
 257     when there is a statistics cookie in the headline!
 258
 259      (defun org-summary-todo (n-done n-not-done)
 260        \"Switch entry to DONE when all subentries are done, to TODO otherwise.\"
 261        (let (org-log-done org-log-states)   ; turn off logging
 262          (org-todo (if (= n-not-done 0) \"DONE\" \"TODO\"))))
 263 #+end_example
 264 ** =org-finalize-agenda-hook=
 265 Defined in: /org-agenda.el/
 266 #+begin_example
 267     Hook run just before displaying an agenda buffer.
 268 #+end_example
 269 ** =org-agenda-mode-hook=
 270 Defined in: /org-agenda.el/
 271 #+begin_example
 272     Hook for org-agenda-mode, run after the mode is turned on.
 273 #+end_example
 274 ** =org-agenda-skip-function=
 275 Defined in: /org-agenda.el/
 276 #+begin_example
 277     Function to be called at each match during agenda construction.
 278     If this function returns nil, the current match should not be skipped.
 279     Otherwise, the function must return a position from where the search
 280     should be continued.
 281     This may also be a Lisp form, it will be evaluated.
 282     Never set this variable using `setq' or so, because then it will apply
 283     to all future agenda commands.  Instead, bind it with `let' to scope
 284     it dynamically into the agenda-constructing command.  A good way to set
 285     it is through options in org-agenda-custom-commands.
 286 #+end_example
 287 ** =org-agenda-after-show-hook=
 288 Defined in: /org-agenda.el/
 289 #+begin_example
 290     Normal hook run after an item has been shown from the agenda.
 291     Point is in the buffer where the item originated.
 292 #+end_example
 293 ** =org-clock-heading-function=
 294 Defined in: /org-clock.el/
 295 #+begin_example
 296     When non-nil, should be a function to create `org-clock-heading'.
 297     This is the string shown in the mode line when a clock is running.
 298     The function is called with point at the beginning of the headline.
 299 #+end_example
 300 ** =org-export-preprocess-hook=
 301 Defined in: /org-exp.el/
 302 #+begin_example
 303     Hook for preprocessing an export buffer.
 304     Pretty much the first thing when exporting is running this hook.
 305 #+end_example
 306 ** =org-export-preprocess-after-include-files-hook=
 307 Defined in: /org-exp.el/
 308 #+begin_example
 309     Hook for preprocessing an export buffer.
 310     This is run after the contents of included files have been inserted.
 311 #+end_example
 312 ** =org-export-preprocess-after-tree-selection-hook=
 313 Defined in: /org-exp.el/
 314 #+begin_example
 315     Hook for preprocessing an export buffer.
 316     This is run after selection of trees to be exported has happened.
 317     This selection includes tags-based selection, as well as removal
 318     of commented and archived trees.
 319 #+end_example
 320 ** =org-export-preprocess-before-backend-specifics-hook=
 321 Defined in: /org-exp.el/
 322 #+begin_example
 323     Hook run before backend-specific functions are called during preprocessing.
 324 #+end_example
 325 ** =org-export-preprocess-final-hook=
 326 Defined in: /org-exp.el/
 327 #+begin_example
 328     Hook for preprocessing an export buffer.
 329     This is run as the last thing in the preprocessing buffer, just before
 330     returning the buffer string to the backend.
 331 #+end_example
 332 ** =org-before-save-iCalendar-file-hook=
 333 Defined in: /org-exp.el/
 334 #+begin_example
 335     Hook run before  an iCalendar file has been saved.
 336     This can be used to modify the result of the export.
 337 #+end_example
 338 ** =org-after-save-iCalendar-file-hook=
 339 Defined in: /org-exp.el/
 340 #+begin_example
 341     Hook run after an iCalendar file has been saved.
 342     The iCalendar buffer is still current when this hook is run.
 343     A good way to use this is to tell a desktop calendar application to re-read
 344     the iCalendar file.
 345 #+end_example
 346 ** =org-mouse-context-menu-function=
 347 Defined in: /org-mouse.el/
 348 #+begin_example
 349     Function to create the context menu.
 350     The value of this variable is the function invoked by
 351     `org-mouse-context-menu' as the context menu.
 352 #+end_example
 353 ** =org-publish-before-export-hook=
 354 Defined in: /org-publish.el/
 355 #+begin_example
 356     Hook run before export on the Org file.
 357     If the functions in this hook modify the original Org buffer, the
 358     modified buffer will be used for export, but the buffer will be
 359     restored and saved back to its initial state after export.
 360 #+end_example
 361 ** =org-publish-after-export-hook=
 362 Defined in: /org-publish.el/
 363 #+begin_example
 364     Hook run after export on the exported buffer.
 365     If functions in this hook modify the buffer, it will be saved.
 366 #+end_example
 367 ** =org-remember-before-finalize-hook=
 368 Defined in: /org-remember.el/
 369 #+begin_example
 370     Hook that is run right before a remember process is finalized.
 371     The remember buffer is still current when this hook runs.
 372 #+end_example
 373 ** =org-remember-mode-hook=
 374 Defined in: /org-remember.el/
 375 #+begin_example
 376     Hook for the minor `org-remember-mode'.
 377 #+end_example
 378 * Examples for using hooks
 379
 380 Feel free to give example of how do you use these hooks.  Ideas for
 381 other hooks are also welcome.
 382
 383 ** org-follow-link-hook                                                 :bzg:
 384
 385 If  you want to display dormant article when following Gnus articles:
 386
 387 #+BEGIN_SRC emacs-lisp
 388 (add-hook 'org-follow-link-hook
 389           (lambda () (if (eq major-mode 'gnus-summary-mode)
 390                          (gnus-summary-insert-dormant-articles))))
 391 #+END_SRC
 392
 393 # org-add-hook?