Merge pull request #3320 from obsidian-tasks-group/docs-query-file-defaults

docs: Major enhancements to Query File Defaults docs

Author: claremacrae

docs/.obsidian/graph.json

@@ -1,6 +1,6 @@
 {
   "collapse-filter": false,
-  "search": "-path:_meta -file:README",
+  "search": "-path:_meta -file:README -file:CHANGELOG -file:About -file:\"Quick Reference\" -file:\"Known Limitations\"",
   "showTags": false,
   "showAttachments": false,
   "hideUnresolved": false,
@@ -50,16 +50,16 @@
       }
     }
   ],
-  "collapse-display": true,
-  "showArrow": false,
-  "textFadeMultiplier": 0,
-  "nodeSizeMultiplier": 1,
+  "collapse-display": false,
+  "showArrow": true,
+  "textFadeMultiplier": -3,
+  "nodeSizeMultiplier": 1.54097073518915,
   "lineSizeMultiplier": 1,
   "collapse-forces": false,
   "centerStrength": 0.518713248970312,
   "repelStrength": 16.8733723958333,
   "linkStrength": 1,
   "linkDistance": 319,
-  "scale": 1.3626171834729273,
+  "scale": 0.27373780164375944,
   "close": false
 }

docs/How To/About How Tos.md

@@ -26,3 +26,7 @@ These How-to guides take you through the steps required to solve real-world prob
 - [[How to style backlinks]]
 - [[How to style buttons]]
 - [[Show tasks in a calendar]]
+
+## Advanced Techniques
+
+- [[Make a query user interface]]

docs/How To/Make a query user interface.md

@@ -0,0 +1,75 @@
+---
+publish: true
+---
+
+# How to make a query user interface
+
+<span class="related-pages">#plugin/meta-bind</span>
+
+## Meta Bind Tasks User Interface to Query File Defaults
+
+> [!released]
+> Query File Defaults were introduced in Tasks X.Y.Z.
+
+The [[Meta Bind Plugin]] allows Obsidian users to make their notes interactive with inline input fields, metadata displays, and buttons.
+
+We can combine:
+
+1. The Tasks plugin's [[Query File Defaults]] facility, based on specific properties named `TQ_*`,
+2. The Meta Bind plugin's ability to create widgets to modify note properties.
+
+... to create a User Interface to easily adjust your Tasks searches, that can:
+
+- show and hide each of the task properties,
+- enable or disable other search features, such as nested tasks, short mode, backlink and buttons,
+- and allow arbitrary extra instructions to be added:
+
+![Meta Bind widgets to edit Query File Defaults](../images/query-file-defaults-meta-bind-controls.png)
+<span class="caption">Meta Bind widgets to edit Query File Defaults</span>
+
+## How to set it up
+
+Follow these steps, which assume you have already [turned off Obsidian's Restricted mode](https://help.obsidian.md/Extending+Obsidian/Plugin+security):
+
+1. Install and enable the [Meta Bind](https://obsidian.md/plugins?search=Meta%20Bind) plugin.
+2. Copy the Markdown code-block below.
+3. Paste the Markdown in to a note in Obsidian that has one or more Tasks searches.
+4. Switch to Live Preview or Reading modes, to see the widgets.
+5. After experimenting, delete any labels and widgets that you do not need.
+
+<!-- snippet: DocsSamplesForDefaults.test.DocsSamplesForDefaults_meta-bind-widgets-snippet.approved.md -->
+```md
+short mode: `INPUT[toggle:TQ_short_mode]`
+tree: `INPUT[toggle:TQ_show_tree]`
+tags: `INPUT[toggle:TQ_show_tags]`
+id: `INPUT[toggle:TQ_show_id]` depends on: `INPUT[toggle:TQ_show_depends_on]`
+priority: `INPUT[toggle:TQ_show_priority]`
+recurrence rule: `INPUT[toggle:TQ_show_recurrence_rule]` on completion: `INPUT[toggle:TQ_show_on_completion]`
+start date: `INPUT[toggle:TQ_show_start_date]` scheduled date: `INPUT[toggle:TQ_show_scheduled_date]` due date: `INPUT[toggle:TQ_show_due_date]`
+created date: `INPUT[toggle:TQ_show_created_date]` cancelled date: `INPUT[toggle:TQ_show_cancelled_date]` done date: `INPUT[toggle:TQ_show_done_date]`
+urgency: `INPUT[toggle:TQ_show_urgency]`
+backlink: `INPUT[toggle:TQ_show_backlink]`
+edit button: `INPUT[toggle:TQ_show_edit_button]` postpone button: `INPUT[toggle:TQ_show_postpone_button]`
+task count: `INPUT[toggle:TQ_show_task_count]`
+extra instructions: `INPUT[textArea:TQ_extra_instructions]`
+explain: `INPUT[toggle:TQ_explain]`
+```
+<!-- endSnippet -->
+
+## Why provide this?
+
+Some might say that this mechanism is perhaps a little awkward, and wouldn't it be good for Tasks to provide its own user interface?
+
+We agree, and we are tracking this in [issue #2579](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2579).
+
+However, the development process went something like this:
+
+1. Teach Tasks to use [[Obsidian Properties#Using Query Properties in Searches|query properties in searches]].
+2. Discover that generating Tasks instructions from simple `true`/`false` properties required some really rather complex JavaScript code inside user queries, which was:
+    - horrible for us to document,
+    - horrible for users to have to copy and understand, cluttering up their searches.
+3. Implement the [[Query File Defaults]] mechanism.
+4. Discover that using Obsidian's [Properties view](https://help.obsidian.md/Plugins/Properties+view) core plugin was *sort-of-OK*, but:
+    - it was a little tedious opening and closing that side-panel,
+    - it does not do a very good job editing multi-line strings, which are useful with `TQ_extra_instructions`.
+5. Experiment with [[Meta Bind Plugin]] and decide this use of it is a relatively easy and big step forward, until such time as Obsidian has its own user interface!

docs/Other Plugins/About Other Plugins.md

@@ -12,6 +12,8 @@ aliases:
 
 - [[Dataview]]
 - [[Kanban Plugin]]
+- [[Meta Bind Plugin]]
+  - Easily modify the [[layout]] of your Tasks searches, without having to edit instructions.
 - [[QuickAdd]]
   - Using the Quickadd plugin to help create tasks
 

docs/Other Plugins/Meta Bind Plugin.md

@@ -0,0 +1,13 @@
+---
+publish: true
+---
+
+# Meta Bind Plugin
+
+<span class="related-pages">#plugin/meta-bind</span>
+
+## Introduction
+
+The [Meta Bind](https://github.com/mProjectsCode/obsidian-meta-bind-plugin) allows Obsidian users to make their notes interactive with inline input fields, metadata displays, and buttons.
+
+It can even be used to create [[Make a query user interface|simple user interface to customise Tasks queries]].

docs/Queries/About Queries.md

@@ -46,27 +46,55 @@ In the following sections we will explain all the various options that are avail
 ### Searching tasks - Basics
 
 - [[Filters]]
+  - Control which tasks are shown in Tasks Queries.
 - [[Explaining Queries]]
+  - Get Tasks to show how your query is interpreted, so you can check your instructions.
 - [[Comments]]
+  - Write notes to your future self, explaining your Queries.
 - [[Examples]]
+  - A selection of some of the more commonly used search instructions.
 
-### Searching tasks - Advanced
+### Searching tasks - Re-using instructions
 
 - [[Global Query]]
+  - Set a global query in the settings that Tasks will add to the start of all the Queries in your vault.
+- [[Query File Defaults]]
+  - Set properties in note frontmatter, to instruct tasks to add instructions to all the Queries in that file.
+
+> [!tip] The Query is assembled like this:
+>
+> 1. Get the **Global Query**, from settings.
+>     - This will be discarded if `ignore global query` is present in any of the following locations.
+> 2. Append the **Query File Defaults**, based on the Query file's properties.
+> 3. Append the **Query Source**, from the `tasks` block.
+>
+> Later [[Layout]] instructions will override earlier ones.
+
+### Searching tasks - Advanced
+
 - [[Combining Filters]]
+  - How to use `AND`, `OR` and `NOT`.
+  - Warning: Make sure you understand where to place brackets in these instructions!
 - [[Regular Expressions]]
+  - A complex but powerful alternative to simple text searches.
 - [[Line Continuations]]
+  - Break long instructions up across multiple lines for readability.
 
 ### Viewing the results
 
 - [[Backlinks]]
+  - Navigate from tasks in Queries back to the source Markdown line.
 
 ### Controlling the display
 
 - [[Limiting]]
+  - Control the maximum number of tasks displayed in a Query's results, and in each group of tasks.
 - [[Sorting]]
+  - Define the sort order.
 - [[Grouping]]
+  - Define headings to group tasks.
 - [[Layout]]
+  - Hide and show individual elements of the Query results.
 
 ## Query Tips
 

docs/Queries/Explaining Queries.md

@@ -163,6 +163,8 @@ Explanation of this Tasks code block query:
 ```
 <!-- endSnippet -->
 
+## Advanced Examples
+
 ### Global Query is displayed
 
 > [!released]
@@ -208,6 +210,67 @@ Explanation of this Tasks code block query:
 ```
 <!-- endSnippet -->
 
+### Query File Defaults are displayed
+
+> [!released]
+> The [[Query File Defaults]] facility was introduced in Tasks X.Y.Z.
+
+> [!info]- What are Query File Defaults?
+> You can use [[Query File Defaults]] facility to modify Tasks searches, by adding certain pre-defined property value's the query file's frontmatter.
+>
+> For example, setting `TQ_short_mode` to `true` makes Tasks insert the following line at the start of the query:
+>
+> ```text
+> short mode
+> ```
+
+Consider this Markdown note:
+
+<!-- placeholder to force blank line before included text --><!-- include: DocsSamplesForExplain.test.explain_query_file_defaults_file_content.approved.md -->
+
+````text
+---
+TQ_extra_instructions: |-
+  folder includes {{query.file.folder}}
+  not done
+TQ_short_mode: true
+TQ_show_tree: true
+---
+
+```tasks
+explain
+```
+````
+
+<!-- placeholder to force blank line after included text --><!-- endInclude -->
+
+The Tasks results begin would the following:
+
+<!-- snippet: DocsSamplesForExplain.test.explain_query_file_defaults_explanation.approved.explanation.text -->
+```text
+Explanation of the Query File Defaults (from properties/frontmatter in the query's file):
+
+  folder includes {{query.file.folder}} =>
+  folder includes Test Data/
+
+  not done
+
+Explanation of this Tasks code block query:
+
+  No filters supplied. All tasks will match the query.
+```
+<!-- endSnippet -->
+
+> [!info]- Why are the generated layout instructions not visible?
+> The Query File Defaults will have generated these instructions:
+>
+> ```text
+> short mode
+> show tree
+> ```
+>
+> Currently, the `explain` output does not display [[layout]] instructions.  We are tracking this in [issue #2093](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2093).
+
 ### Placeholder values are expanded
 
 > [!released]

docs/Queries/Layout.md

@@ -151,7 +151,7 @@ For example:
     ```tasks
     no due date
     path includes GitHub
-    
+
     hide recurrence rule
     hide task count
     hide backlink
@@ -190,3 +190,38 @@ Example:
     ```
 
 This can be reversed with [[#Full Mode]].
+
+## Alternative to typing layout instructions
+
+> [!released]
+> [[Query File Defaults]] were introduced in Tasks X.Y.Z.
+
+All the layout instructions in this page can be generated for you automatically, by putting certain file properties (called 'Query File Defaults') in the file containing the query.
+
+For example, suppose the file containing our query begins with the following:
+
+<!-- snippet: DocsSamplesForDefaults.test.DocsSamplesForDefaults_demo-short-mode_yaml.approved.yaml -->
+```yaml
+---
+TQ_short_mode: true
+---
+```
+<!-- endSnippet -->
+
+All Tasks code blocks in that file will then have this content automatically inserted at their start:
+
+<!-- snippet: DocsSamplesForDefaults.test.DocsSamplesForDefaults_demo-short-mode_instructions.approved.txt -->
+```txt
+short mode
+```
+<!-- endSnippet -->
+
+And of course, if `TQ_short_mode` were `false`, the following would be inserted:
+
+```txt
+full mode
+```
+
+For more information, see [[Query File Defaults]].
+
+And for even more power, see [[Make a query user interface]].