Skip to content

Build your personal knowledge base with Trilium Notes

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.ts
index 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.ts
index 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: CreateN
return 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.json
index 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.ts
index 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.html
index 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. See
documentation 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&nbsp;
+ <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.html
index 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&nbsp;<a class="reference-link" href="#root/_help_iPIMuisry3hd">Text</a>&nbsp;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&nbsp;<a class="reference-link" href="#root/_help_oPVyFC7WL2Lp">Note Tree</a>&nbsp;context
+ menu (<em>Insert child note</em>, <em>Insert note after</em>) still creates
+ it at the chosen place.</p>
+<p>See&nbsp;<a class="reference-link" href="#root/_help_S0Fos78ZfcY7">Note Inbox</a>&nbsp;for
+ the inbox used by notes created without a template.</p>
<h2>Regarding note types</h2>
<p>By default, newly created notes are&nbsp;<a class="reference-link" href="#root/_help_iPIMuisry3hd">Text</a>&nbsp;notes.
If a parent note defines a <code spellcheck="false">child:template</code> pointing
diff --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.html
index 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&nbsp;<a class="reference-link" href="#root/_help_KC1HB96bqqHX">Templates</a>&nbsp;for
+ details.</p>
\ No newline at end of file
diff --git a/docs/User Guide/User Guide/Advanced Usage/Attributes/Relations.md b/docs/User Guide/User Guide/Advanced Usage/Attributes/Relations.md
index 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.md
index 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 types
By 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.md
index 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 file
diff --git a/packages/commons/src/lib/builtin_attributes.ts b/packages/commons/src/lib/builtin_attributes.ts
index 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" },