Next: , Previous: Tables in arbitrary syntax, Up: Hacking

A.7 Dynamic blocks

Org supports dynamic blocks in Org documents. They are inserted with begin and end markers like any other ‘src’ code block, but the contents are updated automatically by a user function. For example, C-c C-x C-r inserts a dynamic table that updates the work time (see Clocking work time).

Dynamic blocks can have names and function parameters. The syntax is similar to ‘src’ code block specifications:

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

These command update dynamic blocks:

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.

Before updating a dynamic block, Org removes content between the BEGIN and END markers. Org then reads the parameters on the BEGIN line for passing to the writer function. If the function expects to access the removed content, then Org expects an extra parameter, :content, on the BEGIN line.

To syntax for calling a writer function with a named block, myblock is: org-dblock-write:myblock. Parameters come from the BEGIN line.

The following is an example of a dynamic block and a block writer function that updates the time when the function was last run:

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

The dynamic block's writer function:

     (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))))

To keep dynamic blocks up-to-date in an Org file, use the function, org-update-all-dblocks in hook, such as before-save-hook. The org-update-all-dblocks function does not run if the file is not in Org mode.

Dynamic blocks, like any other block, can be narrowed with org-narrow-to-block.