A.7 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 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     (org-dblock-update)

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.

You can narrow the current buffer to the current dynamic block (like any other block) with org-narrow-to-block.