Themeability / CSS friendliness Suggestion

[esm7]

Hey,

Now that auto-complete (#822) and boolean queries (#852) are behind us, the next thing I wanna do for Obsidian Tasks is to make it much more CSS friendly.
We're not gonna continue letting all those Todo apps out there look better than our awesome queries, are we? 😉

What I had in Mind

From an infrastructure point of view, what QueryRenderer is missing is to communicate more information to the rendered HTML, so it can be beautifully themed with CSS.

Specifically, what I think that needs to be changed is:

1. Each query line should be rendered as multiple divs -- one for the description, another for the due date, another for recurrence, a div for each single tag, etc.
2. Most things known to a Task object should be communicated as HTML classes, both in the task's main div (the one that contains all the components) and in each individual component. For example a task with medium priority should have priority-medium in its div class and also the div that hosts the priority text should have priority-medium class as well.
3. Classes should represent some useful logic related to dates. I was thinking task-due0d for tasks due today, task-due1d for tasks due tomorrow, task-due2d for tasks due in 2 days, task-due-1d for tasks due yesterday, task-scheduled0d for tasks scheduled today -- you get the idea.

For example, the following task:
- [ ] #task Fix the bugs in the latest release ⏫ 📅 2022-07-11 #atWork

Should be rendered this way by QueryRenderer:

• Container div: classes task-priority-high, task-due1d, task-#atWork
• Child divs:
  • Fix the bugs in the latest release (class task-description)
  • ⏫ (classes task-priority, task-priority-high)
  • 📅 2022-07-11 (classes task-due, task-due1d)
  • #atWork (classes task-tag, task-#atWork

This can effectively render to the exact same look as current queries do. As default, or for users who want to keep things the way they are, the look of queries will not change at all if so you wish.

But...

Why We Should Do It

With the above example, individuals or theme designers can do wonders.

• A task line can be colored if the due date is getting near.
• A task line can be colored or displayed differently in a variety of ways according to the task priority.
• The task line can be split to a more sophisticated view, e.g. the description being in regular text and other components shown beneath in a smaller font or different color. I personally love how Todoist display tasks, and that can easily be accomplished with the above by just playing with CSS.
• Users who wish to do so can show specific tags in a different color.

---

That's my general idea (well, ok, it's more than general 😆 )
(I actually tried to do this about 2 weeks ago, thinking it's a low-hanging fruit, but failed miserably 😃 now I'm back with conclusions...)

@claremacrae, would love to get your feedback about whether you welcome this change, and any other insights of others too of course!

[claremacrae]

Hey @esm7

@claremacrae, would love to get your feedback about whether you welcome this change, and any other insights of others too of course!

Lots of thoughts:

• It sounds really good - thank you very much indeed for offering to do it
• There are a lot of complaints about the already-slow speed of rendering task results blocks in Investigate whether Tasks plugin affects editing speed in large vaults - Answer: it does, and will be worked on soon. #697. What impact, if any, might the generating and rendering of lots of extra class names have for those already struggling with this?
• I would really appreciate this PR including reasonably thorough user-focused documentation for the styles, including examples of how to use them.
  • More along the lines of How to style backlinks, than Styling, so that more users can take advantage of this.
  • I'm happy to take a first thorough draft of the docs and copy-edit, for example.
  • Or to pair on writing the docs.
  • We do have the Tasks-Demo, where sample snippets can be added, which makes creation of screenshots in native style a lot easier.
  • (Context: I totally underestimated how long it would take to document Boolean search for users, and doing that is blocking the next release currently.)
• There are already a number of css-related discussions and issues. If going ahead and doing this, it would help if you could review those, for anything that is missing and could easily be added for completion.

[esm7]

Full thumbs up for working on user-focused documentation to this, with all the points that you wrote.
I also reviewed the CSS-related discussions and this suggestion indeed includes all of them (nice to see someone someone else using Todoist as the reference!). Regarding the 2 issues, these are not exactly in the same area.

About the performance impact: being sure requires some measurements (and I don't mind to take measurements of before & after), however I doubt that more details in the actual rendering will have a meaningful performance toll. Electron's renderer is very fast and rendering the same data using some more divs will doubtfully add more than a few milliseconds.

This is probably negligible compared to what it takes to run a query -- most notably (I assume) iterating over thousands of tasks.

This too requires measurements, maybe I'm completely wrong here, but my hunch says that if we add simple code in Query to reorganize query filters by their relative likelihood, it will make most queries run many times faster. The difference between the line not done appearing first in the query vs appearing last, in a big vault on which most tasks are complete (a typical situation I'd assume), is huge.

[claremacrae]

Full thumbs up for working on user-focused documentation to this, with all the points that you wrote. I also reviewed the CSS-related discussions and this suggestion indeed includes all of them (nice to see someone someone else using Todoist as the reference!). Regarding the 2 issues, these are not exactly in the same area.

Brilliant - thanks.

About the performance impact: being sure requires some measurements (and I don't mind to take measurements of before & after), however I doubt that more details in the actual rendering will have a meaningful performance toll. Electron's renderer is very fast and rendering the same data using some more divs will doubtfully add more than a few milliseconds.

This is probably negligible compared to what it takes to run a query -- most notably (I assume) iterating over thousands of tasks.

Nevertheless, there are measurements in that other issue, including a profiling video. Displaying thousands or even hundreds of tasks makes it impossible to type in Obsidian.

This too requires measurements, maybe I'm completely wrong here, but my hunch says that if we add simple code in Query to reorganize query filters by their relative likelihood, it will make most queries run many times faster. The difference between the line not done appearing first in the query vs appearing last, in a big vault on which most tasks are complete (a typical situation I'd assume), is huge.

Appreciate your hunch - and if we continue with this it should be in the other issue, but at this point it's hard data I'm after - and a couple of users have been providing that, very helpfully.

[claremacrae]

I should also have noted, @esm7, that I believe that @sytone has added various extra CSS classes for displaying tasks in his fork of Tasks: https://github.com/sytone/obsidian-tasks-x.

We have agreed to try and keep open the option of incrementally merging some of his changes back to Tasks and trying to keep them compatible.

I can't see anything about his new style classes in his docs - unsure if I'm missing anything obvious.

Anyway, for any classes you were planning to add, we should explore if he added them already, and if so, keep the class names and the code as consistent as possible.

Diffing of the two code bases is complicated slightly by the fact that he has:

• reformatted all the code to a longer line length
• changed the directory structure of src/

I am holding off doing those things in Tasks until all the existing PRs are merged or closed...

[esm7]

@sytone can you elaborate or point me at those mentioned CSS classes, so I can make this change as compatible as possible?

On a different note, perhaps now that boolean queries are merged, SQL queries are not as important as they used to be.

[claremacrae]

@sytone can you elaborate or point me at those mentioned CSS classes, so I can make this change as compatible as possible?

On a different note, perhaps now that boolean queries are merged, SQL queries are not as important as they used to be.

@sytone Please note that whilst boolean queries are merged in to this project, they are not yet released, as they are awaiting sufficiently-thorough docs on some other features in the upcoming release.
Not saying that you would, but please don't merge post-1.8.2 features from this repo in to yours until they have first been released in Tasks - likely in the next couple of days... Cheers, and thanks!

[claremacrae]

@sytone can you elaborate or point me at those mentioned CSS classes, so I can make this change as compatible as possible?

@esm Ah well, it was worth a try to ask. Let's stick with what you suggested above then!

[AnnaKornfeldSimpson]

@esm7 I know very little CSS (essentially the MDN CSS modules, staring at various snippets in Obsidian, and a few blogposts) so please read this as a beginner's question: will adding "div" (or "span" I guess) for components of the task text's display alter the "inline" vs "block" nature of the task text "li" overall?

More classes for styling options sounds like fun!

[esm7]

No, divs by themselves mean nothing to how HTML is rendered. It will look exactly the same, pixel by pixel.
The only thing these divs will do is to wrap specific parts of the HTML so styles can be applied to them via CSS. And with those styles the sky is the limit, you can change tasks to look like blocks vs inline, separate components and pretty much anything you can imagine.

[tburd]

I am an Obsidian beginner (who tries to read the docs 😉) and have some CSS background. I am looking forward to seeing the implementations suggested here.

For now, I would like to know wheter it is possible to do add a custom css class to the DIV containing the whole query block.
Something like this would help a lot already:

 ```tasks
 not done
 add class 'red-background'   

Thanks for the support! 😊

[claremacrae]

Hi @tburd these are the things you can currently style:

https://obsidian-tasks-group.github.io/obsidian-tasks/advanced/styling/

[claremacrae]

What I do if I want different styles for different query blocks is to put the blocks in custom Obsiadian call-out blocks.

[claremacrae]

If you have any more questions, @tburd, feel free, but please do start them in separate discussions. Many thanks.

[tburd]

Thanks for the tip @claremacrae, callout blocks provided a good solution! 👍

[claremacrae]

Hi @esm7 I think that #1151 is a vote for this! 😄

[njwfish]

Following up on my post in #1151!

I would love to see this, and I agree that good user docs are essential. I think implementing this could be a feature users really really love allowing infinite customization. I'd love to see it happen! I'm not sure I'm a good enough CSS/javascript programmer to help, but if theres something I could push on I'd be happy to hear about it!

[esm7]

This is very important to me too and I'm disappointed for not being able to work on it yet, but I have high confidence that we'll have this (at least in a PR stage) within 2-3 weeks :)

[esm7]

A quick update for everybody waiting on this, including myself!
I'm substantially behind my planned schedule because of some unexpected time-consuming events (good ones, nothing to worry about!)
Expecting to start working on this next week.
It's literally the top priority in my (somewhat sparse lately) "free-time development queue", so rest assured I'm not putting it aside.
From my point of view it's a must-have feature for getting the most out of Tasks.
Hopefully my next comment here will be next week with some initial screenshots :)

[claremacrae]

Thank you. I’m glad you are OK.

[esm7]

Hey, just wanted to drop by and update that although much later than expected, I started working on this today :)
A substantial amount of work here relates to making it testable, as the current rendering mechanism is not covered at all. I am therefore separating the rendering logic away from Task.ts, making a more explicit representation of a task's layout, and several other refactoring efforts that will make this change go smoothly (even unnoticed by default, if so you wish!)
Will update with more details in the upcoming days.

[claremacrae]

Hi @esm7 - sounds great - thank you.

I think the following is exactly what you meant, but it would really aid the review process if the PRs could be separated out in to refactoring ones, and features/functionality changes please.

[esm7]

Indeed, I'll send two separate PRs once I have the complete set of changes more or less ready.

[claremacrae]

I've noticed recently that a few plugins allow their behaviour to be customised via the Style Settings plugin:

For example, Buttons:

I've no idea whether this work might enable that capability for the Tasks plugin, or if the changes on this feature could be done in a way that could be compatible with the Style Settings plugin... Or if this is all something completely independent...

But I wanted to at least mention the idea, just in case it might enable many more people to take advantage of the styling options that will be opened up than just those comfortable with CSS snippet files....

[esm7]

This seems substantially easier than a 'theme' setting I was considering to add. Thank you, will look into it.

[esm7]

I thought you all might appreciate some eye candy, so after a few hours of working on this in the past evenings, here it goes.

Check out this sample query result:

Here's a simple CSS that uses the new classes to modify various task properties:

.task-priority-high input[type=checkbox] {
	box-shadow: 0px 0px 2px 2px red;
	border-color: red;
}
.task-priority-low input[type=checkbox] {
	box-shadow: 0px 0px 2px 2px blue;
	border-color: blue;
}
.task-priority-medium input[type=checkbox] {
	box-shadow: 0px 0px 2px 2px orange;
	border-color: orange;
}
span.task-priority {
	display: none;
}

.task-due.task-due-today span {
	background: #d2e8fa;
	border-radius: 10px;
	padding: 2px 8px;
}
[class*="past-"] .task-due span {
	background: #ffbfcc;
	border-radius: 10px;
	padding: 2px 8px;
}

.task-recurring {
	color: gray;
}

Now see what happens when I apply that without even restarting Obsidian:

And another step forward... ;)
Some more CSS work using grids:

ul > li.task-list-item {
    grid-template-columns: 25px auto;
    display: grid;
    align-items: top;
}

span.tasks-backlink {
    grid-row: 2;
    grid-column: 2;
	font-size: small;
}

ul > li.task-list-item .task-list-item-checkbox {
     margin-inline-start: 0; 
	 margin: 5px 2px;
	 border-radius: 50%;
}
span.task-description {
    grid-row: 1;
	grid-column: 1/10;
}
span.task-recurring {
    grid-row: 2;
	font-size: small;
}
span.task-due {
    grid-row: 2;
	font-size: small;
}
.tasks-list-text {
    position: relative;
    display: inline-grid;
	width: max-content;
	grid-column-gap: 10px;
}
span.task-extras {
    grid-row: 2;
    grid-column: 2;
	font-size: small;
}

And we get this:

All this when I'm very far off from being a CSS wizard -- I'm sure actual theme designers can do wonders here!

So in the next few days I'll add tests, split the PRs, and hopefully soon everybody can enjoy this too :)

[Cito]

Nice work @esm7!

[njwfish]

Incredible this is exactly what I was hoping for here -- super excited about the possibilities!

[claremacrae]

Wow. Fantastic!

[esm7]

Quick update and a follow-up discussion.

1. The full code, its full testing framework (which was most of the work actually), and tests that cover the basic functionality from before this change are ready and available in my branch in case anyone wants to play with it. I didn't write the documentation yet but it's fairly similar to the original description in this discussion and the CSS snippets I attached from 10 days ago are a great start. (Emphasizing again: if you build Tasks from my branch, you will not see any visible difference whatsoever -- that's the whole point :) But the CSS snippets above will only work in my branch.)

2. I deliberately only wrote so far the tests that correspond to the original way the code worked, because my next step is to split the PR into a pure refactoring PR (with tests, that were impossible before this refactoring), and then a much smaller "themeability" PR with more tests and documentation.

3. @claremacrae I think it's time to start thinking/discussing your point of view about the future UI, default theme and themeability in general of Tasks.

   1. In the long term, do you want queries and HTML renders of Tasks to closely resemble the Markdown (as it is today = "no theme"), or do you want a more fancy/clean-looking default theme?
   2. Do you want to give users the ability to choose a theme through the plugin settings, and supply a few themes with the plugin? Technically it's super easy to do, the hard part is to govern these built-in themes.
   3. Where do you imagine users sharing custom themes and finding them?
   4. If the answers to the above make this relevant, perhaps it's worth considering to ask for some help from leading Obsidian theme designers. e.g. if the designer of a sleek theme like Minimal can make a default theme for Tasks, it would be really useful for the users.

[esm7]

It's hard to easily compare before-and-after chunks of code, because of the (understandable) moving of code, but it looked to me like the display of urgency value might have disappeared, and indeed when I turned that on, I didn't see values displayed.

@claremacrae do you mind checking that again, and if you don't see the urgency with my branch, maybe try without the CSS applied?
It's puzzling because I did not touch this code at all, it's right where it used to be at QueryRenderer.ts (perhaps I should have moved it to the new TaskLineRenderer, I wasn't sure. But anyway right now it should work exactly the same way.)
In a show urgency query I see the urgency showing, no matter the CSS. With the "multi-line" CSS it should be in the 3rd row of the task, to the left of the section link and Edit button.

[claremacrae]

With no snippets enabled, and the GitHub actions build on you branch, on iPad, the urgency is displayed. It is feinter then I remembered, so it's possible I missed it.

Now trying to figure out how to add the snippets on iPad - likely via Working Copy.

[claremacrae]

This is what it looks like with just the grid CSS from above enabled.

Clearly the urgency is shown, and I missed it earlier. It might be a combination of some or all of:

• I assumed it would be on the same line as the dates
• plus I had fogotten how dim it is by default
• plus based on my reading of the code, the urgency code was not where I assumed it would be, so I was kind of expecting it wasn't going to be displayed...

[esm7]

This is actually highly related to my dilemma of whether the urgency should go to the refactored piece of code (soon you'll see in a new file TaskLineRenderer.ts) or stay in QueryRenderer.ts.
Unlike the backlinks and the edit button, which are in a higher-level than the task itself, the urgency is a property of the task. So maybe it makes more sense to put it equal to the other task properties. That's probably why you intuitively expected it there.

[claremacrae]

So maybe it makes more sense to put it equal to the other task properties.

I agree.

As well as it "feeling" logical for the score to go on the same line as the other properties, for usability/glanceability I feel the backlinks would benefit from all starting at the same horizontal position, so it's possible to skim down a list of tasks and see the shapes of the backlinks.

With the urgency values varying in width, that skimming is harder to do...

[claremacrae]

Quick update and a follow-up discussion.

1. The full code, its full testing framework (which was most of the work actually), and tests that cover the basic functionality from before this change are ready and available in my branch in case anyone wants to play with it. I didn't write the documentation yet but it's fairly similar to the original description in this discussion and the CSS snippets I attached from 10 days ago are a great start. (Emphasizing again: if you build Tasks from my branch, you will not see any visible difference whatsoever -- that's the whole point :) But the CSS snippets above will only work in my branch.)

I had a quick look at the branch - I only had time to look in the GitHub diffs view so didn't follow the changes in detail.

I presume the yarn.lock change was for your own convenience on your branch, and not something that will be in a PR....

2. I deliberately only wrote so far the tests that correspond to the original way the code worked, because my next step is to split the PR into a pure refactoring PR (with tests, that were impossible before this refactoring), and then a much smaller "themeability" PR with more tests and documentation.

Sounds good.

3. @claremacrae I think it's time to start thinking/discussing your point of view about the future UI, default theme and themeability in general of Tasks.

   1. In the long term, do you want queries and HTML renders of Tasks to closely resemble the Markdown (as it is today = "no theme"), or do you want a more fancy/clean-looking default theme?

Good question. I don't know yet. I'm not sure that I even really know what to expect yet in the short term, yet alone in the long term.

One thing I would really like is for users to have ways to control the appearance of their results with needing to futz around with CSS snippets. I see that as a separate thing from the current work though, that is, something that builds on the current work.

I am not sure, but I think I would like to wait for a little while and see what kinds of styling ideas users come up with.

It would be worth looking through the discussions and feature requests to see what kinds of things users have requested in the past, styling wise.

2. Do you want to give users the ability to choose a theme through the plugin settings, and supply a few themes with the plugin? Technically it's super easy to do, the hard part is to govern these built-in themes.

Oooohhh - I guess that answers what I said above.

Yes please!

You are right above the governing of the themes. Are there other plugins that have done similar things? Can anything be learned from them?

Actually, I suspect the word "themes" is likely to confusion, given the ambiguity with Tasks' own theme system. So best avoided.

Style?
Layout?

3. Where do you imagine users sharing custom themes and finding them?

The two existing possibilities are:

• Discussions - Show & Tell
• As new snippets in the sample vault.

Maybe i'm being a bit too cautious - I certainly don't want to cramp your style.
But the simplest initial thing is to invite additions in Show & Tell, just to get a sense of what people are doing with this.

4. If the answers to the above make this relevant, perhaps it's worth considering to ask for some help from leading Obsidian theme designers. e.g. if the designer of a sleek theme like Minimal can make a default theme for Tasks, it would be really useful for the users.

Interesting. You are way ahead of me!

[claremacrae]

Related discussion: #1358
"How would custom task states interact with CSS theming work?"

[claremacrae]

This has now been released in Tasks 3.0.0.

Huge thanks to @esm7 for this tremendous body of work!

Find out more in the comprehensive user docs.