TriliumNext/Trilium
1
0
Fork 0
mirror of https://github.com/TriliumNext/Trilium.git synced 2025-12-10 03:53:37 -06:00
Code Issues 1.1k Packages Projects Releases 10 Wiki Activity

docs(script): clarify originEntity and activeContext

Browse Source
This commit is contained in:
Elian Doran 2025-12-07 23:58:02 +02:00
parent 2f13a1ad21
commit cb3aced2ed
No known key found for this signature in database
5 changed files with 206 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
apps/client/src/services/frontend_script_api.ts
View File

@ -77,6 +77,10 @@ export interface Api {
/** /**
* Entity whose event triggered this execution. * Entity whose event triggered this execution.
*
* <p>
* For front-end scripts, generally there's no origin entity specified since the scripts are run by the user or automatically by the UI (widgets).
* If there is an origin entity specified, then it's going to be a note entity.
*/ */
originEntity: unknown | null; originEntity: unknown | null;
@ -278,12 +282,16 @@ export interface Api {
getActiveContextNote(): FNote; getActiveContextNote(): FNote;
/** /**
* @returns returns active context (split) * Obtains the currently active/focused split in the current tab.
*
* Note that this method does not return the note context of the "Quick edit" panel, it will return the note context behind it.
*/ */
getActiveContext(): NoteContext; getActiveContext(): NoteContext;
/** /**
* @returns returns active main context (first split in a tab, represents the tab as a whole) * Obtains the main context of the current tab. This is the left-most split.
*
* Note that this method does not return the note context of the "Quick edit" panel, it will return the note context behind it.
*/ */
getActiveMainContext(): NoteContext; getActiveMainContext(): NoteContext;

4
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/2. Reverse proxy/Traefik.html generated vendored
View File

@ -4,7 +4,7 @@
<h2>Breaking change in Traefik 3.6.4</h2> <h2>Breaking change in Traefik 3.6.4</h2>
<p>Traefik 3.6.4 introduced a <a href="https://doc.traefik.io/traefik/migrate/v3/#encoded-characters-in-request-path">breaking change</a> regarding <p>Traefik 3.6.4 introduced a <a href="https://doc.traefik.io/traefik/migrate/v3/#encoded-characters-in-request-path">breaking change</a> regarding
how percent-encoded characters are handled in URLs. More specifically some how percent-encoded characters are handled in URLs. More specifically some
URLs used by Trilium (such as <code spellcheck="false">search/%23workspace%20%23!template</code>) URLs used by Trilium (such as <code>search/%23workspace%20%23!template</code>)
are automatically rejected by Traefik, resulting in HTTP 400 errors.</p> are automatically rejected by Traefik, resulting in HTTP 400 errors.</p>
<p>To solve this, the Traefik <a href="https://doc.traefik.io/traefik/getting-started/configuration-overview/#the-install-configuration"><strong>static</strong> configuration</a> must <p>To solve this, the Traefik <a href="https://doc.traefik.io/traefik/getting-started/configuration-overview/#the-install-configuration"><strong>static</strong> configuration</a> must
be modified in order to allow those characters:</p><pre><code class="language-text-x-yaml">entryPoints: be modified in order to allow those characters:</p><pre><code class="language-text-x-yaml">entryPoints:
@ -36,7 +36,7 @@
<h3>Setup needed environment variables</h3> <h3>Setup needed environment variables</h3>
<p>After setting up a reverse proxy, make sure to configure the&nbsp;<a class="reference-link" <p>After setting up a reverse proxy, make sure to configure the&nbsp;<a class="reference-link"
href="#root/_help_LLzSMXACKhUs">Trusted proxy</a>.</p> href="#root/_help_LLzSMXACKhUs">Trusted proxy</a>.</p>
<h3>Example <code spellcheck="false">docker-compose.yaml</code></h3><pre><code class="language-text-x-yaml">services: <h3>Example <code>docker-compose.yaml</code></h3><pre><code class="language-text-x-yaml">services:
trilium: trilium:
image: triliumnext/trilium image: triliumnext/trilium
container_name: trilium container_name: trilium

277
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Backend scripts/Events.html generated vendored
View File

@ -5,122 +5,169 @@
<p>Global events are attached to the script note via label. Simply create <p>Global events are attached to the script note via label. Simply create
e.g. "run" label with some of these values and script note will be executed e.g. "run" label with some of these values and script note will be executed
once the event occurs.</p> once the event occurs.</p>
<table> <figure class="table">
<thead> <table>
<tr> <thead>
<th>Label</th> <tr>
<th>Description</th> <th>Label</th>
</tr> <th>Description</th>
</thead> </tr>
<tbody> </thead>
<tr> <tbody>
<td><code>run</code> <tr>
</td> <td><code spellcheck="false">run</code>
<td> </td>
<p>Defines on which events script should run. Possible values are:</p> <td>
<ul> <p>Defines on which events script should run. Possible values are:</p>
<li><code>frontendStartup</code> - when Trilium frontend starts up (or is refreshed), <ul>
but not on mobile.</li> <li data-list-item-id="e244b14e102cf1b0d4954e8fd455ea77b"><code spellcheck="false">frontendStartup</code> - when Trilium frontend
<li><code>mobileStartup</code> - when Trilium frontend starts up (or is refreshed), starts up (or is refreshed), but not on mobile.</li>
on mobile.</li> <li data-list-item-id="ea8f8ca86e7b351dd86108848ccb9103a"><code spellcheck="false">mobileStartup</code> - when Trilium frontend starts
<li><code>backendStartup</code> - when Trilium backend starts up</li> up (or is refreshed), on mobile.</li>
<li><code>hourly</code> - run once an hour. You can use additional label <code>runAtHour</code> to <li data-list-item-id="e658488cf1a0862603088ef384e41b8b6"><code spellcheck="false">backendStartup</code> - when Trilium backend starts
specify at which hour, on the back-end.</li> up</li>
<li><code>daily</code> - run once a day, on the back-end</li> <li data-list-item-id="ef40ba992fc450d33a18ca4cb031eca66"><code spellcheck="false">hourly</code> - run once an hour. You can use
</ul> additional label <code spellcheck="false">runAtHour</code> to specify at
</td> which hour, on the back-end.</li>
</tr> <li data-list-item-id="e07458d4f55b6eb42468a5535b8425c5f"><code spellcheck="false">daily</code> - run once a day, on the back-end</li>
<tr> </ul>
<td><code>runOnInstance</code> </td>
</td> </tr>
<td>Specifies that the script should only run on a particular&nbsp;<a class="reference-link" <tr>
href="#root/_help_c5xB8m4g2IY6">Trilium instance</a>.</td> <td><code spellcheck="false">runOnInstance</code>
</tr> </td>
<tr> <td>Specifies that the script should only run on a particular&nbsp;<a class="reference-link"
<td><code>runAtHour</code> href="#root/_help_c5xB8m4g2IY6">Trilium instance</a>.</td>
</td> </tr>
<td>On which hour should this run. Should be used together with <code>#run=hourly</code>. <tr>
Can be defined multiple times for more runs during the day.</td> <td><code spellcheck="false">runAtHour</code>
</tr> </td>
</tbody> <td>On which hour should this run. Should be used together with <code spellcheck="false">#run=hourly</code>.
</table> Can be defined multiple times for more runs during the day.</td>
</tr>
</tbody>
</table>
</figure>
<h2>Entity events</h2> <h2>Entity events</h2>
<p>Other events are bound to some entity, these are defined as <a href="#root/_help_zEY4DaJG4YT5">relations</a> - <p>Other events are bound to some entity, these are defined as <a href="#root/_help_zEY4DaJG4YT5">relations</a> -
meaning that script is triggered only if note has this script attached meaning that script is triggered only if note has this script attached
to it through relations (or it can inherit it).</p> to it through relations (or it can inherit it).</p>
<table> <figure class="table"
<thead> style="width:100%;">
<tr> <table class="ck-table-resized">
<th>Relation</th> <colgroup>
<th>Description</th> <col style="width:20.65%;">
</tr> <col style="width:47.48%;">
</thead> <col style="width:31.87%;">
<tbody> </colgroup>
<tr> <thead>
<td><code>runOnNoteCreation</code> <tr>
</td> <th>Relation</th>
<td>executes when note is created on backend. Use this relation if you want <th>Trigger condition</th>
to run the script for all notes created under a specific subtree. In that <th>Origin entity (see below)</th>
case, create it on the subtree root note and make it inheritable. A new </tr>
note created within the subtree (any depth) will trigger the script.</td> </thead>
</tr> <tbody>
<tr> <tr>
<td><code>runOnChildNoteCreation</code> <td><code spellcheck="false">runOnNoteCreation</code>
</td> </td>
<td>executes when new note is created under the note where this relation is <td>executes when note is created on backend. Use this relation if you want
defined</td> to run the script for all notes created under a specific subtree. In that
</tr> case, create it on the subtree root note and make it inheritable. A new
<tr> note created within the subtree (any depth) will trigger the script.</td>
<td><code>runOnNoteTitleChange</code> <td>The <code spellcheck="false">BNote</code> that got created.</td>
</td> </tr>
<td>executes when note title is changed (includes note creation as well)</td> <tr>
</tr> <td><code spellcheck="false">runOnChildNoteCreation</code>
<tr> </td>
<td><code>runOnNoteContentChange</code> <td>executes when new note is created under the note where this relation is
</td> defined</td>
<td>executes when note content is changed (includes note creation as well).</td> <td>The <code spellcheck="false">BNote</code> of the child that got created.</td>
</tr> </tr>
<tr> <tr>
<td><code>runOnNoteChange</code> <td><code spellcheck="false">runOnNoteTitleChange</code>
</td> </td>
<td>executes when note is changed (includes note creation as well). Does not <td>executes when note title is changed (includes note creation as well)</td>
include content changes</td> <td>The <code spellcheck="false">BNote</code> of the note whose title got changed.</td>
</tr> </tr>
<tr> <tr>
<td><code>runOnNoteDeletion</code> <td><code spellcheck="false">runOnNoteContentChange</code>
</td> </td>
<td>executes when note is being deleted</td> <td>executes when note content is changed (includes note creation as well).</td>
</tr> <td>The <code spellcheck="false">BNote</code> of the note whose content got
<tr> changed.</td>
<td><code>runOnBranchCreation</code> </tr>
</td> <tr>
<td>executes when a branch is created. Branch is a link between parent note <td><code spellcheck="false">runOnNoteChange</code>
and child note and is created e.g. when cloning or moving note.</td> </td>
</tr> <td>executes when note is changed (includes note creation as well). Does not
<tr> include content changes</td>
<td><code>runOnBranchChange</code> <td>The <code spellcheck="false">BNote</code> of the note that got changed.</td>
</td> </tr>
<td>executes when a branch is updated. (since v0.62)</td> <tr>
</tr> <td><code spellcheck="false">runOnNoteDeletion</code>
<tr> </td>
<td><code>runOnBranchDeletion</code> <td>executes when note is being deleted</td>
</td> <td>The <code spellcheck="false">BNote</code> of the note that got (soft) deleted.</td>
<td>executes when a branch is deleted. Branch is a link between parent note </tr>
and child note and is deleted e.g. when moving note (old branch/link is <tr>
deleted).</td> <td><code spellcheck="false">runOnBranchCreation</code>
</tr> </td>
<tr> <td>executes when a branch is created. Branch is a link between parent note
<td><code>runOnAttributeCreation</code> and child note and is created e.g. when cloning or moving note.</td>
</td> <td>The <code spellcheck="false">BBranch</code> that got created.</td>
<td>executes when new attribute is created for the note which defines this </tr>
relation</td> <tr>
</tr> <td><code spellcheck="false">runOnBranchChange</code>
<tr> </td>
<td><code>runOnAttributeChange</code> <td>executes when a branch is updated. (since v0.62)</td>
</td> <td>The <code spellcheck="false">BBranch</code> that got changed.</td>
<td>executes when the attribute is changed of a note which defines this relation. </tr>
This is triggered also when the attribute is deleted</td> <tr>
</tr> <td><code spellcheck="false">runOnBranchDeletion</code>
</tbody> </td>
</table> <td>executes when a branch is deleted. Branch is a link between parent note
and child note and is deleted e.g. when moving note (old branch/link is
deleted).</td>
<td>The <code spellcheck="false">BBranch</code> that got (soft) deleted.</td>
</tr>
<tr>
<td><code spellcheck="false">runOnAttributeCreation</code>
</td>
<td>executes when new attribute is created for the note which defines this
relation</td>
<td>The <code spellcheck="false">BAttribute</code> that got created.</td>
</tr>
<tr>
<td><code spellcheck="false">runOnAttributeChange</code>
</td>
<td>executes when the attribute is changed of a note which defines this relation.
This is triggered also when the attribute is deleted</td>
<td>The <code spellcheck="false">BAttribute</code> that got changed.</td>
</tr>
</tbody>
</table>
</figure>
<h2>Origin entity</h2>
<p>When a script is run by an event such as the ones described above,
<code
spellcheck="false">api.originEntity</code>will get populated with the note, branch or attribute
that triggered the change.</p>
<p>For example, here's a script with <code spellcheck="false">~runOnAttributeChange</code> which
automatically changes the color of a note based on the value of the
<code
spellcheck="false">mycategory</code>label:</p><pre><code class="language-application-javascript-env-frontend">const attr = api.originEntity;
if (attr.name !== "mycategory") return;
const note = api.getNote(attr.noteId);
if (attr.value === "Health") {
note.setLabel("color", "green");
} else {
note.removeLabel("color");
}</code></pre>

2
docs/Developer Guide/Developer Guide/Documentation.md vendored
View File

@ -1,5 +1,5 @@
# Documentation # Documentation
There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/tZh9T30Ojdsq/Documentation_image.png" width="205" height="162"> There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/iivQU4mW8qJE/Documentation_image.png" width="205" height="162">
* The _User Guide_ represents the user-facing documentation. This documentation can be browsed by users directly from within Trilium, by pressing <kbd>F1</kbd>. * The _User Guide_ represents the user-facing documentation. This documentation can be browsed by users directly from within Trilium, by pressing <kbd>F1</kbd>.
* The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers. * The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers.

45
docs/User Guide/User Guide/Scripting/Backend scripts/Events.md vendored
View File

@ -5,22 +5,39 @@
Global events are attached to the script note via label. Simply create e.g. "run" label with some of these values and script note will be executed once the event occurs. Global events are attached to the script note via label. Simply create e.g. "run" label with some of these values and script note will be executed once the event occurs.
<table><thead><tr><th>Label</th><th>Description</th></tr></thead><tbody><tr><td><code>run</code></td><td><p>Defines on which events script should run. Possible values are:</p><ul><li><code>frontendStartup</code> - when Trilium frontend starts up (or is refreshed), but not on mobile.</li><li><code>mobileStartup</code> - when Trilium frontend starts up (or is refreshed), on mobile.</li><li><code>backendStartup</code> - when Trilium backend starts up</li><li><code>hourly</code> - run once an hour. You can use additional label <code>runAtHour</code> to specify at which hour, on the back-end.</li><li><code>daily</code> - run once a day, on the back-end</li></ul></td></tr><tr><td><code>runOnInstance</code></td><td>Specifies that the script should only run on a particular&nbsp;<a class="reference-link" href="../../Advanced%20Usage/Configuration%20(config.ini%20or%20environment%20variables)/Trilium%20instance.md">Trilium instance</a>.</td></tr><tr><td><code>runAtHour</code></td><td>On which hour should this run. Should be used together with <code>#run=hourly</code>. Can be defined multiple times for more runs during the day.</td></tr></tbody></table> <table><thead><tr><th>Label</th><th>Description</th></tr></thead><tbody><tr><td><code spellcheck="false">run</code></td><td><p>Defines on which events script should run. Possible values are:</p><ul><li data-list-item-id="e244b14e102cf1b0d4954e8fd455ea77b"><code spellcheck="false">frontendStartup</code> - when Trilium frontend starts up (or is refreshed), but not on mobile.</li><li data-list-item-id="ea8f8ca86e7b351dd86108848ccb9103a"><code spellcheck="false">mobileStartup</code> - when Trilium frontend starts up (or is refreshed), on mobile.</li><li data-list-item-id="e658488cf1a0862603088ef384e41b8b6"><code spellcheck="false">backendStartup</code> - when Trilium backend starts up</li><li data-list-item-id="ef40ba992fc450d33a18ca4cb031eca66"><code spellcheck="false">hourly</code> - run once an hour. You can use additional label <code spellcheck="false">runAtHour</code> to specify at which hour, on the back-end.</li><li data-list-item-id="e07458d4f55b6eb42468a5535b8425c5f"><code spellcheck="false">daily</code> - run once a day, on the back-end</li></ul></td></tr><tr><td><code spellcheck="false">runOnInstance</code></td><td>Specifies that the script should only run on a particular&nbsp;<a class="reference-link" href="../../Advanced%20Usage/Configuration%20(config.ini%20or%20environment%20variables)/Trilium%20instance.md">Trilium instance</a>.</td></tr><tr><td><code spellcheck="false">runAtHour</code></td><td>On which hour should this run. Should be used together with <code spellcheck="false">#run=hourly</code>. Can be defined multiple times for more runs during the day.</td></tr></tbody></table>
## Entity events ## Entity events
Other events are bound to some entity, these are defined as [relations](../../Advanced%20Usage/Attributes.md) - meaning that script is triggered only if note has this script attached to it through relations (or it can inherit it). Other events are bound to some entity, these are defined as [relations](../../Advanced%20Usage/Attributes.md) - meaning that script is triggered only if note has this script attached to it through relations (or it can inherit it).
| Relation | Description | | Relation | Trigger condition | Origin entity (see below) |
| --- | --- | | --- | --- | --- |
| `runOnNoteCreation` | executes when note is created on backend. Use this relation if you want to run the script for all notes created under a specific subtree. In that case, create it on the subtree root note and make it inheritable. A new note created within the subtree (any depth) will trigger the script. | | `runOnNoteCreation` | executes when note is created on backend. Use this relation if you want to run the script for all notes created under a specific subtree. In that case, create it on the subtree root note and make it inheritable. A new note created within the subtree (any depth) will trigger the script. | The `BNote` that got created. |
| `runOnChildNoteCreation` | executes when new note is created under the note where this relation is defined | | `runOnChildNoteCreation` | executes when new note is created under the note where this relation is defined | The `BNote` of the child that got created. |
| `runOnNoteTitleChange` | executes when note title is changed (includes note creation as well) | | `runOnNoteTitleChange` | executes when note title is changed (includes note creation as well) | The `BNote` of the note whose title got changed. |
| `runOnNoteContentChange` | executes when note content is changed (includes note creation as well). | | `runOnNoteContentChange` | executes when note content is changed (includes note creation as well). | The `BNote` of the note whose content got changed. |
| `runOnNoteChange` | executes when note is changed (includes note creation as well). Does not include content changes | | `runOnNoteChange` | executes when note is changed (includes note creation as well). Does not include content changes | The `BNote` of the note that got changed. |
| `runOnNoteDeletion` | executes when note is being deleted | | `runOnNoteDeletion` | executes when note is being deleted | The `BNote` of the note that got (soft) deleted. |
| `runOnBranchCreation` | executes when a branch is created. Branch is a link between parent note and child note and is created e.g. when cloning or moving note. | | `runOnBranchCreation` | executes when a branch is created. Branch is a link between parent note and child note and is created e.g. when cloning or moving note. | The `BBranch` that got created. |
| `runOnBranchChange` | executes when a branch is updated. (since v0.62) | | `runOnBranchChange` | executes when a branch is updated. (since v0.62) | The `BBranch` that got changed. |
| `runOnBranchDeletion` | executes when a branch is deleted. Branch is a link between parent note and child note and is deleted e.g. when moving note (old branch/link is deleted). | | `runOnBranchDeletion` | executes when a branch is deleted. Branch is a link between parent note and child note and is deleted e.g. when moving note (old branch/link is deleted). | The `BBranch` that got (soft) deleted. |
| `runOnAttributeCreation` | executes when new attribute is created for the note which defines this relation | | `runOnAttributeCreation` | executes when new attribute is created for the note which defines this relation | The `BAttribute` that got created. |
| `runOnAttributeChange` | executes when the attribute is changed of a note which defines this relation. This is triggered also when the attribute is deleted | | `runOnAttributeChange` | executes when the attribute is changed of a note which defines this relation. This is triggered also when the attribute is deleted | The `BAttribute` that got changed. |
## Origin entity
When a script is run by an event such as the ones described above, `api.originEntity` will get populated with the note, branch or attribute that triggered the change.
For example, here's a script with `~runOnAttributeChange` which automatically changes the color of a note based on the value of the `mycategory` label:
```javascript
const attr = api.originEntity;
if (attr.name !== "mycategory") return;
const note = api.getNote(attr.noteId);
if (attr.value === "Health") {
note.setLabel("color", "green");
} else {
note.removeLabel("color");
}
```