Merge pull request #3463 from obsidian-tasks-group/trigger-search-result-redraws

feat: Editing any Includes setting redraws open Tasks searches

Author: claremacrae

resources/sample_vaults/Tasks-Demo/How To/Reuse instructions across the vault.md

@@ -1,8 +1,9 @@
 ---
 TQ_explain: false
 TQ_extra_instructions: |-
+  (filename includes Tasks Format) OR (tag includes #context)
   ignore global query
-  limit 10
+  limit 20
 ---
 # Reuse instructions across the vault
 
@@ -16,6 +17,12 @@ explain: `INPUT[toggle:TQ_explain]`
 
 (assuming there is not one called `xxxx`!)
 
+````text
+```tasks
+include xxxx
+```
+````
+
 ```tasks
 include xxxx
 ```
@@ -24,13 +31,25 @@ include xxxx
 
 explain: `INPUT[toggle:TQ_explain]`
 
+````text
+```tasks
+```
+````
+
 ```tasks
 ```
 
 ## Hide all the fields
 
 explain: `INPUT[toggle:TQ_explain]`
 
+````text
+```tasks
+include hide_all_dates
+include hide_other_fields
+```
+````
+
 ```tasks
 include hide_all_dates
 include hide_other_fields
@@ -40,24 +59,59 @@ include hide_other_fields
 
 explain: `INPUT[toggle:TQ_explain]`
 
+````text
+```tasks
+include hide_buttons
+```
+````
+
 ```tasks
 include hide_buttons
 ```
 
-## Hide everything, including tags
+## Show only the description and any tags
 
 explain: `INPUT[toggle:TQ_explain]`
 
+````text
+```tasks
+include just_the_description_and_tags
+```
+````
+
 ```tasks
 include just_the_description_and_tags
 ```
 
+## Just show the description, without tags
+
+explain: `INPUT[toggle:TQ_explain]`
+
+````text
+```tasks
+include just_the_description
+```
+````
+
+```tasks
+include just_the_description
+```
+
 ## Advanced use: return a function, that takes a parameter from the query source
 
 ### Has context 'home' - and group by the Include text - version 1
 
 explain: `INPUT[toggle:TQ_explain]`
 
+````text
+```tasks
+# For debug/explanatory purposes, show the source of the Include as a group name:
+group by function const x = "{{includes.filter_by_context}}"; return x
+
+{{includes.filter_by_context}}('home')
+```
+````
+
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
 group by function const x = "{{includes.filter_by_context}}"; return x
@@ -69,6 +123,16 @@ group by function const x = "{{includes.filter_by_context}}"; return x
 
 explain: `INPUT[toggle:TQ_explain]`
 
+````text
+```tasks
+# For debug/explanatory purposes, show the source of the Include as a group name:
+group by function const x = "{{includes.extract_contexts_1}}"; return x
+
+# includes.extract_contexts_1 value needs to be surrounded by parentheses ():
+filter by function return ({{includes.extract_contexts_1}})('home')
+```
+````
+
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
 group by function const x = "{{includes.extract_contexts_1}}"; return x
@@ -81,6 +145,16 @@ filter by function return ({{includes.extract_contexts_1}})('home')
 
 explain: `INPUT[toggle:TQ_explain]`
 
+````text
+```tasks
+# For debug/explanatory purposes, show the source of the Include as a group name:
+group by function const x = "{{includes.extract_contexts_2}}"; return x
+
+# includes.extract_contexts_1 value has the parentheses, to simplify use:
+filter by function {{includes.extract_contexts_2}}('home')
+```
+````
+
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
 group by function const x = "{{includes.extract_contexts_2}}"; return x

src/Config/IncludesSettingsUI.ts

@@ -1,5 +1,6 @@
 import { Setting, TextAreaComponent } from 'obsidian';
 import type TasksPlugin from '../main';
+import type { TasksEvents } from '../Obsidian/TasksEvents';
 import { IncludesSettingsService, type RenamesInProgress } from './IncludesSettingsService';
 import { type IncludesMap, type Settings, getSettings, updateSettings } from './Settings';
 
@@ -12,15 +13,18 @@ type RefreshViewCallback = () => void;
  */
 export class IncludesSettingsUI {
     private readonly plugin: TasksPlugin;
+    private readonly events: TasksEvents;
     private readonly includesSettingsService = new IncludesSettingsService();
     private readonly nameFields: Map<string, { inputEl: HTMLInputElement; originalKey: string }> = new Map();
 
     /**
      * Creates a new instance of IncludesSettingsUI
      * @param plugin The Tasks plugin instance
+     * @param events The plugin's events object
      */
-    constructor(plugin: TasksPlugin) {
+    constructor(plugin: TasksPlugin, events: TasksEvents) {
         this.plugin = plugin;
+        this.events = events;
     }
 
     /**
@@ -219,5 +223,7 @@ export class IncludesSettingsUI {
         if (refreshView) {
             refreshView();
         }
+
+        this.events.triggerReloadOpenSearchResults();
     }
 }

src/Config/SettingsTab.ts

@@ -6,6 +6,7 @@ import { Status } from '../Statuses/Status';
 import type { StatusCollection } from '../Statuses/StatusCollection';
 import { createStatusRegistryReport } from '../Statuses/StatusRegistryReport';
 import { i18n } from '../i18n/i18n';
+import type { TasksEvents } from '../Obsidian/TasksEvents';
 import * as Themes from './Themes';
 import {
     type HeadingState,
@@ -34,11 +35,11 @@ export class SettingsTab extends PluginSettingTab {
     private readonly plugin: TasksPlugin;
     private readonly includesSettingsUI;
 
-    constructor({ plugin }: { plugin: TasksPlugin }) {
+    constructor({ plugin, events }: { plugin: TasksPlugin; events: TasksEvents }) {
         super(plugin.app, plugin);
 
         this.plugin = plugin;
-        this.includesSettingsUI = new IncludesSettingsUI(plugin);
+        this.includesSettingsUI = new IncludesSettingsUI(plugin, events);
     }
 
     private static createFragmentWithHTML = (html: string) =>

src/Obsidian/TasksEvents.ts

@@ -7,6 +7,7 @@ import type { State } from './Cache';
 enum Event {
     CacheUpdate = 'obsidian-tasks-plugin:cache-update',
     RequestCacheUpdate = 'obsidian-tasks-plugin:request-cache-update',
+    ReloadOpenSearchResults = 'obsidian-tasks-plugin:reload-open-search-results',
 }
 
 interface CacheUpdateData {
@@ -22,30 +23,52 @@ export class TasksEvents {
         this.obsidianEvents = obsidianEvents;
     }
 
+    // ------------------------------------------------------------------------
+    // CacheUpdate event
+
     public onCacheUpdate(handler: (cacheData: CacheUpdateData) => void): EventRef {
         this.logger.debug('TasksEvents.onCacheUpdate()');
+        const name = Event.CacheUpdate;
         // @ts-expect-error: error TS2345: Argument of type '(cacheData: CacheUpdateData) => void'
         // is not assignable to parameter of type '(...data: unknown[]) => unknown'.
-        return this.obsidianEvents.on(Event.CacheUpdate, handler);
+        return this.obsidianEvents.on(name, handler);
     }
 
     public triggerCacheUpdate(cacheData: CacheUpdateData): void {
         this.logger.debug('TasksEvents.triggerCacheUpdate()');
         this.obsidianEvents.trigger(Event.CacheUpdate, cacheData);
     }
 
+    // ------------------------------------------------------------------------
+    // RequestCacheUpdate event
+
     public onRequestCacheUpdate(handler: (fn: (cacheData: CacheUpdateData) => void) => void): EventRef {
         this.logger.debug('TasksEvents.onRequestCacheUpdate()');
+        const name = Event.RequestCacheUpdate;
         // @ts-expect-error: error TS2345: Argument of type '(cacheData: CacheUpdateData) => void'
         // is not assignable to parameter of type '(...data: unknown[]) => unknown'.
-        return this.obsidianEvents.on(Event.RequestCacheUpdate, handler);
+        return this.obsidianEvents.on(name, handler);
     }
 
     public triggerRequestCacheUpdate(fn: (cacheData: CacheUpdateData) => void): void {
         this.logger.debug('TasksEvents.triggerRequestCacheUpdate()');
         this.obsidianEvents.trigger(Event.RequestCacheUpdate, fn);
     }
 
+    // ------------------------------------------------------------------------
+    // ReloadOpenSearchResults event
+
+    public onReloadOpenSearchResults(handler: () => void): EventRef {
+        this.logger.debug('TasksEvents.onReloadOpenSearchResults()');
+        const name = Event.ReloadOpenSearchResults;
+        return this.obsidianEvents.on(name, handler);
+    }
+
+    public triggerReloadOpenSearchResults(): void {
+        this.logger.debug('TasksEvents.triggerReloadOpenSearchResults()');
+        this.obsidianEvents.trigger(Event.ReloadOpenSearchResults);
+    }
+
     public off(eventRef: EventRef): void {
         this.logger.debug('TasksEvents.off()');
         this.obsidianEvents.offref(eventRef);

src/Renderer/QueryRenderer.ts

@@ -1,11 +1,13 @@
 import {
     type CachedMetadata,
+    type Debouncer,
     type EventRef,
     type MarkdownPostProcessorContext,
     MarkdownRenderChild,
     MarkdownRenderer,
     type TAbstractFile,
     TFile,
+    debounce,
 } from 'obsidian';
 import { App, Keymap } from 'obsidian';
 import { GlobalQuery } from '../Config/GlobalQuery';
@@ -21,6 +23,8 @@ import type { Task } from '../Task/Task';
 import { type BacklinksEventHandler, type EditButtonClickHandler, QueryResultsRenderer } from './QueryResultsRenderer';
 import { createAndAppendElement } from './TaskLineRenderer';
 
+type RenderParams = { tasks: Task[]; state: State };
+
 /**
  * `QueryRenderer` is responsible for rendering queries in Markdown code blocks
  * annotated with the 'tasks' processor.
@@ -90,12 +94,14 @@ class QueryRenderChild extends MarkdownRenderChild {
     private readonly events: TasksEvents;
 
     private renderEventRef: EventRef | undefined;
+    private reloadSearchResultsEventRef: EventRef | undefined;
     private queryReloadTimeout: NodeJS.Timeout | undefined;
 
     private isCacheChangedSinceLastRedraw = false;
     private observer: IntersectionObserver | null = null;
 
     private readonly queryResultsRenderer: QueryResultsRenderer;
+    private readonly debouncedRenderFn: Debouncer<[RenderParams], void>;
 
     constructor({
         app,
@@ -127,15 +133,19 @@ class QueryRenderChild extends MarkdownRenderChild {
         this.app = app;
         this.plugin = plugin;
         this.events = events;
+
+        this.debouncedRenderFn = debounce((params: RenderParams) => this.render(params), 300, true);
     }
 
     onload() {
         this.queryResultsRenderer.query.debug('[render] QueryRenderChild.onload() entered');
 
         // Process the current cache state:
         this.events.triggerRequestCacheUpdate(this.render.bind(this));
-        // Listen to future cache changes:
+
+        // Listen to future changes:
         this.renderEventRef = this.events.onCacheUpdate(this.render.bind(this));
+        this.reloadSearchResultsEventRef = this.events.onReloadOpenSearchResults(this.rereadQueryFromFile.bind(this));
 
         this.reloadQueryAtMidnight();
 
@@ -221,10 +231,17 @@ class QueryRenderChild extends MarkdownRenderChild {
             this.events.off(this.renderEventRef);
         }
 
+        if (this.reloadSearchResultsEventRef !== undefined) {
+            this.events.off(this.reloadSearchResultsEventRef);
+        }
+
         if (this.queryReloadTimeout !== undefined) {
             clearTimeout(this.queryReloadTimeout);
         }
 
+        // Cancel any pending debounced renders
+        this.debouncedRenderFn.cancel();
+
         this.observer?.disconnect();
         this.observer = null;
     }
@@ -256,7 +273,11 @@ class QueryRenderChild extends MarkdownRenderChild {
         }, millisecondsToMidnight + 1000); // Add buffer to be sure to run after midnight.
     }
 
-    private async render({ tasks, state }: { tasks: Task[]; state: State }) {
+    private debouncedRender(params: RenderParams): void {
+        this.debouncedRenderFn(params);
+    }
+
+    private async render({ tasks, state }: RenderParams) {
         // We got here because the Cache reported a change in at least one task in the vault.
         // So note that any results we have already drawn are now out-of-date:
         this.isCacheChangedSinceLastRedraw = true;
@@ -304,6 +325,12 @@ class QueryRenderChild extends MarkdownRenderChild {
 
         this.containerEl.firstChild?.replaceWith(content);
     }
+
+    private rereadQueryFromFile() {
+        this.queryResultsRenderer.rereadQueryFromFile();
+        this.isCacheChangedSinceLastRedraw = true;
+        this.debouncedRender({ tasks: this.plugin.getTasks(), state: this.plugin.getState() });
+    }
 }
 
 function createEditTaskPencilClickHandler(app: App): EditButtonClickHandler {

src/Renderer/QueryResultsRenderer.ts

@@ -112,6 +112,20 @@ export class QueryResultsRenderer {
      */
     public setTasksFile(newFile: TasksFile) {
         this._tasksFile = newFile;
+        this.rereadQueryFromFile();
+    }
+
+    /**
+     * Reads the query from the source file and tasks file.
+     *
+     * This is for when some change in the vault invalidates the current
+     * Query object, and so it needs to be reloaded.
+     *
+     * For example, the user edited their Tasks plugin settings in some
+     * way that changes how the query is interpreted, such as changing an
+     * 'includes' definition.
+     */
+    public rereadQueryFromFile() {
         this.query = this.makeQueryFromSourceAndTasksFile();
     }