mirror of
https://github.com/TriliumNext/Trilium.git
synced 2025-12-10 03:53:37 -06:00
docs(script): clarify originEntity and activeContext
This commit is contained in:
Elian Doran
parent
2f13a1ad21
commit
cb3aced2ed
@ -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,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 <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
|
||||
|
||||
@ -5,6 +5,7 @@
|
||||
<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>
|
||||
<figure class="table">
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
@ -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 <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>
|
||||
|
||||
</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>
|
||||
</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>
|
||||
@ -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.
|
||||
|
||||
@ -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 <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 <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");
|
||||
}
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user