Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
feat(templates): let a template gather its instances in its own inbox
Elian Doranb2a2be3ea01e
diff --git a/apps/client/src/services/note_create.spec.ts b/apps/client/src/services/note_create.spec.tsindex 4cbaf07a7a..40c3291820 100644--- a/apps/client/src/services/note_create.spec.ts+++ b/apps/client/src/services/note_create.spec.ts@@ -321,6 +321,60 @@ describe("chooseNoteType", () => {triggerCommand.mockImplementation((_name: string, data: any) => data.callback(payload));await expect(noteCreateService.chooseNoteType()).resolves.toEqual(payload);});++ describe("template inbox", () => {+ // A template whose ~inbox points at a note reachable from root, so that it has a note path.+ const root = buildNote({+ id: "root",+ title: "root",+ children: [+ { id: "people", title: "People" },+ { id: "person-tpl", title: "Person", "#template": "", "~inbox": "people" },+ { id: "plain-tpl", title: "Plain", "#template": "" }+ ]+ });+ expect(root.noteId).toBe("root");++ function choose(response: Record<string, unknown>) {+ triggerCommand.mockImplementation((_name: string, data: any) => data.callback(response));+ return noteCreateService.chooseNoteType();+ }++ it("routes a template without an explicit parent into the template's inbox", async () => {+ await expect(choose({ success: true, noteType: "text", templateNoteId: "person-tpl" }))+ .resolves.toEqual({+ success: true, noteType: "text", templateNoteId: "person-tpl", notePath: "root/people"+ });+ });++ it("keeps a parent the user picked over the template's inbox", async () => {+ await expect(choose({+ success: true, noteType: "text", templateNoteId: "person-tpl", notePath: "root/elsewhere"+ })).resolves.toMatchObject({ notePath: "root/elsewhere" });+ });++ it("leaves the path unset without a template or without an inbox on it", async () => {+ await expect(choose({ success: true, noteType: "text" }))+ .resolves.toEqual({ success: true, noteType: "text" });+ await expect(choose({ success: true, noteType: "text", templateNoteId: "plain-tpl" }))+ .resolves.not.toHaveProperty("notePath", expect.any(String));+ });++ it("creates the note in the inbox when the chooser is used through createNoteWithTypePrompt", async () => {+ setActiveContext(true);+ triggerCommand.mockImplementation((_name: string, data: any) => {+ data.callback({ success: true, noteType: "text", templateNoteId: "person-tpl" });+ });++ await noteCreateService.createNoteWithTypePrompt("fallback-parent", {});++ expect(server.post).toHaveBeenCalledWith(+ `notes/people/children?target=into&targetBranchId=`,+ expect.objectContaining({ templateNoteId: "person-tpl" }),+ undefined+ );+ });+ });});describe("duplicateSubtree", () => {diff --git a/apps/client/src/services/note_create.ts b/apps/client/src/services/note_create.tsindex fef0361fc5..57ea4f4f22 100644--- a/apps/client/src/services/note_create.ts+++ b/apps/client/src/services/note_create.ts@@ -117,10 +117,21 @@ async function createNote(parentNotePath: string | undefined, options: CreateNot};}+/**+ * Prompts for the type / template of a new note and, optionally, a parent. When the user picks a+ * template without picking a parent, the template's own `~inbox` (if any) is returned as the+ * `notePath` instead, so a template gathers the notes created from it in one place.+ */async function chooseNoteType() {- return new Promise<ChooseNoteTypeResponse>((res) => {+ const response = await new Promise<ChooseNoteTypeResponse>((res) => {appContext.triggerCommand("chooseNoteType", { callback: res });});++ if (response.success && !response.notePath && response.templateNoteId) {+ response.notePath = await getTemplateInboxNotePath(response.templateNoteId);+ }++ return response;}async function createNoteWithTypePrompt(parentNotePath: string, options: CreateNoteOpts = {}) {@@ -136,6 +147,18 @@ async function createNoteWithTypePrompt(parentNotePath: string, options: CreateNreturn await createNote(notePath || parentNotePath, options);}+/**+ * Resolves the path of the note the template's `~inbox` relation points at, relative to the current+ * hoisting. Undefined when the template has no inbox, or the inbox has no visible path.+ */+async function getTemplateInboxNotePath(templateNoteId: string) {+ const templateNote = await froca.getNote(templateNoteId);+ const inboxNote = await templateNote?.getRelationTarget("inbox");+ const hoistedNoteId = appContext.tabManager.getActiveContext()?.hoistedNoteId;++ return inboxNote?.getBestNotePathString(hoistedNoteId);+}+/* If the first element is heading, parse it out and use it as a new heading. */function parseSelectedHtml(selectedHtml: string) {const dom = $.parseHTML(selectedHtml);diff --git a/apps/client/src/translations/en/translation.json b/apps/client/src/translations/en/translation.jsonindex df3b4e80ff..bcdd641d19 100644--- a/apps/client/src/translations/en/translation.json+++ b/apps/client/src/translations/en/translation.json@@ -633,6 +633,7 @@"run_on_attribute_creation": "Executes when new attribute is created for the note which defines this relation.","run_on_attribute_change": "Executes when the attribute is changed of a note which defines this relation. This is triggered also when the attribute is deleted.","relation_template": "Note's attributes will be inherited even without a parent-child relationship, note's content and subtree will be added to instance notes if empty. See documentation for details.",+ "relation_inbox": "Set on a template note: notes created from the template (e.g. via @-completion) are created under the target note, unless another location is picked explicitly.","inherit": "Note's attributes will be inherited even without a parent-child relationship. See template relation for a similar concept. See attribute inheritance in the documentation.","render_note": "Notes of type \"render HTML note\" will be rendered using a code note (HTML or script) and it is necessary to point using this relation to which note should be rendered.","widget_relation": "Target of this relation will be executed and rendered as a widget in the sidebar.",diff --git a/apps/client/src/widgets/attribute_widgets/attr_help.ts b/apps/client/src/widgets/attribute_widgets/attr_help.tsindex b0093211dc..7da869bbd7 100644--- a/apps/client/src/widgets/attribute_widgets/attr_help.ts+++ b/apps/client/src/widgets/attribute_widgets/attr_help.ts@@ -200,6 +200,7 @@ export const ATTR_HELP: AttrHelpMap = {runOnAttributeCreation: t("attribute_detail.run_on_attribute_creation"),runOnAttributeChange: t("attribute_detail.run_on_attribute_change"),template: t("attribute_detail.relation_template"),+ inbox: t("attribute_detail.relation_inbox"),inherit: t("attribute_detail.inherit"),renderNote: t("attribute_detail.render_note"),widget: t("attribute_detail.widget_relation"),diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Attributes/Relations.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Attributes/Relations.htmlindex 95df04dbf5..d3b5b64d96 100644--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Attributes/Relations.html+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Attributes/Relations.html@@ -81,6 +81,14 @@ class="table">note's content and subtree will be added to instance notes if empty. Seedocumentation for details.</td></tr>+ <tr>+ <td><code spellcheck="false">inbox</code>+ </td>+ <td>set on a template note, points to the note under which notes created+ from the template are gathered when no other location is picked. See + <a+ class="reference-link" href="#root/_help_KC1HB96bqqHX">Templates</a>.</td>+ </tr><tr><td><code spellcheck="false">inherit</code></td>diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Templates.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Templates.htmlindex 8e423e6c31..4af7223fe0 100644--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Templates.html+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Templates.html@@ -57,6 +57,23 @@will not automatically apply the new template to the grandchild notes.Only the structure present at the time of note creation is considered.</p></aside>+<h2>Template inbox</h2>+<p>A template can gather the notes created from it in one place, instead+ of having them land wherever they happen to be created. To do so, add an+ <code+ spellcheck="false">~inbox</code>relation to the template note, pointing at the note that should+ hold the instances — for example a <em>Person</em> template with <code spellcheck="false">~inbox</code> pointing+ to a <em>People</em> note.</p>+<p>The inbox is used whenever a note is created from the template through+ the <em>Choose note type</em> dialog — for example via <code spellcheck="false">@</code>-completion+ in a <a class="reference-link" href="#root/_help_iPIMuisry3hd">Text</a> note,+ or the <em>Create and link child note</em> option of the note search — and+ no other location is picked in that dialog. Creating an instance note from+ the <a class="reference-link" href="#root/_help_oPVyFC7WL2Lp">Note Tree</a> context+ menu (<em>Insert child note</em>, <em>Insert note after</em>) still creates+ it at the chosen place.</p>+<p>See <a class="reference-link" href="#root/_help_S0Fos78ZfcY7">Note Inbox</a> for+ the inbox used by notes created without a template.</p><h2>Regarding note types</h2><p>By default, newly created notes are <a class="reference-link" href="#root/_help_iPIMuisry3hd">Text</a> notes.If a parent note defines a <code spellcheck="false">child:template</code> pointingdiff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.htmlindex 68de24d038..1786f90c60 100644--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.html+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.html@@ -27,4 +27,12 @@in that workspace.</li><li>A note carrying the <code spellcheck="false">#inbox</code> within that workspace.</li><li>The workspace root note itself.</li>-</ul>\ No newline at end of file+</ul>+<h2>Template inboxes</h2>+<p>A <a href="#root/_help_KC1HB96bqqHX">template</a> can have an inbox of its+ own, set via an <code spellcheck="false">~inbox</code> relation on the template+ note pointing at the destination. Notes created from that template through+ the <em>Choose note type</em> dialog (e.g. <code spellcheck="false">@</code>-completion+ in a text note) land there instead of under the current note, unless another+ location is picked in the dialog. See <a class="reference-link" href="#root/_help_KC1HB96bqqHX">Templates</a> for+ details.</p>\ No newline at end of filediff --git a/docs/User Guide/User Guide/Advanced Usage/Attributes/Relations.md b/docs/User Guide/User Guide/Advanced Usage/Attributes/Relations.mdindex 3bde4e9faf..13d60901ac 100644--- a/docs/User Guide/User Guide/Advanced Usage/Attributes/Relations.md+++ b/docs/User Guide/User Guide/Advanced Usage/Attributes/Relations.md@@ -42,6 +42,7 @@ These relations are supported and used internally by Trilium.| --- | --- || `runOn*` | See <a class="reference-link" href="../../Scripting/Backend%20scripts/Backend%20Events.md">Events</a> || `template` | note's attributes will be inherited even without a parent-child relationship, note's content and subtree will be added to instance notes if empty. See documentation for details. |+| `inbox` | set on a template note, points to the note under which notes created from the template are gathered when no other location is picked. See <a class="reference-link" href="../Templates.md">Templates</a>. || `inherit` | note's attributes will be inherited even without a parent-child relationship. See <a class="reference-link" href="../Templates.md">Templates</a> for a similar concept. See <a class="reference-link" href="Attribute%20Inheritance.md">Attribute Inheritance</a> in the documentation. || `renderNote` | notes of type <a class="reference-link" href="../../Note%20Types/Render%20Note.md">Render Note</a> will be rendered using a code note (HTML or script) and it is necessary to point using this relation to which note should be rendered || `widget` | Used in the context of custom <a class="reference-link" href="../../Scripting/Frontend%20Basics/Launch%20Bar%20Widgets.md">Launch Bar Widgets</a>, to refer to the widget that will be rendered. |diff --git a/docs/User Guide/User Guide/Advanced Usage/Templates.md b/docs/User Guide/User Guide/Advanced Usage/Templates.mdindex a34dccfabe..338a0f0dd4 100644--- a/docs/User Guide/User Guide/Advanced Usage/Templates.md+++ b/docs/User Guide/User Guide/Advanced Usage/Templates.md@@ -33,6 +33,14 @@ To specify a template for child notes, you can use a `~child:template` relation> Changing the template hierarchy after the parent note is created will not retroactively apply to newly created child notes.> For example, if you initially use `~child:template` and later switch to `~child:child:template`, it will not automatically apply the new template to the grandchild notes. Only the structure present at the time of note creation is considered.+## Template inbox++A template can gather the notes created from it in one place, instead of having them land wherever they happen to be created. To do so, add an `~inbox` relation to the template note, pointing at the note that should hold the instances — for example a _Person_ template with `~inbox` pointing to a _People_ note.++The inbox is used whenever a note is created from the template through the _Choose note type_ dialog — for example via `@`-completion in a <a class="reference-link" href="../Note%20Types/Text.md">Text</a> note, or the _Create and link child note_ option of the note search — and no other location is picked in that dialog. Creating an instance note from the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Note%20Tree.md">Note Tree</a> context menu (_Insert child note_, _Insert note after_) still creates it at the chosen place.++See <a class="reference-link" href="../Basic%20Concepts%20and%20Features/Notes/Note%20Inbox.md">Note Inbox</a> for the inbox used by notes created without a template.+## Regarding note typesBy default, newly created notes are <a class="reference-link" href="../Note%20Types/Text.md">Text</a> notes. If a parent note defines a `child:template` pointing to a template of a different type (e.g. a Code note), the behavior depends on how the new note is created:diff --git a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.md b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.mdindex ebf7f88e16..03e21d8940 100644--- a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.md+++ b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Note Inbox.md@@ -25,4 +25,8 @@ When a new note is created while hoisted in a workspace, the location is determi* A note carrying the `#workspaceInbox` label in that workspace.* A note carrying the `#inbox` within that workspace.-* The workspace root note itself.\ No newline at end of file+* The workspace root note itself.++## Template inboxes++A [template](../../Advanced%20Usage/Templates.md) can have an inbox of its own, set via an `~inbox` relation on the template note pointing at the destination. Notes created from that template through the _Choose note type_ dialog (e.g. `@`-completion in a text note) land there instead of under the current note, unless another location is picked in the dialog. See <a class="reference-link" href="../../Advanced%20Usage/Templates.md">Templates</a> for details.\ No newline at end of filediff --git a/packages/commons/src/lib/builtin_attributes.ts b/packages/commons/src/lib/builtin_attributes.tsindex bb95ee11b8..536f58ffc4 100644--- a/packages/commons/src/lib/builtin_attributes.ts+++ b/packages/commons/src/lib/builtin_attributes.ts@@ -338,6 +338,8 @@ const BUILTIN_ATTRIBUTES = [{ type: "relation", name: "runOnAttributeCreation", isDangerous: true },{ type: "relation", name: "runOnAttributeChange", isDangerous: true },{ type: "relation", name: "template" },+ // Set on a template: where a note created from it goes when no parent is picked explicitly.+ { type: "relation", name: "inbox" },{ type: "relation", name: "inherit" },// Set on a journal root, to be applied as `~template` on each note the period generates.{ type: "relation", name: "dateTemplate" },