org-tutorials/org-column-view-tutorial.org

   1 #+TITLE:     Emacs Org's Column View
   2 #+AUTHOR:    Bastien Guerry
   3 #+EMAIL:     bzg@altern.org
   4 #+SEQ_TODO:  TODO DONE
   5 #+LANGUAGE:  en
   6 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   7
   8 [[file:../index.org][{Back to Worg's index}]]
   9
  10 A short introduction to Org's column view by [[mailto:bzg AT gnu.fr][Bastien Guerry]].
  11
  12 /Oct, 15th 2007/
  13
  14 Please check the [[file:org-column-screencast.org][screencast]] demonstrating some of the possibilities I'm
  15 discussing here.
  16
  17 Also note that the column view feature is not available for Org < 5.01,
  18 Hence this feature is not in Emacs 22.1 (which comes with Org 4.67c.)
  19 Since Org is actively developed, it's always a good idea to upgrade to
  20 the [[http://www.legito.net/#sec-2][latest version]].
  21
  22 * Introduction: the default column view
  23
  24 First press =C-c C-x C-c= to show the default column view.  It turns
  25 each outline item into a table row displaying some of its properties.
  26
  27 [[file:../images/thumbs/org-col-default-view.png][file:../images/thumbs/org-col-default-view.png]]
  28
  29 You can switch the column view /off/ and return to the normal view by
  30 pressing `q' while the cursor is on the highlighted entry -- but you
  31 can turn the column view /on/ from any location in the buffer.
  32
  33 The first headline is now a row of /browsable columns/ displaying
  34 properties. The first highlighted line of the buffer briefly tells you
  35 what property is displayed in each columns.  In this screenshot it
  36 reads:
  37
  38 : ITEM for the headline title
  39 :   T for the TODO keyword
  40 :   P for the priority cookie
  41 :   T for the tags
  42
  43 The default column only shows the item, the TODO state, the priority of
  44 the item and its tags, we will see later how to add other properties of
  45 your own.
  46
  47 This default setup is driven by the variable
  48 =org-columns-default-format=, which global value is:
  49
  50 : #+COLUMNS: %25ITEM %TODO %3PRIORITY %TAGS
  51
  52 | Element    | Description                                     |
  53 |------------+-------------------------------------------------|
  54 | %25ITEM    | display the item in a 25-characters-width field |
  55 | %TODO      | display the TODO state of the item              |
  56 | %3PRIORITY | display the priority in a 3-chars-width field   |
  57 | %TAGS      | display the tags of the entry                   |
  58
  59 * Slight customization of the default column view
  60
  61 Okay, so now we'd like to customize the column display.
  62
  63 For example, we'd like to change the /width/ of the "priority" field and
  64 the "tags" field in the column:
  65
  66 : #+COLUMNS: %25ITEM %5TODO %1PRIORITY %10TAGS
  67
  68 [[file:../images/thumbs/org-col-default-customized-view1.png][file:../images/thumbs/org-col-default-customized-view1.png]]
  69
  70
  71 The TODO field (=%5TODO=) is now 5 characters wide, whereas the priority
  72 and the tags fields are 1 and 10.
  73
  74 Now we'd like to change the /title/ of the columns.  For example -- and
  75 since we are such *hardworkers* -- each so-called item is in fact... a
  76 "task" :
  77
  78 : #+COLUMNS: %25ITEM(Task) %5TODO(To-do) %1PRIORITY %10TAGS
  79
  80 [[file:../images/thumbs/org-col-default-customized-view2.png][file:../images/thumbs/org-col-default-customized-view2.png]]
  81
  82 We also add a "To-do" label for displaying the TODO state for this
  83 entry.
  84
  85 * Displaying other properties
  86
  87 What if you want to display *other properties* in the column view? For
  88 example, we'd like to display the =SCHEDULED= property. Then we need to
  89 redefine the global #+COLUMNS option like this:
  90
  91 : #+COLUMNS: %30ITEM %10SCHEDULED %TODO %3PRIORITY %TAGS
  92
  93 Refresh your Org buffer to take this change into account, then =C-c C-x
  94 C-c= again on the entry.  The column now shows the =SCHEDULED= property.
  95
  96 [[file:../images/thumbs/org-col-default-customized-view3.png][file:../images/thumbs/org-col-default-customized-view3.png]]
  97
  98 : ** Exemple of outline item with a SCHEDULED property
  99 :    SCHEDULED: <2007-10-14 dim>
 100
 101 What is the list of available properties?  Here it is:
 102
 103 : ITEM         The content of the headline.
 104 : TODO         The TODO keyword of the entry.
 105 : TAGS         The tags defined directly in the headline.
 106 : ALLTAGS      All tags, including inherited ones.
 107 : PRIORITY     The priority of the entry, a string with a single letter.
 108 : DEADLINE     The deadline time string, without the angular brackets.
 109 : SCHEDULED    The scheduling time stamp, without the angular brackets.
 110
 111 These are all *special properties*, but of course you can define your
 112 own properties.
 113
 114 Before going to the rather complex stuff you can do with your own
 115 properties, we'd like to know how to use different column views for
 116 different subtrees.
 117
 118 * Defining a column format for a subtree
 119
 120 To define a colum view for a specific item, just add the special
 121 property =:COLUMNS:= to it:
 122
 123 : ** Top node for columns view
 124 :    :PROPERTIES:
 125 :    :COLUMNS:  %25ITEM %TAGS %PRIORITY %TODO
 126 :    :END:
 127
 128 This view will be used for the entry and its entire subtree -- unless
 129 some of its children has its own column view.
 130
 131 See for example this:
 132
 133 : ** Top node for columns view
 134 :    :PROPERTIES:
 135 :    :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
 136 :    :END:
 137 : *** TODO Example 1
 138 : *** TODO Example 2
 139 : *** DONE Example 3
 140
 141 [[file:../images/thumbs/org-col-default-customized-view4.png][file:../images/thumbs/org-col-default-customized-view4.png]]
 142
 143 Good.
 144
 145 But what if you suddenly prefer =%TAGS= to be at the right of =%TODO=?
 146 Put the cursor in the =%TAGS= field and press =M-<right>=, it will move
 147 the field to the right.
 148
 149 What if you want to make a field larger?  No problem.  Just go to that
 150 field and press `>' to widen the field (or `<' to narrow it.)
 151
 152 If you want to interactively define the column element of a property, go
 153 the its field and press `s'.
 154
 155 So now that we know how to customize the column view for each entry,
 156 it's time to play with user-defined properties.
 157
 158 * Adding summary-types for some properties
 159
 160 Let's define a new entry with its own column view and a few properties:
 161
 162 : ** My project
 163 :    :PROPERTIES:
 164 :    :COLUMNS:  %20ITEM %9Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
 165 :    :END:
 166
 167 [[file:../images/thumbs/org-col-default-customized-view5.png][file:../images/thumbs/org-col-default-customized-view5.png]]
 168
 169 Let's comment this a bit.
 170
 171 We have a =:COLUMNS:= property, defining the column view. It says:
 172
 173 | Element                  | Description                                     |
 174 |--------------------------+-------------------------------------------------|
 175 | %20ITEM                  | display the item (20 characters for this field) |
 176 | %9Approved(Approved?){X} | display the "Approved" property                 |
 177 | %Owner                   | display the "Owner" property                    |
 178 | %11Status                | display the "Status" property                   |
 179 | %10Time_Spent{:}         | display the "Time_spent" property               |
 180
 181 What are ={X}= and ={:}=?
 182
 183 It defines *summary-types*.
 184
 185 ={X}= means: display =[X]= if all entries have a =[X]= value for their
 186 "Approved" property (=[-]= or =[ ]= otherwise).
 187
 188 ={:}= means: display a summary of the time spend, by adding all the time
 189 values found in the property "Time_Spent".
 190
 191 Once you get the =:COLUMN:= property defined, you can interactively add
 192 any property with =C-c C-x p=.  It will prompt you for the name of the
 193 property, and offer default possible values depending on the =_ALL=
 194 friend of the property (if any) or on the values found in the buffer.
 195
 196 * Defining all the possible values for a property
 197
 198 Defining summary-types implies that you need to have a limited set of
 199 possible values for certain properties.
 200
 201 For example, the "Approved" value discussed above should take only two
 202 values: =[ ]= and =[X]=.
 203
 204 Same for the "Status" property: you might want to define only a few
 205 status like "In progress" "Not started yet" "Finished".
 206
 207 You can restrict the allowed values for any property using the =_ALL=
 208 suffix like this:
 209
 210 : ** My project
 211 :    :PROPERTIES:
 212 :    :COLUMNS:  %20ITEM %9Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
 213 :    :Owner_ALL:    Tammy Mark Karl Lisa Don
 214 :    :Status_ALL:   "In progress" "Not started yet" "Finished" ""
 215 :    :Approved_ALL: "[ ]" "[X]"
 216 :    :END:
 217
 218 : | Owner_ALL    | only accept Tammy Mark Karl Lisa Don                   |
 219 : | Status_ALL   | only accept "In progress" "Not started yet" "Finished" |
 220 : | Approved_ALL | only accept "[ ]" "[X]"                                |
 221
 222 Note: =*_ALL= properties are meta-properties, defining rules on how to
 223 use the properties themselves.
 224
 225 When you're in a field of the column, you can define all the possible
 226 values for the associated property by pressing `a': it will prompt the
 227 current set of allowed values and you will be able to edit it.
 228
 229 * Complete example with three items in the subtree
 230
 231 Here is a example on how the column view affect the display of an entry
 232 and its subtree.  Take it and test it.
 233
 234 : ** My project
 235 :    :PROPERTIES:
 236 :    :COLUMNS:  %20ITEM %9Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
 237 :    :Owner_ALL:    Tammy Mark Karl Lisa Don
 238 :    :Status_ALL:   "In progress" "Not started yet" "Finished" ""
 239 :    :Approved_ALL: "[ ]" "[X]"
 240 :    :END:
 241 :
 242 : *** Item 1
 243 :     :PROPERTIES:
 244 :     :Owner:    Tammy
 245 :     :Time_spent:   1:45
 246 :     :Status:   Finished
 247 :     :END:
 248 :
 249 : *** Item 2
 250 :     :PROPERTIES:
 251 :     :Owner:    Tammy
 252 :     :Status:   In progress
 253 :     :Time_spent:   0:15
 254 :     :END:
 255 :
 256 : *** Item 3
 257 :     :PROPERTIES:
 258 :     :Owner:    Lisa
 259 :     :Status:   Not started yet
 260 :     :Approved: [X]
 261 :     :END:
 262
 263 * Editing properties from the column view
 264
 265 So far, so good.  But one great thing about the column view is that it
 266 lets you access and edit any property very quickly.
 267
 268 See this:
 269
 270 : ** My project
 271 :    :PROPERTIES:
 272 :    :COLUMNS:  %20ITEM %10Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
 273 :    :Owner_ALL:    Tammy Mark Karl Lisa Don
 274 :    :Status_ALL:   "In progress" "Not started yet" "Finished" ""
 275 :    :Approved_ALL: "[ ]" "[X]"
 276 :    :END:
 277
 278 Use =v= to display the field value in the minibuffer.
 279
 280 Use =e= to interactively select/edit the value.
 281
 282 Use =S-left/right= to cycle through the allowed values in a field.
 283
 284 Use =a= to edit the allowed values for this property.
 285
 286 Nice, isn't it?
 287
 288 * Conclusion: more to come
 289
 290 Okay, that's all for today. But let me drop two last hints to let you
 291 explore column views further:
 292
 293 1. You can use the column view and cycle through visibility.
 294 2. The column view also works in agenda buffers.
 295
 296 I guess this is already suggestive enough...
 297
 298 Enjoy!
 299
 300 - https://orgmode.org/
 301 - https://orgmode.org/org.html#Column-View
 302
 303