Skip to content

Commit

Permalink
Merge pull request #3198 from obsidian-tasks-group/docs-for-styling
Browse files Browse the repository at this point in the history 
docs: Add the "Tasks extras" and other improvements to Styling docs
  • Loading branch information
@claremacrae
claremacrae authored Nov 22, 2024
2 parents 5650d36 + 69f6ea5 commit 848d8bb
Show file tree
Hide file tree
Showing 9 changed files with 301 additions and 120 deletions.
261 changes: 159 additions & 102 deletions docs/Advanced/Styling.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,16 @@ The Tasks plugin renders a task in the following structure (this refers to query
- Task description and tags (span class="task-description")
- Internal span
- Each tag in the description is wrapped in <a href class="tag" data-tag-name="[tag-name]">
- Task ID (span class="task-id")
- Internal span
- Task 'depends on' (span class="task-dependsOn")
- Internal span
- Task priority (span class="task-priority" + data-task-priority attribute)
- Internal span
- Task recurrence rule (span class="task-recurring")
- Internal span
- Task 'on completion' (span class="onCompletion")
- Internal span
- Task created date (span class="task-created" + data-task-created attribute)
- Internal span
- ... start date, scheduled date, due date, cancelled date and done date in this order
Expand All @@ -65,135 +71,184 @@ The reason for this additional internal span is that it allows CSS styles that c

### Sample HTML: Full mode

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

> [!Note]
> The below does not (yet) show the "Task extras".
> In Reading Mode:
>
> - all the classes and data inside the `li` are available,
> - and none of the "Task extras" content is available.
<!-- snippet: TaskLineRenderer.test.Visualise_HTML_Full_task_-_full_mode.approved.html -->
<!-- snippet: QueryResultsRenderer.test.QueryResultsRenderer_tests_fully_populated_task.approved.html -->
```html
<!--
- [ ] 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
-->

<li
class="task-list-item plugin-tasks-list-item"
data-task-priority="medium"
data-task-created="past-4d"
data-task-start="past-3d"
data-task-scheduled="past-2d"
data-task-due="past-1d"
data-task-cancelled="future-1d"
data-task-done="today"
data-task=""
data-line="0"
data-task-status-name="Todo"
data-task-status-type="TODO">
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
<span class="tasks-list-text">
<span class="task-description"><span>Do exercises #todo #health</span></span>
<span class="task-id"><span>🆔 abcdef</span></span>
<span class="task-dependsOn"><span>⛔ 123456,abc123</span></span>
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
<span class="task-recurring"><span>🔁 every day when done</span></span>
<span class="task-onCompletion"><span>🏁 delete</span></span>
<span
class="task-created"
<div>
<ul class="contains-task-list plugin-tasks-query-result">
<li
class="task-list-item plugin-tasks-list-item"
data-task-priority="medium"
data-task-created="past-4d"
title="Click to edit created date, Right-click for more options">
<span>➕ 2023-07-01</span>
</span>
<span class="task-start" data-task-start="past-3d" title="Click to edit start date, Right-click for more options">
<span>🛫 2023-07-02</span>
</span>
<span
class="task-scheduled"
data-task-start="past-3d"
data-task-scheduled="past-2d"
title="Click to edit scheduled date, Right-click for more options">
<span>⏳ 2023-07-03</span>
</span>
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
<span>📅 2023-07-04</span>
</span>
<span
class="task-cancelled"
data-task-due="past-1d"
data-task-cancelled="future-1d"
title="Click to edit cancelled date, Right-click for more options">
<span>❌ 2023-07-06</span>
</span>
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
<span>✅ 2023-07-05</span>
</span>
<span class="task-block-link"><span>^dcf64c</span></span>
</span>
</li>
data-task-done="today"
data-task=""
data-line="0"
data-task-status-name="Todo"
data-task-status-type="TODO">
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
<span class="tasks-list-text">
<span class="task-description"><span>Do exercises #todo #health</span></span>
<span class="task-id"><span>🆔 abcdef</span></span>
<span class="task-dependsOn"><span>⛔ 123456,abc123</span></span>
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
<span class="task-recurring"><span>🔁 every day when done</span></span>
<span class="task-onCompletion"><span>🏁 delete</span></span>
<span
class="task-created"
data-task-created="past-4d"
title="Click to edit created date, Right-click for more options">
<span>➕ 2023-07-01</span>
</span>
<span
class="task-start"
data-task-start="past-3d"
title="Click to edit start date, Right-click for more options">
<span>🛫 2023-07-02</span>
</span>
<span
class="task-scheduled"
data-task-scheduled="past-2d"
title="Click to edit scheduled date, Right-click for more options">
<span>⏳ 2023-07-03</span>
</span>
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
<span>📅 2023-07-04</span>
</span>
<span
class="task-cancelled"
data-task-cancelled="future-1d"
title="Click to edit cancelled date, Right-click for more options">
<span>❌ 2023-07-06</span>
</span>
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
<span>✅ 2023-07-05</span>
</span>
<span class="task-block-link"><span>^dcf64c</span></span>
</span>
<span class="task-extras">
<span class="tasks-urgency">18.157</span>
<span class="tasks-backlink">
(
<a rel="noopener" target="_blank" class="internal-link">fileName &gt; My Header</a>
)
</span>
<a class="tasks-edit" title="Edit task" href="#"></a>
<a class="tasks-postpone" title="ℹ️ Due tomorrow, on Thu 6th Jul (right-click for more options)"></a>
</span>
</li>
</ul>
<div class="task-count">1 task</div>
</div>
```
<!-- endSnippet -->

### Sample HTML: Short mode

Here is the same task in [[Layout#Short Mode|short mode]]. The only difference is that any text values after Tasks emoji are omitted:
Here is the same Tasks search in [[Layout#Short Mode|short mode]].

The differences from full mode are:

- the `ul` has an extra class `tasks-layout-short-mode`,
- any text values after Tasks emoji are omitted,
- the backlink is shorter and has an extra class `internal-link-short-mode`,
- the postpone button has an extra class `tasks-postpone-short-mode`.

> [!Note]
> The below does not (yet) show the "Task extras".
> In Reading Mode:
>
<!-- snippet: TaskLineRenderer.test.Visualise_HTML_Full_task_-_short_mode.approved.html -->
> - all the classes and data inside the `li` are available,
> - and none of the "Task extras" content is available.
<!-- snippet: QueryResultsRenderer.test.QueryResultsRenderer_tests_fully_populated_task_-_short_mode.approved.html -->
```html
<!--
- [ ] 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
-->

<li
class="task-list-item plugin-tasks-list-item"
data-task-priority="medium"
data-task-created="past-4d"
data-task-start="past-3d"
data-task-scheduled="past-2d"
data-task-due="past-1d"
data-task-cancelled="future-1d"
data-task-done="today"
data-task=""
data-line="0"
data-task-status-name="Todo"
data-task-status-type="TODO">
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
<span class="tasks-list-text">
<span class="task-description"><span>Do exercises #todo #health</span></span>
<span class="task-id"><span>🆔</span></span>
<span class="task-dependsOn"><span>⛔</span></span>
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
<span class="task-recurring"><span>🔁</span></span>
<span class="task-onCompletion"><span>🏁</span></span>
<span
class="task-created"
<div>
<ul class="contains-task-list plugin-tasks-query-result tasks-layout-short-mode">
<li
class="task-list-item plugin-tasks-list-item"
data-task-priority="medium"
data-task-created="past-4d"
title="Click to edit created date, Right-click for more options">
<span>➕</span>
</span>
<span class="task-start" data-task-start="past-3d" title="Click to edit start date, Right-click for more options">
<span>🛫</span>
</span>
<span
class="task-scheduled"
data-task-start="past-3d"
data-task-scheduled="past-2d"
title="Click to edit scheduled date, Right-click for more options">
<span>⏳</span>
</span>
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
<span>📅</span>
</span>
<span
class="task-cancelled"
data-task-due="past-1d"
data-task-cancelled="future-1d"
title="Click to edit cancelled date, Right-click for more options">
<span>❌</span>
</span>
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
<span>✅</span>
</span>
<span class="task-block-link"><span>^dcf64c</span></span>
</span>
</li>
data-task-done="today"
data-task=""
data-line="0"
data-task-status-name="Todo"
data-task-status-type="TODO">
<input class="task-list-item-checkbox" type="checkbox" title="Right-click for options" data-line="0" />
<span class="tasks-list-text">
<span class="task-description"><span>Do exercises #todo #health</span></span>
<span class="task-id"><span>🆔</span></span>
<span class="task-dependsOn"><span>⛔</span></span>
<span class="task-priority" data-task-priority="medium"><span>🔼</span></span>
<span class="task-recurring"><span>🔁</span></span>
<span class="task-onCompletion"><span>🏁</span></span>
<span
class="task-created"
data-task-created="past-4d"
title="Click to edit created date, Right-click for more options">
<span>➕</span>
</span>
<span
class="task-start"
data-task-start="past-3d"
title="Click to edit start date, Right-click for more options">
<span>🛫</span>
</span>
<span
class="task-scheduled"
data-task-scheduled="past-2d"
title="Click to edit scheduled date, Right-click for more options">
<span>⏳</span>
</span>
<span class="task-due" data-task-due="past-1d" title="Click to edit due date, Right-click for more options">
<span>📅</span>
</span>
<span
class="task-cancelled"
data-task-cancelled="future-1d"
title="Click to edit cancelled date, Right-click for more options">
<span>❌</span>
</span>
<span class="task-done" data-task-done="today" title="Click to edit done date, Right-click for more options">
<span>✅</span>
</span>
<span class="task-block-link"><span>^dcf64c</span></span>
</span>
<span class="task-extras">
<span class="tasks-urgency">18.157</span>
<span class="tasks-backlink">
<a rel="noopener" target="_blank" class="internal-link internal-link-short-mode">🔗</a>
</span>
<a class="tasks-edit" title="Edit task" href="#"></a>
<a
class="tasks-postpone tasks-postpone-short-mode"
title="ℹ️ Due tomorrow, on Thu 6th Jul (right-click for more options)"></a>
</span>
</li>
</ul>
<div class="task-count">1 task</div>
</div>
```
<!-- endSnippet -->

Expand All @@ -216,8 +271,10 @@ The generic classes are:
- `task-cancelled`
- `task-done`
- `task-recurring`
- `task-onCompletion`
- `task-id`
- `task-dependsOn`
- `task-block-link`

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.

Expand Down
4 changes: 3 additions & 1 deletion src/Renderer/QueryResultsRenderer.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -409,7 +409,9 @@ export class QueryResultsRenderer {

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

/**
Expand Down
Loading

0 comments on commit 848d8bb

Please sign in to comment.