- publishing free software manuals
The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
ISBN 9781906966089
RRP £9.95 ($14.95)

Sales of this book support the Org project! Get a printed copy>>>

16.16 Dynamic blocks

Org documents can contain dynamic blocks. These are specially marked regions that are updated by some user-written function. A good example for such a block is the clock table inserted by the command C-c C-x C-r (see section 8.4 Clocking work time).

Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name to the block and can also specify parameters for the function producing the content of the block.

#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...

#+END:

Dynamic blocks are updated with the following commands

C-c C-x C-u
Update dynamic block at point.
C-u C-c C-x C-u
Update all dynamic blocks in the current file.

Updating a dynamic block means to remove all the text between BEGIN and END, parse the BEGIN line for parameters and then call the specific writer function for this block to insert the new content. If you want to use the original content in the writer function, you can use the extra parameter :content.

For a block with name myblock, the writer function is org-dblock-write:myblock with as only parameter a property list with the parameters given in the begin line. Here is a trivial example of a block that keeps track of when the block update function was last run:

#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"

#+END:

The corresponding block writer function could look like this:

(defun org-dblock-write:block-update-time (params)
   (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
     (insert "Last block update at: "
             (format-time-string fmt (current-time)))))

If you want to make sure that all dynamic blocks are always up-to-date, you could add the function org-update-all-dblocks to a hook, for example before-save-hook. org-update-all-dblocks is written in a way such that it does nothing in buffers that are not in org-mode.

ISBN 9781906966089The Org Mode 7 Reference ManualSee the print edition