Testing new taxy-based org-ql-report view (feedback welcome)
- Dominant language
- Emacs Lisp
- Stars
- 1.6k
- Forks
- 120
- PR merge metrics
- No merged PRs in 30d
Description
This issue is for tracking early feedback for testers of the https://github.com/alphapapa/org-ql/tree/wip/taxy-org-ql-view branch.
To test:
1. Install the package from the branch, e.g. with Quelpa:
```el
(use-package org-ql
:quelpa (org-ql :fetcher github :repo "alphapapa/org-ql" :branch "wip/taxy-org-ql-view"
:files (:defaults (:exclude "helm-org-ql.el"))))
```
It may be helpful to use https://github.com/alphapapa/with-emacs.sh to install it into a separate Emacs configuration, but this is optional.
2. Load the library, e.g. by evaluating `(require 'taxy-org-ql-view)`.
3. Evaluate a `taxy-org-ql-report` form, for example:
```el
;; This additional predicate is used in the example below:
(org-ql-defpred stuck ()
"Stuck projects."
:normalizers ((`(,predicate-names . ,args)
`(and (todo "PROJECT") (not (descendants (todo "NEXT" "WAITING")))))))
(taxy-org-ql-report :buffer "Clients"
:queries '(( :name "Agenda"
:where (and (or (scheduled) (deadline auto)) (not (done)))
:group (((planned :today :name "Today")) ((planned :past)) ((planned :future))))
( :name "Stuck"
:where (stuck))
( :name "UNDERWAY"
:where (todo "UNDERWAY" "NOW"))
( :name "NEXT"
:where (todo "NEXT"))
( :name "Neglected"
:where (and (todo "PROJECT")
(not (descendants (and (todo "WAITING") (scheduled))))
(not (or (clocked :from -7) (descendants (clocked :from -7))))
;; Prevents stuck projects from being duplicated in neglected list.
(not (stuck)))
:group nil))
:sort '(priority date reverse)
:group '(priority)
:columns '("Keyword" "Heading\\Parent" "Pri" "Planning" "Tags")
:sections `(( :name "Client 1"
:from "~/client1.org")
( :name "Client 2"
:from "~/client2.org")))
```
The documentation is not yet written, but the bottom line is that this displays the results of multiple org-ql queries in a single buffer, similar to Org Agenda blocks. In this example, all of the queries are run for each section, each of which runs on a different file. The result looks something like this, where each section is a collapsible `magit-section`:

One of the primary new features is the use of `taxy` to dynamically group entries. For example, you could use:
```el
:group '((planned) todo)
```
...which would put all items with planning timestamps in one group, and group remaining items by their to-do keywords. You could also give an argument to the to-do matcher, like `:group '((planned) ((todo "SOMEDAY" "MAYBE")) priority)`, which would only collect items with the SOMEDAY or MAYBE keywords, and then group remaining items by priority.
Among other things, this branch will also allow easier customization of the output format. For example, the `:columns` argument is used to select columns for display, each of which is defined with simple top-level forms here: https://github.com/alphapapa/org-ql/blob/9496f7a8fcba11b244ea0c1921a3c6dcec7a02fe/taxy-org-ql-view.el#L106 And users can define additional columns in their own configurations and use them in the report view.
Also, the `taxy-org-ql-report` view retains some compatibility with Org Agenda commands since it continues to add relevant text properties to each item (e.g. you can use `C-c C-d` to change the deadline of an item). In the future I may design a new system for defining commands for this kind of buffer, but for now this is still useful.
Any feedback on this branch is welcome. I don't intend to remove the existing `org-ql-view` library in the next release, but someday it may be subsumed by this one.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.