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