Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add the "Tasks extras" and other improvements to Styling docs #3198

Merged
merged 7 commits into from
Nov 22, 2024
Merged

docs: Add the "Tasks extras" and other improvements to Styling docs #3198

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
50ca871
docs: Add some recent fields to the Styling docs
claremacrae Nov 22, 2024
ba14a6d
refactor: ! Rework rendering of urgency so it can be called from tests.
claremacrae Nov 22, 2024
937ec8d
test: - Update the fake date in QueryResultsRenderer.test.ts
claremacrae Nov 22, 2024
3e1cb90
test: - Show CSS class used when rendering urgency.
claremacrae Nov 22, 2024
5dbf7e8
test: - Add QueryResultsRenderer approval test for short-mode
claremacrae Nov 22, 2024
b271a03
test: - QueryResultsRenderer.test.ts now includes markdown in approve…
claremacrae Nov 22, 2024
69f6ea5
docs: Add the "Tasks extras" to the Sample HTML in Styling docs.
claremacrae Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
261 changes: 159 additions & 102 deletions docs/Advanced/Styling.md
View file
Open in desktop
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
Open in desktop
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