Show currently clocked heading

[chasecaleb]

Is your feature request related to a problem? Please describe.
As a user who tracks their time with clocking, I would like a way to tell when I have a clocked in heading and a way to navigate to it as well.

The current clock functionality in organice is better than nothing since it allows me to clock in and out on a heading, but the lack of UI visibility is limiting. There are a couple main scenarios where this is an issue:

1. As a user, I have the memory of a goldifsh and forget whether or not I have a clock running. Similarly, even if I remember that I'm clocked in I may forget which heading is clocked.
2. As a user who sometimes clocks into a heading but then gets distracted by multi-tasking or needs to find related information in a different org file, I would like a button to take me back to the currently clocked heading.
3. [Tangential, but likely needs to be tackled as part of this] As a user with the memory of a goldfish, I would like a way to prevent clocking into multiple tasks at the same time.

Describe the solution you'd like

• For scenarios 1 & 2 above:
  • At minimum, an indicator that a task is currently clocked in and a button to navigate to it.
  • Optionally: also a way
• For scenario 3: Emacs handles this by automatically clocking out of the previous heading when clocking into a new one. I think this would be fine for organice as well.

Additional requirements:

• This should work across multiple files. It doesn't necessarily have to be every single org file in the backend; either every organice agenda file or every file that has been loaded/persisted to storage would both work I think.
• Nice-to-have: It would be nice if this can detect existing clocks by scanning file contents, as opposed to keeping track of the current clock out-of-band. This would make it possible to clock in from one place (e.g. from Emacs on a computer) and then clock out from another (e.g. from organice on my phone). This would also be a more robust implementation with lower risk of bugs due to state getting out of sync.

Additional context
Emacs accomplishes this by displaying the current task in the mode line and providing function org-clock-goto.

---

I'm planning on implementing this myself if there's interest. I'd like some help coming up with and agreeing on a mock first though. I haven't worked on any mocks in Excalidraw myself yet because I wanted to at minimum bounce ideas off you first.

Possible ways to do this:

1. Add a button within the "Show Search / Task List" magnifying glass icon at the bottom to go to the clocked heading. Perhaps the magnifying glass icon could also change colors to indicate when a clock is running.
2. Display the clocked heading text somewhere in the Agenda modal. Tapping it would go to the clocked heading. I'm thinking this would be shown towards the bottom of the modal as a footer, but it could be somewhere else in the model. Similarly to the last suggestion, I think changing the color of the agenda calendar icon when a clock is running would make sense.
3. At the top of the page as an additional header, i.e. between the "file browser" header and the main page content. In this case the heading title should be truncated if necessary to stay within a single line, to avoid taking up too much screen real estate (this is easy with CSS).

[munen]

Hi @chasecaleb

It's very encouraging and fun to see that you're already tackling the next interesting task🚀

Clocking is one of the great Org mode features that I (and my team) also make regular use of when working on billable time for clients, so I'm happy to see this feature getting more love. The original implementation in organice is from @schoettl and I've seen that he has already given you a 👍 on this issue, too(;

There are a couple main scenarios where this is an issue:

As a user, I have the memory of a goldifsh and forget whether or not I have a clock running. Similarly, even if I remember that I'm clocked in I may forget which heading is clocked.

Count me into the school of goldfish.

As a user who sometimes clocks into a heading but then gets distracted by multi-tasking or needs to find related information in a different org file, I would like a button to take me back to the currently clocked heading.

👍

[Tangential, but likely needs to be tackled as part of this] As a user with the memory of a goldfish, I would like a way to prevent clocking into multiple tasks at the same time.

This is where it get's a bit tricky.

Generally speaking, Emacs and the original Org mode implementation are always right, because they define the original behavior. So, generally, any behavior (or markup) that organice employs is either a bug or should have a good rationale. Now, more specifically, Emacs has different constraints than organice. Emacs is a Desktop application and therefore developed for the singular user in mind. organice is a web-based application and therefore can enhance the original Emacs Org mode in multi-user ways.

Specifically for clocking, this is actually something that we at 200ok.ch make use of. We have an Org mode file that is shared with the customer (often as an automated HTML export) and we track time using organice. Since there's multiple tasks and sometimes multiple people working at the project, we track multiple items at the same time.

This could be a case of https://xkcd.com/1172/, but I think that thinking about multi-user situations with organice has potential.

The behavior of this feature is not explicitly documented, so it could be that it has a small user-base. On the other hand, I remember a conversation (I think on Reddit) with @alphapapa of org-ql and org-super-agenda fame (to only quote two of his popular repositories) where he said that we should document this, because it could be quite a killer feature. Of course, as always, my memory could just be filling in niceties to help my side of the argument(;

In any case, that clocking in to multiple tasks at the same time is neither a decision, nor my last words on it. I'm just laying down some arguments as they come to my mind. I'm thinking of this as the 'bouncing ideas off' phase that you've initiated(;

• For scenarios 1 & 2 above:
  • At minimum, an indicator that a task is currently clocked in and a button to navigate to it.

That would be nice!

• For scenario 3: Emacs handles this by automatically clocking out of the previous heading when clocking into a new one. I think this would be fine for organice as well.

Or, just brainstorming here, an indicator for the tasks that are currently clocked in. I'm thinking that we can use UX in favor of automation here. Users who want to clock multiple tasks can. Users who don't want to clock multiple tasks will have an easy time to see that they are already clocking into one task when they want to start a new one.

This should work across multiple files.

Again, just brainstorming. On the one hand, this could be quite cool. On the other, it assumes that all Org files belong to the same person and this person can only work on one issue. It might be the right assumption, it might not be. For example, a team of people could be working on different projects. However, they organize themselves with Org mode and organice. Or even a single person only uses organice.

In any case, independent of the above statement:

It doesn't necessarily have to be every single org file in the backend; either every organice agenda file or every file that has been loaded/persisted to storage would both work I think.

organice persists every file that has every been opened into localStorage for performance. However, without additional configuration, this file might be stale.

In organice's settings, under "File settings", there's many things that can be configured for any given file. For example, here I'm configuring some of my most important files:

This shows two of my main Org files things.org and reference.org. I don't need my references in the Agenda, but both of them are synced on startup, so that they are always fresh.

Nice-to-have: It would be nice if this can detect existing clocks by scanning file contents, as opposed to keeping track of the current clock out-of-band. This would make it possible to clock in from one place (e.g. from Emacs on a computer) and then clock out from another (e.g. from organice on my phone). This would also be a more robust implementation with lower risk of bugs due to state getting out of sync.

Maybe I'm misunderstanding you, but I'd say this is already implemented. You can start the clock in Emacs, then open the file in organice and stop the clock. The other way around also works. organice recognizes that there's already a clock in progress, already. When you're on the task, you can see that there's two different states of the 'clock' icon.

I'm planning on implementing this myself if there's interest.

I'm thinking this is a great feature which will be helpful to many people. So, if you want to build it, I'm in favor👍

I'd like some help coming up with and agreeing on a mock first though.

Sure, I agree that iterating on mockups will be very beneficial for this feature.

I propose that we discuss the 'one clock at a time' or 'multiple clocks at a time' issue first and then do the mockups, because the result of the discussion will likely influence the UX.

In any case, since you've already come up with multiple options, I'll be happy to comment on them, already.

Add a button within the "Show Search / Task List" magnifying glass icon at the bottom to go to the clocked heading.

Sounds good!

Addendum: It could also:

• Open the search pre-populated with a list of clocked tasks. The search already supports looking for clocked tasks (syntax documentation is in sample.org).
  • That would be quite consistent as the feature is located under the magnifying glass button.
• Go to 'the next'™ clocked task

Perhaps the magnifying glass icon could also change colors to indicate when a clock is running.

Maybe. I'm not super sure about it, though. My first thought was that the magnifying glass is a container for different things (search, task-list and clocks) so it would be hard for the user to know what triggered the change in color. On the other hand.. search and task-list don't really have state, so it wouldn't be hard to understand. I don't know. Maybe it's one of those things that just have to be tested and if we like it, we go for it. It would definitively be a prominent place and will make good use of real estate!

Display the clocked heading text somewhere in the Agenda modal. Tapping it would go to the clocked heading. I'm thinking this would be shown towards the bottom of the modal as a footer, but it could be somewhere else in the model. Similarly to the last suggestion, I think changing the color of the agenda calendar icon when a clock is running would make sense.

That would also be a good idea. I like it less than the first idea, though (but maybe for the wrong reasons). My reason is that I don't see clocked entries in the Emacs Org mode agenda, so using the existing search function of organice seems more natural. However, I might be wrong and showing clocked entries in the Emacs agenda is totally a thing and I just haven't used it so far.

At the top of the page as an additional header, i.e. between the "file browser" header and the main page content. In this case the heading title should be truncated if necessary to stay within a single line, to avoid taking up too much screen real estate (this is easy with CSS).

Also an option. I also like it less than the first option, because on a smartphone there's already so little space. And when I'm clocking (one or multiple) task(s), it would always show.

To summarize, I like this iteration of option 1 best: The magnifying glass turns colors, the user clicks it, the user clicks a new icon in the stack, the search pops up and shows the currently clocked tasks.

[chasecaleb]

Specifically for clocking, this is actually something that we at 200ok.ch make use of. We have an Org mode file that is shared with the customer (often as an automated HTML export) and we track time using organice. Since there's multiple tasks and sometimes multiple people working at the project, we track multiple items at the same time.

This could be a case of https://xkcd.com/1172/, but I think that thinking about multi-user situations with organice has potential.

Clever. Regardless of whether or not it's a case of that XKCD, that's an interesting use-case. I like your idea about showing a search for open clocks, for example, as a way of implementing this without requiring a single clock. Bonus: this makes implementation easier, since it eliminates the need to e.g. automatically find and clock out of the currently clock when the user clocks into something else.

Decision: let's continue to support multiple concurrently running clocks, including multiple clocks within a single file and multiple clocks across multiple files.

The behavior of this feature is not explicitly documented, so it could be that it has a small user-base. On the other hand, I remember a conversation (I think on Reddit) with @alphapapa of org-ql and org-super-agenda fame (to only quote two of his popular repositories) where he said that we should document this, because it could be quite a killer feature.

I spent a couple minutes searching and couldn't find this discussion so I don't think it was Reddit, but I think you're right on both accounts: it likely has a small user-base but it could also be a killer feature for some people. I don't think many people use org-mode like this since Emacs doesn't work well for this use case, but if there was more awareness that organice supports this then we might attract more users.

organice persists every file that has every been opened into localStorage for performance. However, without additional configuration, this file might be stale.

Right, but I don't think that concern is specific to this feature. You could say the same about the agenda, search, and tasklist after all - it's up to the user to enable "sync on startup" to avoid stale data in those views as well, right?

Maybe I'm misunderstanding you, but I'd say this is already implemented. You can start the clock in Emacs, then open the file in organice and stop the clock. The other way around also works. organice recognizes that there's already a clock in progress, already. When you're on the task, you can see that there's two different states of the 'clock' icon.

Yes, it already works like this for the clock icon on the header. What I meant is that the new UI indication (e.g. colored magnifying glass) and list of clock tasks (or whatever we come up with) should also function like this. It probably wasn't necessary to point out in the first place since in hindsight it seems like a given. I think my original point here was just "don't implement this in a dumb way".

Or, just brainstorming here, an indicator for the tasks that are currently clocked in. I'm thinking that we can use UX in favor of automation here. Users who want to clock multiple tasks can. Users who don't want to clock multiple tasks will have an easy time to see that they are already clocking into one task when they want to start a new one.

If by "indicator" you mean adding something to the heading (e.g. a clock icon next to heading's bullet point icon or a different background color on the heading text), then I think that's a useful enhancement. However I think that's orthogonal this feature, which is about finding/navigating to currently clocked task(s) without having to go looking for them. If you have a rough idea where to look then the indicator would be useful, but if you have e.g. multiple large org files with a lot of nested headers then that's not a convenient way to find the task. So how about a separate issue for this idea?

The search already supports looking for clocked tasks (syntax documentation is in sample.org)

Nice. There isn't currently support to search for currently running clocked tasks as best as I can tell, so I'll need to figure out and implement new syntaxfor this, right? For instance clock:.. shows all tasks that have a clock entry. I tried clock:now..now and that doesn't return anything.

---

TLDR: So all that said here's my first attempt at specific requirements for this feature. Point out changes as you see fit, then I'll come up with a mock up or two (or you're welcome to do the mock if you want):

1. For the purpose of this feature, "active running clocks" is defined as any open clocks within files included in search. "Files included in search" refers to the existing search functionality, so this means the currently viewed file as well as any files for which "Include in Search?" is enabled.
   • Alternatively: we could add an "Include in Clocklist?" setting to the list of file settings. However I don't think this is necessarily warranted, considering that we're talking about using a prefilled search view for the clock list display.
2. Search syntax should be extended so that clock:now will headings with an active running clock.
   • Not sure if this is the right syntax choice, let me know. Could also be e.g. clock:active, clock:open, or clock:running.
3. When there is an active running clock, the magnifying glass icon should change colors.
4. When there is an active running clock, click the magnifying glass should show a clock icon added the stack. Clicking this clock icon should show a "Clock list" pop up view.
5. The "Clock list" view should be identical to the existing "Search" view, with the following exceptions:
   • The search input should be pre-filled such that it only shows active running clocks.
   • The title text (top-left, above the input field) should be "Clock list" instead of "Search"

[munen]

Decision: let's continue to support multiple concurrently running clocks, including multiple clocks within a single file and multiple clocks across multiple files.

👍

Right, but I don't think that concern is specific to this feature. You could say the same about the agenda, search, and tasklist after all - it's up to the user to enable "sync on startup" to avoid stale data in those views as well, right?

Kind of right. However, for a file to show up in the agenda/search/task-list, it has to be either:

• The currently open file (and therefore recently pulled from the back-end) or
• Configured in the File Settings where it can be configured to be synced on startup.

Any other file that was opened is just saved to localStorage where it could lay unchanged for a long time.

I spent a couple minutes searching and couldn't find this discussion so I don't think it was Reddit, but I think you're right on both accounts: it likely has a small user-base but it could also be a killer feature for some people. I don't think many people use org-mode like this since Emacs doesn't work well for this use case, but if there was more awareness that organice supports this then we might attract more users.

👍

Yes, it already works like this for the clock icon on the header. What I meant is that the new UI indication (e.g. colored magnifying glass) and list of clock tasks (or whatever we come up with) should also function like this. It probably wasn't necessary to point out in the first place since in hindsight it seems like a given. I think my original point here was just "don't implement this in a dumb way".

👍

If by "indicator" you mean adding something to the heading (e.g. a clock icon next to heading's bullet point icon or a different background color on the heading text), then I think that's a useful enhancement. However I think that's orthogonal this feature, which is about finding/navigating to currently clocked task(s) without having to go looking for them. If you have a rough idea where to look then the indicator would be useful, but if you have e.g. multiple large org files with a lot of nested headers then that's not a convenient way to find the task. So how about a separate issue for this idea?

You're right, it's orthogonal.

I have opened a new issue as a someday/maybe task so we don't forget the nice suggestion about how to indicate it which you've made.

Nice. There isn't currently support to search for currently running clocked tasks as best as I can tell, so I'll need to figure out and implement new syntaxfor this, right? For instance clock:.. shows all tasks that have a clock entry. I tried clock:now..now and that doesn't return anything.

You are right, it doesn't support currently running clocked tasks.

Now that we're talking about this, I'm thinking that either clock:today or clock:now could show tasks that are running and are still open.

@schoettl is the original creator of the search syntax and feature. Do you have an opinion on the matter?

If you want to update the search grammar, here's some documentation to get you started: https://organice.200ok.ch/documentation.html#search_grammar

1. For the purpose of this feature, "active running clocks" is defined as any open clocks within files included in search. "Files included in search" refers to the existing search functionality, so this means the currently viewed file as well as any files for which "Include in Search?" is enabled.

👍

Alternatively: we could add an "Include in Clocklist?" setting to the list of file settings. However I don't think this is necessarily warranted, considering that we're talking about using a prefilled search view for the clock list display.

I agree, I think it's enough to work with the "Include in Search?" flag.

2. Search syntax should be extended so that clock:now will headings with an active running clock.

👍

Not sure if this is the right syntax choice, let me know. Could also be e.g. clock:active, clock:open, or clock:running.

I think it's a good sign we both intuitively thought that clock:now would be the right candidate.

3. When there is an active running clock, the magnifying glass icon should change colors.

👍

4. When there is an active running clock, click the magnifying glass should show a clock icon added the stack. Clicking this clock icon should show a "Clock list" pop up view.

👍

5. The "Clock list" view should be identical to the existing "Search" view, with the following exceptions:

The search input should be pre-filled such that it only shows active running clocks.
The title text (top-left, above the input field) should be "Clock list" instead of "Search"

👍

For this to be less messy code-wise, it would be wise (bad morning pun), to refactor TaskListModal and SearchModal into one component which then can also be used for the ClockList. Right now the former two share a lot of code and functionality.

There's an issue which includes the refactor task as a subset: #211

FYI: The issue also documents a way in which we could get rid of the stack behind the magnifying glass and unify search and task-list into one view. I think the proposed pattern (which has previously been discussed between @schoettl and me) could be extended to the ClockList in the future.

TLDR: So all that said here's my first attempt at specific requirements for this feature. Point out changes as you see fit, then I'll come up with a mock up or two (or you're welcome to do the mock if you want):

I'll finish with the TLDR that you had on top of the list which I've just commented on. Since you've made a very clear explanation of what this new feature is going to look like, I feel there's no need for a mockup anymore. If you think differently and want to further discuss UX before you want to start implementing, then a mockup would make sense, of course.

In any case, thank you for your solid project management on this issue so far. This is going to be another good one!🙇🙏

[chasecaleb]

There's an issue which includes the refactor task as a subset: #211

FYI: The issue also documents a way in which we could get rid of the stack behind the magnifying glass and unify search and task-list into one view.

I like all the ideas in #211, and I think we should treat it as a blocker for the present issue for both UI and technical reasons:

1. I like replacing the button stack with a tab bar. It's a big UX win since then we'll be using a single design pattern instead of two different ones across different parts of the app.
2. It makes more sense to refactor first and then benefit from the improvements while implementing this issue, as opposed to making a bigger mess by implementing this issue first. Doing the work in Refactor TaskListModal and SearchModal #211 first will make this faster and safer to implement.

Since you've made a very clear explanation of what this new feature is going to look like, I feel there's no need for a mockup anymore.

I was tempted to say the same thing, since what we've settled on is similar enough to existing parts of the UI.

P.S. I'm so glad that search is implemented with a nice grammar instead of something crazy like string parsing by hand. Well done.

[munen]

I like all the ideas in #211, and I think we should treat it as a blocker for the present issue for both UI and technical reasons.

I'm happy to hear you say that, because it would make a bigger mess to introduce a third similar component. However, I wasn't going to say it's a blocker, because if you're passionate about introducing this feature, I don't want to block you with a refactoring that I haven't done so far.

I'm also happy to hear you like all ideas in #211. The issue is the resolve of a few discussions and calls between @schoettl and me. It's good to see it resonate with others, as well!

P.S. I'm so glad that search is implemented with a nice grammar instead of something crazy like string parsing by hand. Well done.

Thank you 🙏 The design and grunt work is done by @schoettl. I only helped. Personally, I'm very pleased with the implementation, though. It's a nice grammar that I continue to like to use, and there's well written code and tests.

[tarnung]

Hi Caleb!
I just set up a dev environment for organice again and I'm still catching up with everything that happened here since I last checked. So I might not be up to speed with everything that you discussed yet.

I extended the search grammar with the "clock"-keyword a while ago.
Currently "clock" always searches for headers with clocked time on them.
"clock:now" is a legal search term that finds all headers where either the "clocked in" time or the "clocked out" time is between now and now.
I guess we can savely assume that it wouldn't be disaster to loose this functionality.

"clock:today" does something a little more useful since it finds all headers where either the "clocked in" time or the "clocked out" time is between start of current day and end of current day. I'd like to keep that capability.

Currently whenever the "clock" keyword is used in a valid search expression we build a timefilter (reducers/org.js line 1170).
You probably don't want to do that and instead build a filter that just searches for "logBookEntries" with a "start" and no "end" property. Beware, if I remember correctly, there are things besides clock entries that also populate "logBookEntries" and only have a "start" timestamp. I can't quite remember what they were. Maybe logging status change in repeated tasks? You'll have to check for the type of log book entry.

[tarnung]

I guess I made a bit of a mess since I placed the search functionality for clock entries in setSearchFilterInformation (reducers/org.js line 1197) and not in isMatch like the rest of the search criteria. Took me a moment to get a hang of what's happening again.

But nonetheless, "clock" queries can be matched with every other search term (searching for a tag, text, schedule timestamps etc). I guess it would be nice if that would also be true of searching for active clock entries. Not because anyone would use it a lot but simply to keep the behaviour of search consistent.

[munen]

Hi, @tarnung, hi @schoettl👋

Cool that you’re getting involved with this👍🚀

[schoettl]

Hi all :) @tarnung: right, I see. Let's discuss your point regarding setSearchFilterInformation and isMatch in #745

[tarnung]

@chasecaleb you can look at #747 for a basic implementation proposal. It only covers functionality not proper UI integration though.

[tarnung]

The feature is merged into master. Let's continue the discussion over in #744 or in new issues, if there is need for further improvement,