org: Template elements
9.1.3.1 Template elements
.........................
Now lets look at the elements of a template definition. Each entry in
‘org-capture-templates’ is a list with the following items:
KEYS
The keys that will select the template, as a string, characters
only, for example ‘"a"’ for a template to be selected with a single
key, or ‘"bt"’ for selection with two keys. When using several
keys, keys using the same prefix key must be sequential in the list
and preceded by a 2-element entry explaining the prefix key, for
example
("b" "Templates for marking stuff to buy")
If you do not define a template for the ‘C’ key, this key will be
used to open the customize buffer for this complex variable.
DESCRIPTION
A short string describing the template, which will be shown during
selection.
TYPE
The type of entry, a symbol. Valid values are:
‘entry’
An Org mode node, with a headline. Will be filed as the child
of the target entry or as a top-level entry. The target file
should be an Org mode file.
‘item’
A plain list item, placed in the first plain list at the
target location. Again the target file should be an Org file.
‘checkitem’
A checkbox item. This only differs from the plain list item
by the default template.
‘table-line’
a new line in the first table at the target location. Where
exactly the line will be inserted depends on the properties
‘:prepend’ and ‘:table-line-pos’ (see below).
‘plain’
Text to be inserted as it is.
TARGET
Specification of where the captured item should be placed. In Org
mode files, targets usually define a node. Entries will become
children of this node. Other types will be added to the table or
list in the body of this node. Most target specifications contain
a file name. If that file name is the empty string, it defaults to
‘org-default-notes-file’. A file can also be given as a variable,
function, or Emacs Lisp form.
Valid values are:
‘(file "path/to/file")’
Text will be placed at the beginning or end of that file.
‘(id "id of existing org entry")’
Filing as child of this entry, or in the body of the entry.
‘(file+headline "path/to/file" "node headline")’
Fast configuration if the target heading is unique in the
file.
‘(file+olp "path/to/file" "Level 1 heading" "Level 2" ...)’
For non-unique headings, the full path is safer.
‘(file+regexp "path/to/file" "regexp to find location")’
Use a regular expression to position the cursor.
‘(file+datetree "path/to/file")’
Will create a heading in a date tree for today’s date(1).
‘(file+datetree+prompt "path/to/file")’
Will create a heading in a date tree, but will prompt for the
date.
‘(file+function "path/to/file" function-finding-location)’
A function to find the right location in the file.
‘(clock)’
File to the entry that is currently being clocked.
‘(function function-finding-location)’
Most general way, write your own function to find both file
and location.
TEMPLATE
The template for creating the capture item. If you leave this
empty, an appropriate default template will be used. Otherwise
this is a string with escape codes, which will be replaced
depending on time and context of the capture call. The string with
escapes may be loaded from a template file, using the special
syntax ‘(file "path/to/template")’. See below for more details.
PROPERTIES
The rest of the entry is a property list of additional options.
Recognized properties are:
‘:prepend’
Normally new 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.
‘:empty-lines’
Set this to the number of lines to insert before and after the
new item. Default 0, only common other value is 1.
‘:clock-in’
Start the clock in this item.
‘:clock-keep’
Keep the clock running when filing the captured entry.
‘:clock-resume’
If starting the capture interrupted a clock, restart that
clock when finished with 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.
‘:unnarrowed’
Do not narrow the target buffer, simply show the full buffer.
Default is to narrow it so that you only see the new material.
‘: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 when capture was
invoked, kill the buffer again after capture is completed.
---------- Footnotes ----------
(1) Datetree headlines for years accept tags, so if you use both ‘*
2013 :noexport:’ and ‘* 2013’ in your file, the capture will refile the
note to the first one matched.
Info Catalog
org: Capture templates
org: Capture templates
org: Template expansion