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

feat: Add "Query File Defaults" facility

Author: claremacrae

docs/Getting Started/Obsidian Properties.md

@@ -183,7 +183,7 @@ group by function \
     return value ? window.moment(value).format('YYYY MMMM') : 'no date'
 ```
 
-## Using Query Properties in Placeholders
+## Using Query Properties in Searches
 
 > [!released]
 > Use of Obsidian properties in placeholders was introduced in Tasks X.Y.Z.
@@ -192,31 +192,32 @@ group by function \
   - `query.file.hasProperty()` works.
   - `query.file.property()` works.
 
-Imagine this text at the top of the note containing the query:
+Imagine this text at the top of **the note containing the query**:
 
 ```yaml
 ---
 search-text: exercise
+workdate: 2024-04-01
+groupby: group by happens
 ---
 ```
 
-It can be used in your query in two ways:
+It can be used in queries in several ways:
 
-1. A search term from front-matter embedded via placeholder:
+1. A search term from frontmatter embedded via placeholder:
 
     ```javascript
     description includes {{query.file.property('search-text')}}
+    due on or before {{query.file.property('workdate')}}
     ```
 
-1. An entire instruction controlled by front-matter value:
+2. An entire instruction controlled by front-matter value:
 
     ```javascript
-    {{const prop = 'TQ-explain';    return query.file.hasProperty(prop) ?  ( query.file.property(prop) ? 'explain' : '') : '';}}
-
-    {{const prop = 'TQ-show-tree';  return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' tree' || ''}}
+    {{query.file.property('groupby')}}
     ```
 
-1. Scripting, which allows creation of a custom filter, which works when the search term is empty
+3. Scripting, which allows creation of a custom filter, which works when the search term is empty
 
     ```javascript
     filter by function \
@@ -226,6 +227,9 @@ It can be used in your query in two ways:
         return task.description.toLowerCase().includes(propertyLower);
     ```
 
+> [!tip]
+> See also [[Query File Defaults]] for built-in properties automatically supported by Tasks searches.
+
 > [!warning] Using properties with no value
 > Currently when a property in a placeholder is not set:
 >
@@ -235,13 +239,6 @@ It can be used in your query in two ways:
 > [!Info]
 > In a future release, we will likely allow Tasks to silently ignore built filters created from properties that have no value.
 
-> [!Info]
-> In a future release, we will likely introduce standard property names for instructions that will automatically be included inside Tasks queries.
-> Perhaps:
->
-> - tasks-search-explain: true/false
-> - tasks-search-limit: number
-
 ## How does Tasks interpret Obsidian Properties?
 
 Consider a file with the following example properties (or "Frontmatter"):

docs/Queries/Query File Defaults.md

@@ -0,0 +1,151 @@
+---
+publish: true
+---
+
+# Query File Defaults
+
+## Summary
+
+Scenarios:
+
+- You have multiple Tasks queries in a Markdown file, and they have a lot of
+  text in common. You would like to avoid repeating those common instructions in
+  each one.
+- Usually you like to see your Tasks search results with certain [[Layout]]
+  options, but sometimes it is nice to see more detail, perhaps turning
+  `show tree` on and off, depending on your mood.
+
+## Applying instructions to every Tasks search in a file
+
+### Obsidian-native User Interface
+
+You can use the Obsidian **File properties** view to customise Tasks searches:
+
+![Obsidian's 'File properties' widget, with checkboxes and a text box to modify query file defaults for a file containing Tasks searches.](../images/query-file-defaults-file-properties-controls.png)
+<span class="caption">Obsidian's **File properties** widget, with checkboxes and a text box to modify query file defaults for a file containing Tasks searches. See [[#Widening property names in Obsidian]] for the CSS snippet used to widen property names.</span>
+
+To try this out:
+
+1. Show the `File properties` panel:
+    - Enable the Obsidian core Properties view plugin: `Settings` > `Core plugins` > turn on `Properties view`
+    - Switch to Reading or Live Preview modes.
+    - Run the `Properties view: Show file properties` command.
+2. Add one or more `tasks_query_*` properties to the file
+    - Click on `Add property`.
+    - Start typing `tasks_query_`.
+    - Or you can paste in property names from the [[#Supported Query File Defaults property values]] section below.
+    - Press `<Return>` or `<Enter>` to add the property.
+3. Now you can modify these `tasks_query_*` properties to change the behaviour of Tasks searches in this file.
+
+> [!info]
+> We plan to streamline the addition of these properties to notes.
+
+#### Widening property names in Obsidian
+
+By default, the property names are very narrow in Obsidian.
+
+You can make them wider with the following CSS Snippet.
+
+<!-- snippet: resources/sample_vaults/Tasks-Demo/.obsidian/snippets/widen-property-labels.css -->
+```css
+/* Make property labels wider, to fit the names of Tasks-specific properties */
+.metadata-content {
+    --metadata-label-width: 18em;
+}
+```
+<!-- endSnippet -->
+
+The Obsidian user guide shows how to [use CSS snippets in Obsidian](https://help.obsidian.md/How+to/Add+custom+styles#Use+Themes+and+or+CSS+snippets).
+
+### Meta Bind User Interface
+
+You can use the [Meta Bind](https://obsidian.md/plugins?search=Meta%20Bind) plugin to create a User Interface to easily change your Tasks searches:
+
+![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>
+
+> [!info]- Set up Meta Bind widgets to edit Query File Defaults
+> Steps to do this, which assume you have already [turned off Obsidian's Restricted mode](https://help.obsidian.md/Extending+Obsidian/Plugin+security):
+>
+> 1. Install and enable [Meta Bind](https://obsidian.md/plugins?search=Meta%20Bind)
+> 2. Click the Copy button to copy the Markdown 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.
+>
+> ![[Meta Bind Query Widgets]]
+
+## Technical details
+
+### Supported Query File Defaults property values
+
+These are all the properties currently supported by Tasks, as Query File Defaults.
+
+<!-- snippet: DocsSamplesForDefaults.test.DocsSamplesForDefaults_supported-properties-empty.approved.yaml -->
+```yaml
+---
+tasks_query_explain:
+tasks_query_short_mode:
+tasks_query_show_tree:
+tasks_query_show_tags:
+tasks_query_show_id:
+tasks_query_show_depends_on:
+tasks_query_show_priority:
+tasks_query_show_recurrence_rule:
+tasks_query_show_on_completion:
+tasks_query_show_created_date:
+tasks_query_show_start_date:
+tasks_query_show_scheduled_date:
+tasks_query_show_due_date:
+tasks_query_show_cancelled_date:
+tasks_query_show_done_date:
+tasks_query_show_urgency:
+tasks_query_show_backlink:
+tasks_query_show_edit_button:
+tasks_query_show_postpone_button:
+tasks_query_show_task_count:
+tasks_query_extra_instructions:
+---
+```
+<!-- endSnippet -->
+
+> [!tip]
+> We hope in the future to add an Obsidian Command to add all supported Query
+> File Defaults properties to the current file automatically.
+
+### Types of Query File Defaults property values
+
+These are all the types of properties currently supported by Tasks, as Query
+File Defaults.
+
+> [!tip]
+> We plan to make Tasks add these types to the Obsidian vault automatically in
+> future.
+
+```json
+{
+  "types": {
+    "tasks_query_explain": "checkbox",
+    "tasks_query_short_mode": "checkbox",
+    "tasks_query_show_tree": "checkbox",
+    "tasks_query_show_tags": "checkbox",
+    "tasks_query_show_id": "checkbox",
+    "tasks_query_show_depends_on": "checkbox",
+    "tasks_query_show_priority": "checkbox",
+    "tasks_query_show_recurrence_rule": "checkbox",
+    "tasks_query_show_on_completion": "checkbox",
+    "tasks_query_show_created_date": "checkbox",
+    "tasks_query_show_start_date": "checkbox",
+    "tasks_query_show_scheduled_date": "checkbox",
+    "tasks_query_show_due_date": "checkbox",
+    "tasks_query_show_cancelled_date": "checkbox",
+    "tasks_query_show_done_date": "checkbox",
+    "tasks_query_show_urgency": "checkbox",
+    "tasks_query_show_backlink": "checkbox",
+    "tasks_query_show_edit_button": "checkbox",
+    "tasks_query_show_postpone_button": "checkbox",
+    "tasks_query_show_task_count": "checkbox",
+    "tasks_query_extra_instructions": "text"
+  }
+}
+```

docs/Scripting/Placeholders.md

@@ -77,7 +77,7 @@ Explanation of this Tasks code block query:
 > [!released]
 > Use of Obsidian properties in placeholders was introduced in Tasks X.Y.Z.
 
-It is now possible to use properties in the query file. See [[Obsidian Properties#Using Query Properties in Placeholders]]
+It is now possible to use properties in the query file. See [[Obsidian Properties#Using Query Properties in Searches]]
 
 ## Error checking: invalid variables
 

docs/What is New/Changelog.md

@@ -14,8 +14,10 @@ _In recent [Tasks releases](https://github.com/obsidian-tasks-group/obsidian-tas
 
 - X.Y.Z:
   - Add `query.file.hasProperty()` and `query.file.property()` in custom filters
-  - Add `{{query.file.hasProperty()}}` and `{{query.file.property()}}` in placeholders - see [[Obsidian Properties#Using Query Properties in Placeholders|Using Query Properties in Placeholders]].
+  - Add `{{query.file.hasProperty()}}` and `{{query.file.property()}}` in placeholders - see [[Obsidian Properties#Using Query Properties in Searches|Using Query Properties in Placeholders]].
   - Placeholders can now call functions and contain expressions.
+  - New [[Query File Defaults]] facility allows easy customising of all the
+    Tasks searches in a file, by editing properties
   - Add Chinese translation of [[Settings]], [[Editing a Status]] and [[Check your Statuses]]
 - 7.14.0:
   - Add [[Editing Dates#Date-picker on task dates|date picker]] to Reading mode and Tasks query search results.

docs/images/query-file-defaults-file-properties-controls.png

@@ -0,0 +1,18 @@
+<!-- snippet: DocsSamplesForDefaults.test.DocsSamplesForDefaults_meta-bind-widgets-snippet.approved.md -->
+```md
+short mode: `INPUT[toggle:tasks_query_short_mode]`
+tree: `INPUT[toggle:tasks_query_show_tree]`
+tags: `INPUT[toggle:tasks_query_show_tags]`
+id: `INPUT[toggle:tasks_query_show_id]` depends on: `INPUT[toggle:tasks_query_show_depends_on]`
+priority: `INPUT[toggle:tasks_query_show_priority]`
+recurrence rule: `INPUT[toggle:tasks_query_show_recurrence_rule]` on completion: `INPUT[toggle:tasks_query_show_on_completion]`
+start date: `INPUT[toggle:tasks_query_show_start_date]` scheduled date: `INPUT[toggle:tasks_query_show_scheduled_date]` due date: `INPUT[toggle:tasks_query_show_due_date]`
+created date: `INPUT[toggle:tasks_query_show_created_date]` cancelled date: `INPUT[toggle:tasks_query_show_cancelled_date]` done date: `INPUT[toggle:tasks_query_show_done_date]`
+urgency: `INPUT[toggle:tasks_query_show_urgency]`
+backlink: `INPUT[toggle:tasks_query_show_backlink]`
+edit button: `INPUT[toggle:tasks_query_show_edit_button]` postpone button: `INPUT[toggle:tasks_query_show_postpone_button]`
+task count: `INPUT[toggle:tasks_query_show_task_count]`
+extra instructions: `INPUT[textArea:tasks_query_extra_instructions]`
+explain: `INPUT[toggle:tasks_query_explain]`
+```
+<!-- endSnippet -->

docs/images/query-file-defaults-meta-bind-controls.png

@@ -5,7 +5,8 @@
     "js-engine-code-block-border",
     "dataview-block",
     "dataview-clare",
-    "dataview-blocks"
+    "dataview-blocks",
+    "widen-property-labels"
   ],
   "accentColor": ""
 }

docs/snippets-embedded-in-multiple-pages/Meta Bind Query Widgets.md

@@ -16,5 +16,6 @@
   "obsidian-kanban",
   "js-engine",
   "table-editor-obsidian",
-  "reveal-active-file-button"
+  "reveal-active-file-button",
+  "obsidian-meta-bind-plugin"
 ]

resources/sample_vaults/Tasks-Demo/.obsidian/appearance.json

@@ -0,0 +1,22 @@
+{
+  "devMode": false,
+  "ignoreCodeBlockRestrictions": false,
+  "preferredDateFormat": "YYYY-MM-DD",
+  "firstWeekday": {
+    "index": 1,
+    "name": "Monday",
+    "shortName": "Mo"
+  },
+  "syncInterval": 200,
+  "minSyncInterval": 50,
+  "maxSyncInterval": 1000,
+  "enableJs": false,
+  "viewFieldDisplayNullAsEmpty": false,
+  "enableSyntaxHighlighting": true,
+  "enableEditorRightClickMenu": true,
+  "inputFieldTemplates": [],
+  "buttonTemplates": [],
+  "excludedFolders": [
+    "templates"
+  ]
+}