Skip to content

Commit 848d8bb

Browse files
claremacraeclaremacrae
authored
Merge pull request #3198 from obsidian-tasks-group/docs-for-styling
docs: Add the "Tasks extras" and other improvements to Styling docs
2 parents 5650d36 + 69f6ea5 commit 848d8bb

9 files changed

+301
-120
lines changed

‎docs/Advanced/Styling.md‎

Lines changed: 159 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,16 @@ The Tasks plugin renders a task in the following structure (this refers to query
4444
- Task description and tags (span class="task-description")
4545
- Internal span
4646
- Each tag in the description is wrapped in <a href class="tag" data-tag-name="[tag-name]">
47+
- Task ID (span class="task-id")
48+
- Internal span
49+
- Task 'depends on' (span class="task-dependsOn")
50+
- Internal span
4751
- Task priority (span class="task-priority" + data-task-priority attribute)
4852
- Internal span
4953
- Task recurrence rule (span class="task-recurring")
5054
- Internal span
55+
- Task 'on completion' (span class="onCompletion")
56+
- Internal span
5157
- Task created date (span class="task-created" + data-task-created attribute)
5258
- Internal span
5359
- ... start date, scheduled date, due date, cancelled date and done date in this order
@@ -65,135 +71,184 @@ The reason for this additional internal span is that it allows CSS styles that c
6571

6672
### Sample HTML: Full mode
6773

68-
To help visualise the structure above, here is the HTML for a sample task shown in [[Layout#Full Mode|full mode]].
74+
To help visualise the structure above, here is the HTML for a sample Tasks search shown in [[Layout#Full Mode|full mode]].
6975

7076
> [!Note]
71-
> The below does not (yet) show the "Task extras".
77+
> In Reading Mode:
78+
>
79+
> - all the classes and data inside the `li` are available,
80+
> - and none of the "Task extras" content is available.
7281
73-
<!-- snippet: TaskLineRenderer.test.Visualise_HTML_Full_task_-_full_mode.approved.html -->
82+
<!-- snippet: QueryResultsRenderer.test.QueryResultsRenderer_tests_fully_populated_task.approved.html -->
7483
```html
7584
<!--
7685
- [ ] Do exercises #todo #health 🆔 abcdef ⛔ 123456,abc123 🔼 🔁 every day when done 🏁 delete ➕ 2023-07-01 🛫 2023-07-02 ⏳ 2023-07-03 📅 2023-07-04 ❌ 2023-07-06 ✅ 2023-07-05 ^dcf64c
7786
-->
7887

79-
<li
80-
class="task-list-item plugin-tasks-list-item"
81-
data-task-priority="medium"
82-
data-task-created="past-4d"
83-
data-task-start="past-3d"
84-
data-task-scheduled="past-2d"
85-
data-task-due="past-1d"
86-
data-task-cancelled="future-1d"
87-
data-task-done="today"
88-
data-task=""
89-
data-line="0"
90-
data-task-status-name="Todo"
91-
data-task-status-type="TODO">
92-
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
93-
<span class="tasks-list-text">
94-
<span class="task-description"><span>Do exercises #todo #health</span></span>
95-
<span class="task-id"><span>🆔 abcdef</span></span>
96-
<span class="task-dependsOn"><span>⛔ 123456,abc123</span></span>
97-
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
98-
<span class="task-recurring"><span>🔁 every day when done</span></span>
99-
<span class="task-onCompletion"><span>🏁 delete</span></span>
100-
<span
101-
class="task-created"
88+
<div>
89+
<ul class="contains-task-list plugin-tasks-query-result">
90+
<li
91+
class="task-list-item plugin-tasks-list-item"
92+
data-task-priority="medium"
10293
data-task-created="past-4d"
103-
title="Click to edit created date, Right-click for more options">
104-
<span>➕ 2023-07-01</span>
105-
</span>
106-
<span class="task-start" data-task-start="past-3d" title="Click to edit start date, Right-click for more options">
107-
<span>🛫 2023-07-02</span>
108-
</span>
109-
<span
110-
class="task-scheduled"
94+
data-task-start="past-3d"
11195
data-task-scheduled="past-2d"
112-
title="Click to edit scheduled date, Right-click for more options">
113-
<span>⏳ 2023-07-03</span>
114-
</span>
115-
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
116-
<span>📅 2023-07-04</span>
117-
</span>
118-
<span
119-
class="task-cancelled"
96+
data-task-due="past-1d"
12097
data-task-cancelled="future-1d"
121-
title="Click to edit cancelled date, Right-click for more options">
122-
<span>❌ 2023-07-06</span>
123-
</span>
124-
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
125-
<span>✅ 2023-07-05</span>
126-
</span>
127-
<span class="task-block-link"><span>^dcf64c</span></span>
128-
</span>
129-
</li>
98+
data-task-done="today"
99+
data-task=""
100+
data-line="0"
101+
data-task-status-name="Todo"
102+
data-task-status-type="TODO">
103+
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
104+
<span class="tasks-list-text">
105+
<span class="task-description"><span>Do exercises #todo #health</span></span>
106+
<span class="task-id"><span>🆔 abcdef</span></span>
107+
<span class="task-dependsOn"><span>⛔ 123456,abc123</span></span>
108+
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
109+
<span class="task-recurring"><span>🔁 every day when done</span></span>
110+
<span class="task-onCompletion"><span>🏁 delete</span></span>
111+
<span
112+
class="task-created"
113+
data-task-created="past-4d"
114+
title="Click to edit created date, Right-click for more options">
115+
<span>➕ 2023-07-01</span>
116+
</span>
117+
<span
118+
class="task-start"
119+
data-task-start="past-3d"
120+
title="Click to edit start date, Right-click for more options">
121+
<span>🛫 2023-07-02</span>
122+
</span>
123+
<span
124+
class="task-scheduled"
125+
data-task-scheduled="past-2d"
126+
title="Click to edit scheduled date, Right-click for more options">
127+
<span>⏳ 2023-07-03</span>
128+
</span>
129+
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
130+
<span>📅 2023-07-04</span>
131+
</span>
132+
<span
133+
class="task-cancelled"
134+
data-task-cancelled="future-1d"
135+
title="Click to edit cancelled date, Right-click for more options">
136+
<span>❌ 2023-07-06</span>
137+
</span>
138+
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
139+
<span>✅ 2023-07-05</span>
140+
</span>
141+
<span class="task-block-link"><span>^dcf64c</span></span>
142+
</span>
143+
<span class="task-extras">
144+
<span class="tasks-urgency">18.157</span>
145+
<span class="tasks-backlink">
146+
(
147+
<a rel="noopener" target="_blank" class="internal-link">fileName &gt; My Header</a>
148+
)
149+
</span>
150+
<a class="tasks-edit" title="Edit task" href="#"></a>
151+
<a class="tasks-postpone" title="ℹ️ Due tomorrow, on Thu 6th Jul (right-click for more options)"></a>
152+
</span>
153+
</li>
154+
</ul>
155+
<div class="task-count">1 task</div>
156+
</div>
130157
```
131158
<!-- endSnippet -->
132159

133160
### Sample HTML: Short mode
134161

135-
Here is the same task in [[Layout#Short Mode|short mode]]. The only difference is that any text values after Tasks emoji are omitted:
162+
Here is the same Tasks search in [[Layout#Short Mode|short mode]].
163+
164+
The differences from full mode are:
165+
166+
- the `ul` has an extra class `tasks-layout-short-mode`,
167+
- any text values after Tasks emoji are omitted,
168+
- the backlink is shorter and has an extra class `internal-link-short-mode`,
169+
- the postpone button has an extra class `tasks-postpone-short-mode`.
136170

137171
> [!Note]
138-
> The below does not (yet) show the "Task extras".
172+
> In Reading Mode:
139173
>
140-
<!-- snippet: TaskLineRenderer.test.Visualise_HTML_Full_task_-_short_mode.approved.html -->
174+
> - all the classes and data inside the `li` are available,
175+
> - and none of the "Task extras" content is available.
176+
177+
<!-- snippet: QueryResultsRenderer.test.QueryResultsRenderer_tests_fully_populated_task_-_short_mode.approved.html -->
141178
```html
142179
<!--
143180
- [ ] Do exercises #todo #health 🆔 abcdef ⛔ 123456,abc123 🔼 🔁 every day when done 🏁 delete ➕ 2023-07-01 🛫 2023-07-02 ⏳ 2023-07-03 📅 2023-07-04 ❌ 2023-07-06 ✅ 2023-07-05 ^dcf64c
144181
-->
145182

146-
<li
147-
class="task-list-item plugin-tasks-list-item"
148-
data-task-priority="medium"
149-
data-task-created="past-4d"
150-
data-task-start="past-3d"
151-
data-task-scheduled="past-2d"
152-
data-task-due="past-1d"
153-
data-task-cancelled="future-1d"
154-
data-task-done="today"
155-
data-task=""
156-
data-line="0"
157-
data-task-status-name="Todo"
158-
data-task-status-type="TODO">
159-
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
160-
<span class="tasks-list-text">
161-
<span class="task-description"><span>Do exercises #todo #health</span></span>
162-
<span class="task-id"><span>🆔</span></span>
163-
<span class="task-dependsOn"><span>⛔</span></span>
164-
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
165-
<span class="task-recurring"><span>🔁</span></span>
166-
<span class="task-onCompletion"><span>🏁</span></span>
167-
<span
168-
class="task-created"
183+
<div>
184+
<ul class="contains-task-list plugin-tasks-query-result tasks-layout-short-mode">
185+
<li
186+
class="task-list-item plugin-tasks-list-item"
187+
data-task-priority="medium"
169188
data-task-created="past-4d"
170-
title="Click to edit created date, Right-click for more options">
171-
<span>➕</span>
172-
</span>
173-
<span class="task-start" data-task-start="past-3d" title="Click to edit start date, Right-click for more options">
174-
<span>🛫</span>
175-
</span>
176-
<span
177-
class="task-scheduled"
189+
data-task-start="past-3d"
178190
data-task-scheduled="past-2d"
179-
title="Click to edit scheduled date, Right-click for more options">
180-
<span>⏳</span>
181-
</span>
182-
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
183-
<span>📅</span>
184-
</span>
185-
<span
186-
class="task-cancelled"
191+
data-task-due="past-1d"
187192
data-task-cancelled="future-1d"
188-
title="Click to edit cancelled date, Right-click for more options">
189-
<span>❌</span>
190-
</span>
191-
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
192-
<span>✅</span>
193-
</span>
194-
<span class="task-block-link"><span>^dcf64c</span></span>
195-
</span>
196-
</li>
193+
data-task-done="today"
194+
data-task=""
195+
data-line="0"
196+
data-task-status-name="Todo"
197+
data-task-status-type="TODO">
198+
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
199+
<span class="tasks-list-text">
200+
<span class="task-description"><span>Do exercises #todo #health</span></span>
201+
<span class="task-id"><span>🆔</span></span>
202+
<span class="task-dependsOn"><span>⛔</span></span>
203+
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
204+
<span class="task-recurring"><span>🔁</span></span>
205+
<span class="task-onCompletion"><span>🏁</span></span>
206+
<span
207+
class="task-created"
208+
data-task-created="past-4d"
209+
title="Click to edit created date, Right-click for more options">
210+
<span>➕</span>
211+
</span>
212+
<span
213+
class="task-start"
214+
data-task-start="past-3d"
215+
title="Click to edit start date, Right-click for more options">
216+
<span>🛫</span>
217+
</span>
218+
<span
219+
class="task-scheduled"
220+
data-task-scheduled="past-2d"
221+
title="Click to edit scheduled date, Right-click for more options">
222+
<span>⏳</span>
223+
</span>
224+
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
225+
<span>📅</span>
226+
</span>
227+
<span
228+
class="task-cancelled"
229+
data-task-cancelled="future-1d"
230+
title="Click to edit cancelled date, Right-click for more options">
231+
<span>❌</span>
232+
</span>
233+
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
234+
<span>✅</span>
235+
</span>
236+
<span class="task-block-link"><span>^dcf64c</span></span>
237+
</span>
238+
<span class="task-extras">
239+
<span class="tasks-urgency">18.157</span>
240+
<span class="tasks-backlink">
241+
<a rel="noopener" target="_blank" class="internal-link internal-link-short-mode">🔗</a>
242+
</span>
243+
<a class="tasks-edit" title="Edit task" href="#"></a>
244+
<a
245+
class="tasks-postpone tasks-postpone-short-mode"
246+
title="ℹ️ Due tomorrow, on Thu 6th Jul (right-click for more options)"></a>
247+
</span>
248+
</li>
249+
</ul>
250+
<div class="task-count">1 task</div>
251+
</div>
197252
```
198253
<!-- endSnippet -->
199254

@@ -216,8 +271,10 @@ The generic classes are:
216271
- `task-cancelled`
217272
- `task-done`
218273
- `task-recurring`
274+
- `task-onCompletion`
219275
- `task-id`
220276
- `task-dependsOn`
277+
- `task-block-link`
221278

222279
In addition to the generic classes, there are [**data attributes**](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) that represent the content of the various task components.
223280

‎src/Renderer/QueryResultsRenderer.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -409,7 +409,9 @@ export class QueryResultsRenderer {
409409

410410
private addUrgency(listItem: HTMLElement, task: Task) {
411411
const text = new Intl.NumberFormat().format(task.urgency);
412-
listItem.createSpan({ text, cls: 'tasks-urgency' });
412+
const span = createAndAppendElement('span', listItem);
413+
span.textContent = text;
414+
span.classList.add('tasks-urgency');
413415
}
414416

415417
/**

0 commit comments

Comments
 (0)