You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* fix: Rename the status settings arrays.
This is partly to avoid needing to implement
backwards-compatibility of reading settings for
settings written by the 2 test builds.
And partly because I want to reserve use of 'status type'
to the new status.type instructions (DONE, TODO, IN_PROGRESS, CANCELLED)
* fix: Remove 'Status Types' references in settings GUI.
* fix: Clarify a reference to 'Status type' in docs
* docs: Add introduction and promote related pages
* docs: More info on sections in settings pane
* test: Update documentation snippets for Core/Custom split
* feat: Improve wording on Edit Status modal
* docs: Interim commit of statuses.md
* docs: Update statuses screenshots
* docs: Fix incorrect image
* docs: Mark up interesting sections of images
* docs: Add introduction and promote related pages
* test: Status Character -> Status Symbol in docs tables
Also, re-ordered the columns so that the two symbols columns are adjacent.
I spotted an error in doing so.
* fix: The Next Symbol for DONE was wrong in both theme collections
* docs: Interim commit of statuses docs
* test: Add some more snippets of status scenarios
* docs: Add 'What can Statuses do?' section
* docs: Update create-or-edit-task.md
* docs: Document recurrence and done dates
* docs: More info on status type.
* docs: Add some sample images to the statuses page.
* fix: Add missing full-stop to CustomStatusModal
* docs: Group some headings together for readability
* docs: Reorder the status HowTos
* docs: Add a standard snippet with links between status docs
* docs: Move description of Statuses Settings to dedicated page
And added new content it it.
* docs: Add editing-a-status.md
* docs: Add 'Example Statuses' page.
* docs: Add 'Core Statuses' page
* docs: Add 'Custom Statuses' page
* docs: Add 'Status Types' page
* docs: Refine Statuses page
* docs: More readable table of status.type behaviour
* docs: Add 'Limitations and Issues' section to status-settings.md
* docs: Improve 'Broad steps to understand and set up Statuses' callout
* docs: Review and update style-custom-statuses.md
* docs: Review and update set-up-custom-statuses.md
* docs: Remove some clutter
* docs: Document 'Unknown Statuses'
* fix: ITS/slrvb now use IN_PROGRESS for 'Doing'
* docs: Add 'Ignoring clicks and toggles'
* docs: Set the version number for custom statuses feature
* docs: Credit the source of 'help message' recommendation.
* vault: Revert accidental setting of theme
* vault: Revert accidental commit of files in sample vault
This page provides an overview of using Tasks with **Custom Statuses**, which some people refer to as Custom Checkboxes or Alternative/Alternate Checkboxes.
30
+
31
+
Here's the kind of thing that you can do:
32
+
33
+
34
+
35
+
### Related pages
36
+
37
+
Once you're comfortable with the background information in this page, further information is available in the following related pages.
38
+
39
+
-[How to style custom statuses]({{ site.baseurl }}{% link how-to/style-custom-statuses.md %}).
40
+
-[How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %}).
41
+
-[Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %}).
42
+
43
+
---
44
+
45
+
## Do I need to set up statuses?
46
+
47
+
If you are happy with all your tasks beginning with `[ ]` and `[x]`, then **no**, you can just ignore Tasks' Statuses facility.
48
+
49
+
---
50
+
51
+
## About Statuses
52
+
53
+
### What IS a Status?
54
+
55
+
Every task in the Tasks plugin now has a Status.
56
+
57
+
Status is just Tasks' name for:
58
+
59
+
1. the character (`symbol`) between the `[` and `]` in a task line
60
+
2. AND some options that you can customise, to tell tasks how to treat all your tasks with that character.
61
+
62
+
Some obsidian users call them other names, like 'Alternative Checkboxes', but that is more about how they are displayed, rather than about the actual *behaviour* of tasks with particular statuses.
63
+
64
+
### What's IN a Status?
65
+
66
+
These are the options that you can modify, for each status:
67
+
68
+
69
+
70
+
Here is some more detail.
71
+
72
+
-**Status Symbol**
26
73
- the single character in the `[]` at the start of the task.
27
-
-`status name`
74
+
- this character will control what how tasks are rendered by your Theme or CSS Snippet.
75
+
-**Status Name**
28
76
- a name for the status.
29
77
- this is flexible: for custom statuses, you can use any name you wish.
30
78
- is searchable with `status.name`, for example `status.name includes My custom in-progress status`.
31
-
-`next status symbol`
79
+
-**Next Status Symbol**
32
80
- the status symbol to use when the task is toggled.
33
-
-`status type`
81
+
-**Status Type**
34
82
- one of `TODO`, `IN_PROGRESS`, `DONE`, `CANCELLED`, `NON_TASK`.
35
-
- Tasks needs to know the type of each custom status, so that it knows how to treat them when searching, and what to do when tasks with the status are toggled.
36
-
- is searchable with `status.type`, for example `status.type is IN_PROGRESS`.
37
-
- you can have any number of custom statuses with the same status type, and then search them conveniently with `status.type`
83
+
- Tasks needs to know the type of each status, so that it knows how to treat them when searching, and what to do when tasks with the status are toggled.
84
+
- types are searchable with `status.type`, for example `status.type is IN_PROGRESS`.
85
+
- Also available:
86
+
-`sort by status.type`
87
+
-`group by status.type`
88
+
- For more information, see [Status Types]({{ site.baseurl }}{% link getting-started/statuses/status-types.md %})
38
89
39
-
### Status Types
90
+
### Unknown Statuses
40
91
41
-
This table demonstrates the behaviour of each of the status types in Tasks.
42
-
Each column shows an example task with the given status type.
92
+
What happens if Tasks reads a line with a status symbol that it does not know about?
43
93
44
-
The tasks shown are purely examples for context. The `~` column is just an arbitrary example to show `NON_TASK`'s behaviour'. You can assign each of these types to any of your custom statuses.
94
+
All such tasks are given a status called `Unknown`, with these properties:
45
95
46
-
<!-- placeholder to force blank line before included text --><!-- include: DocsSamplesForStatuses.test.Status_Transitions status-types.approved.md -->
| Matches `status.name includes todo`| YES | no | no | no | no |
54
-
| Matches `status.type is TODO`| YES | no | no | no | no |
55
-
| Matches `status.name includes in progress`| no | YES | no | no | no |
56
-
| Matches `status.type is IN_PROGRESS`| no | YES | no | no | no |
57
-
| Matches `status.name includes done`| no | no | YES | no | no |
58
-
| Matches `status.type is DONE`| no | no | YES | no | no |
59
-
| Matches `status.name includes cancelled`| no | no | no | YES | no |
60
-
| Matches `status.type is CANCELLED`| no | no | no | YES | no |
61
-
| Matches `status.type is NON_TASK`| no | no | no | no | YES |
62
-
| Name for `group by status`| Todo | Done | Done | Done | Done |
63
-
| Name for `group by status.type`| 2 TODO | 1 IN_PROGRESS | 3 DONE | 4 CANCELLED | 5 NON_TASK |
64
-
| Name for `group by status.name`| Todo | In Progress | Done | Cancelled | My custom status |
103
+
### Done date, Recurrence and Statuses
65
104
66
-
<!-- placeholder to force blank line after included text --><!-- endInclude -->
105
+
It is the Task Status Type changing **to**`DONE` that controls when:
67
106
68
-
{: .warning }
69
-
The `group by` results of the above table are subject to change.
107
+
- tasks **gain** their Done dates (if Done dates are enabled in settings),
108
+
- new copies of recurring tasks are created.
70
109
71
-
## Standard Markdown task statuses
110
+
It is the Task Status Type changing **from**`DONE` that controls when:
72
111
73
-
Tasks have a status.
112
+
- tasks **lose** their Done dates (if Done dates are enabled in settings).
74
113
75
-
The convention in markdown is:
114
+
---
76
115
77
-
```text
78
-
- [ ] I am a task that is not yet done
79
-
- [x] I am a task that has been done
80
-
```
116
+
## What can Statuses do?
81
117
82
-
---
118
+
Now we have seen what is in a Status, what can we do with them?
83
119
84
-
## Tasks core task statuses
120
+
We can use them to control what Tasks does when a task's checkbox is clicked, or toggled.
85
121
86
-
{: .released }
87
-
Introduced in Tasks X.Y.Z
122
+
The [Example Statuses]({{ site.baseurl }}{% link getting-started/statuses/example-statuses.md %}) page has a variety of examples, for inspiration.
88
123
89
-
Tasks supports custom task statuses.
124
+
---
90
125
91
-
This table shows the statuses provided by default:
126
+
## More about Statuses
92
127
93
-
<!-- placeholder to force blank line before included text --><!-- include: DocsSamplesForStatuses.test.DefaultStatuses_core-statuses.approved.md -->
128
+
### Core Statuses
94
129
95
-
| Status Character | Status Name<br>`status.name includes...`<br>`sort by status.name`<br>`group by status.name`| Next Status Character | Status Type<br>`status.type is...`<br>`sort by status.type`<br>`group by status.type`| Needs Custom Styling |
See [Core Statuses]({{ site.baseurl }}{% link getting-started/statuses/core-statuses.md %}) to find out more.
109
142
110
-
Note that `Todo` is followed by `Done`, in order to preserve compatibility with earlier Tasks releases.
143
+
### Custom Statuses
111
144
112
-
{: .info }
113
-
These core statuses are currently read-only.
114
-
It will soon be possible to edit these custom statuses, and enable `Todo` -> `In Progress` -> `Done`.
145
+
Custom statuses represent any non-standard markdown tasks.
115
146
116
-
---
147
+
Here are some tasks with example custom statuses, that is, with non-standard characters between the `[` and `]`:
117
148
118
-
## Custom task statuses
149
+
```text
150
+
- [X] Checked
151
+
- [-] A dropped/cancelled task
152
+
- [?] A question
153
+
- [/] A Half Done/In-progress task
154
+
```
119
155
120
-
### First choose your styling scheme
156
+
They **require custom CSS styling or theming** on order to display correctly in Tasks blocks or Live Preview.
121
157
122
-
You can use any snippet or theme you wish. If you are already using a snippet or theme that supports "custom checkboxes", you should stick with that.
158
+
### What's the Big Deal?
123
159
124
-
If, however, you are using the default theme, or a theme that doesn't know style "custom checkboxes", you will need to pick one.
160
+
People have been using themes and CSS snippets to style custom checkboxes in Obsidian all along.
125
161
126
-
[Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %}) has a list of the ones that Tasks already has one-click support for, to help you choose.
162
+
What Tasks's custom statuses allow you to do is to **also customise the behaviour of your tasks**.
127
163
128
-
### Editing custom statuses
164
+
### Setting up Custom Statuses
129
165
130
-
Your choice of styling facility will determine which letters and characters you wish to you in your custom statuses.
166
+
<!-- force a blank line --><!-- include: snippet-statuses-overview.md -->
131
167
132
-
Then see [How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %}) for how to set up your custom statuses.
168
+
{: .info }
169
+
> Broad steps to understand and set up Statuses (or "Alternate Checkboxes"):
170
+
>
171
+
> - Understand what Statuses are:
172
+
> -[Statuses]({{ site.baseurl }}{% link getting-started/statuses.md %})
173
+
> -[Custom Statuses]({{ site.baseurl }}{% link getting-started/statuses/custom-statuses.md %})
174
+
> - Choose your status styling scheme: this will determine the names and symbols for your custom statuses:
175
+
> - Some common ones are shown in [Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %})
176
+
> - Set up your status styling scheme
177
+
> -[How to style custom statuses]({{ site.baseurl }}{% link how-to/style-custom-statuses.md %}).
178
+
> - Configure Tasks to use your custom statuses
179
+
> -[How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %})
180
+
> - Optionally, update your tasks searches to take advantage of the new flexibility
181
+
> -[Filters for Task Statuses]({{ site.baseurl }}{% link queries/filters.md %}#filters-for-task-statuses)
182
+
183
+
<!-- force a blank line --><!-- endInclude -->
133
184
134
-
{: .warning }
135
-
Remember to set up your chosen CSS Snippet or Theme before setting up the custom statuses.
185
+
---
136
186
137
187
## Using Statuses
138
188
@@ -164,12 +214,6 @@ For details, see [Filters for Task Statuses]({{ site.baseurl }}{% link queries/f
164
214
{: .info }
165
215
We envisage adding `status.symbol`.
166
216
167
-
## Related pages
168
-
169
-
-[How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %}).
170
-
-[How to style custom statuses]({{ site.baseurl }}{% link how-to/style-custom-statuses.md %}).
171
-
-[Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %}).
172
-
173
217
---
174
218
175
219
## Credit: Sytone and the 'Tasks SQL Powered' plugin
Note that `Todo` is followed by `Done`, in order to preserve compatibility with earlier Tasks releases.
41
+
42
+
{: .info }
43
+
You can edit the 'Todo' core status to make its Next Status Symbol be `/` and enable `Todo` -> `In Progress` -> `Done`, if you prefer.
44
+
45
+
## Editing core statuses
46
+
47
+
The only restriction on editing core statuses is that you cannot change their Status Symbols.
48
+
49
+
You are free to rename them, change their next character, and even change their Status Type, should you wish.
50
+
51
+
## Details
52
+
53
+
And this is how you can use them:
54
+
55
+
<!-- placeholder to force blank line before included text --><!-- include: DocsSamplesForStatuses.test.DefaultStatuses_core-statuses.approved.md -->
56
+
57
+
| Status Symbol | Next Status Symbol | Status Name<br>`status.name includes...`<br>`sort by status.name`<br>`group by status.name`| Status Type<br>`status.type is...`<br>`sort by status.type`<br>`group by status.type`| Needs Custom Styling |
58
+
| ----- | ----- | ----- | ----- | ----- |
59
+
|`space`|`x`| Todo |`TODO`| No |
60
+
|`x`|`space`| Done |`DONE`| No |
61
+
62
+
<!-- placeholder to force blank line after included text --><!-- endInclude -->
0 commit comments