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.
*
* <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;
@ -278,12 +282,16 @@ export interface Api {
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;
/**
* @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;

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>
<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
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>
<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:
@ -36,7 +36,7 @@
<h3>Setup needed environment variables</h3>
<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>
<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:
image: triliumnext/trilium
container_name: trilium

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

@ -5,7 +5,8 @@
<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
once the event occurs.</p>
<table>
<figure class="table">
<table>
<thead>
<tr>
<th>Label</th>
@ -14,113 +15,159 @@
</thead>
<tbody>
<tr>
<td><code>run</code>
<td><code spellcheck="false">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>
<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>runOnInstance</code>
<td><code spellcheck="false">runOnInstance</code>
</td>
<td>Specifies that the script should only run on a particular&nbsp;<a class="reference-link"
href="#root/_help_c5xB8m4g2IY6">Trilium instance</a>.</td>
</tr>
<tr>
<td><code>runAtHour</code>
<td><code spellcheck="false">runAtHour</code>
</td>
<td>On which hour should this run. Should be used together with <code>#run=hourly</code>.
<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>
</table>
</figure>
<h2>Entity events</h2>
<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
to it through relations (or it can inherit it).</p>
<table>
<figure class="table"
style="width:100%;">
<table class="ck-table-resized">
<colgroup>
<col style="width:20.65%;">
<col style="width:47.48%;">
<col style="width:31.87%;">
</colgroup>
<thead>
<tr>
<th>Relation</th>
<th>Description</th>
<th>Trigger condition</th>
<th>Origin entity (see below)</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>runOnNoteCreation</code>
<td><code spellcheck="false">runOnNoteCreation</code>
</td>
<td>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.</td>
<td>The <code spellcheck="false">BNote</code> that got created.</td>
</tr>
<tr>
<td><code>runOnChildNoteCreation</code>
<td><code spellcheck="false">runOnChildNoteCreation</code>
</td>
<td>executes when new note is created under the note where this relation is
defined</td>
<td>The <code spellcheck="false">BNote</code> of the child that got created.</td>
</tr>
<tr>
<td><code>runOnNoteTitleChange</code>
<td><code spellcheck="false">runOnNoteTitleChange</code>
</td>
<td>executes when note title is changed (includes note creation as well)</td>
<td>The <code spellcheck="false">BNote</code> of the note whose title got changed.</td>
</tr>
<tr>
<td><code>runOnNoteContentChange</code>
<td><code spellcheck="false">runOnNoteContentChange</code>
</td>
<td>executes when note content is changed (includes note creation as well).</td>
<td>The <code spellcheck="false">BNote</code> of the note whose content got
changed.</td>
</tr>
<tr>
<td><code>runOnNoteChange</code>
<td><code spellcheck="false">runOnNoteChange</code>
</td>
<td>executes when note is changed (includes note creation as well). Does not
include content changes</td>
<td>The <code spellcheck="false">BNote</code> of the note that got changed.</td>
</tr>
<tr>
<td><code>runOnNoteDeletion</code>
<td><code spellcheck="false">runOnNoteDeletion</code>
</td>
<td>executes when note is being deleted</td>
<td>The <code spellcheck="false">BNote</code> of the note that got (soft) deleted.</td>
</tr>
<tr>
<td><code>runOnBranchCreation</code>
<td><code spellcheck="false">runOnBranchCreation</code>
</td>
<td>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.</td>
<td>The <code spellcheck="false">BBranch</code> that got created.</td>
</tr>
<tr>
<td><code>runOnBranchChange</code>
<td><code spellcheck="false">runOnBranchChange</code>
</td>
<td>executes when a branch is updated. (since v0.62)</td>
<td>The <code spellcheck="false">BBranch</code> that got changed.</td>
</tr>
<tr>
<td><code>runOnBranchDeletion</code>
<td><code spellcheck="false">runOnBranchDeletion</code>
</td>
<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>runOnAttributeCreation</code>
<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>runOnAttributeChange</code>
<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>
</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
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 _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.
<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
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 |
| --- | --- |
| `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. |
| `runOnChildNoteCreation` | executes when new note is created under the note where this relation is defined |
| `runOnNoteTitleChange` | executes when note title is changed (includes note creation as well) |
| `runOnNoteContentChange` | executes when note content is changed (includes note creation as well). |
| `runOnNoteChange` | executes when note is changed (includes note creation as well). Does not include content changes |
| `runOnNoteDeletion` | executes when note is being 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. |
| `runOnBranchChange` | executes when a branch is updated. (since v0.62) |
| `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). |
| `runOnAttributeCreation` | executes when new attribute is created for the note which defines this relation |
| `runOnAttributeChange` | executes when the attribute is changed of a note which defines this relation. This is triggered also when the attribute is deleted |
| 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. | The `BNote` that got created. |
| `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) | The `BNote` of the note whose title got changed. |
| `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 | The `BNote` of the note that got changed. |
| `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. | The `BBranch` that got created. |
| `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). | The `BBranch` that got (soft) deleted. |
| `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 | 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");
}
```