mirror of
https://github.com/zadam/trilium.git
synced 2026-03-10 06:00:23 +01:00
docs(user): improve documentation on scripts & active content
This commit is contained in:
Elian Doran
24
docs/User Guide/User Guide/Scripting/Backend scripts.md
vendored
Normal file
24
docs/User Guide/User Guide/Scripting/Backend scripts.md
vendored
Normal file
@@ -0,0 +1,24 @@
|
||||
# Backend scripts
|
||||
Unlike [front-end scripts](Frontend%20Basics.md) which run on the client / browser-side, back-end scripts run directly on the Node.js environment of the Trilium server.
|
||||
|
||||
Back-end scripts can be used both on a <a class="reference-link" href="../Installation%20%26%20Setup/Server%20Installation.md">Server Installation</a> (where it will run on the device the server is running on), or on the <a class="reference-link" href="../Installation%20%26%20Setup/Desktop%20Installation.md">Desktop Installation</a> (where it will run on the PC).
|
||||
|
||||
## Advantages of backend scripts
|
||||
|
||||
The benefit of backend scripts is that they can be pretty powerful, for example to have access to the underlying system, for example it can read files or execute processes.
|
||||
|
||||
However, the main benefit of backend scripts is that they have easier access to the notes since the information about them is already loaded in memory. Whereas on the client, notes have to be manually loaded first.
|
||||
|
||||
## Creating a backend script
|
||||
|
||||
Create a new <a class="reference-link" href="../Note%20Types/Code.md">Code</a> note and select the language _JS backend_.
|
||||
|
||||
## Running backend scripts
|
||||
|
||||
Backend scripts can be either run manually (via the Execute button on the script page), or they can be triggered on certain events.
|
||||
|
||||
In addition, scripts can be run automatically when the server starts up, on a fixed time interval or when a certain event occurs (such as an attribute being modified). For more information, see the dedicated <a class="reference-link" href="Backend%20scripts/Events.md">Events</a> page.
|
||||
|
||||
## Script API
|
||||
|
||||
Trilium exposes a set of APIs that can be directly consumed by scripts, under the `api` object. For a reference of this API, see <a class="reference-link" href="Script%20API/Backend%20API.dat">Backend API</a>.
|
||||
@@ -5,7 +5,7 @@
|
||||
|
||||
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 data-list-item-id="e244b14e102cf1b0d4954e8fd455ea77b"><code>frontendStartup</code> - when Trilium frontend starts up (or is refreshed), but not on mobile.</li><li data-list-item-id="ea8f8ca86e7b351dd86108848ccb9103a"><code>mobileStartup</code> - when Trilium frontend starts up (or is refreshed), on mobile.</li><li data-list-item-id="e658488cf1a0862603088ef384e41b8b6"><code>backendStartup</code> - when Trilium backend starts up</li><li data-list-item-id="ef40ba992fc450d33a18ca4cb031eca66"><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 data-list-item-id="e07458d4f55b6eb42468a5535b8425c5f"><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="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
|
||||
|
||||
|
||||
@@ -1,56 +1,39 @@
|
||||
# Frontend Basics
|
||||
## Frontend API
|
||||
Front-end scripts are custom JavaScript notes that are run on the client (browser environment)
|
||||
|
||||
The frontend api supports two styles, regular scripts that are run with the current app and note context, and widgets that export an object to Trilium to be used in the UI. In both cases, the frontend api of Trilium is available to scripts running in the frontend context as global variable `api`. The members and methods of the api can be seen on the [Script API](Script%20API.md) page.
|
||||
There are four flavors of front-end scripts:
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Regular scripts | These are run with the current app and note context. These can be run either manually or automatically on start-up. |
|
||||
| <a class="reference-link" href="Frontend%20Basics/Custom%20Widgets.md">Custom Widgets</a> | These can introduce new UI elements in various positions, such as near the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Note%20Tree.md">Note Tree</a>, content area or even the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Right%20Sidebar.md">Right Sidebar</a>. |
|
||||
| <a class="reference-link" href="Frontend%20Basics/Launch%20Bar%20Widgets.md">Launch Bar Widgets</a> | Similar to <a class="reference-link" href="Frontend%20Basics/Custom%20Widgets.md">Custom Widgets</a>, but dedicated to the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Launch%20Bar.md">Launch Bar</a>. These can simply introduce new buttons or graphical elements to the bar. |
|
||||
| <a class="reference-link" href="../Note%20Types/Render%20Note.md">Render Note</a> | This allows rendering custom content inside a note, using either HTML or Preact JSX. |
|
||||
|
||||
For more advanced behaviors that do not require a user interface (e.g. batch modifying notes), see <a class="reference-link" href="Backend%20scripts.md">Backend scripts</a>.
|
||||
|
||||
## Scripts
|
||||
|
||||
Scripts don't have any special requirements. They can be run at will using the execute button in the UI or they can be configured to run at certain times using [Attributes](../Advanced%20Usage/Attributes.md) on the note containing the script.
|
||||
Scripts don't have any special requirements. They can be run manually using the _Execute_ button on the code note or they can be run automatically; to do so, set the `run` [label](../Advanced%20Usage/Attributes/Labels.md) to either:
|
||||
|
||||
### Global Events
|
||||
* `frontendStartup` - when Trilium frontend starts up (or is refreshed), but not on mobile.
|
||||
* `mobileStartup` - when Trilium frontend starts up (or is refreshed), on mobile.
|
||||
|
||||
This attribute is called `#run` and it can have any of the following values:
|
||||
|
||||
* `frontendStartup` - executes on frontend upon startup.
|
||||
* `mobileStartup` - executes on mobile frontend upon startup.
|
||||
* `backendStartup` - executes on backend upon startup.
|
||||
* `hourly` - executes once an hour on backend.
|
||||
* `daily` - executes once a day on backend.
|
||||
|
||||
### Entity Events
|
||||
|
||||
These events are triggered by certain [relations](../Advanced%20Usage/Attributes.md) to other notes. Meaning that the script is triggered only if the note has this script attached to it through relations (or it can inherit it).
|
||||
|
||||
* `runOnNoteCreation` - executes when note is created on backend.
|
||||
* `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).
|
||||
* `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.
|
||||
* `runOnBranchDeletion` - executes when a branch is delete. Branch is a link between parent note and child note and is deleted e.g. when moving note (old branch/link is deleted).
|
||||
* `runOnChildNoteCreation` - executes when new note is created under this note.
|
||||
* `runOnAttributeCreation` - executes when new attribute is created under this note.
|
||||
* `runOnAttributeChange` - executes when attribute is changed under this note.
|
||||
> [!NOTE]
|
||||
> Backend scripts have more powerful triggering conditions, for example they can run automatically on a hourly or daily basis, but also on events such as when a note is created or an attribute is modified. See the server-side <a class="reference-link" href="Backend%20scripts/Events.md">Events</a> for more information.
|
||||
|
||||
## Widgets
|
||||
|
||||
Conversely to scripts, widgets do have some specific requirements in order to work. A widget must:
|
||||
Widgets require a certain format in order for Trilium to be able to integrate them into the UI.
|
||||
|
||||
* Extend [BasicWidget](https://triliumnext.github.io/Notes/frontend_api/BasicWidget.html) or one of it's subclasses.
|
||||
* Create a new instance and assign it to `module.exports`.
|
||||
* Define a `parentWidget` member to determine where it should be displayed.
|
||||
* Define a `position` (integer) that determines the location via sort order.
|
||||
* Have a `#widget` attribute on the containing note.
|
||||
* Create, render, and return your element in the render function.
|
||||
* For [BasicWidget](https://triliumnext.github.io/Notes/frontend_api/BasicWidget.html) and [NoteContextAwareWidget](https://triliumnext.github.io/Notes/frontend_api/NoteContextAwareWidget.html)you should create `this.$widget` and render it in `doRender()`.
|
||||
* For [RightPanelWidget](https://triliumnext.github.io/Notes/frontend_api/RightPanelWidget.html) the `this.$widget` and `doRender()` are already handled and you should instead return the value in `doRenderBody()`.
|
||||
* For legacy widgets, the script note must export a `BasicWidget` or a derived one (see <a class="reference-link" href="Frontend%20Basics/Custom%20Widgets/Note%20context%20aware%20widget.md">Note context aware widget</a> or <a class="reference-link" href="Frontend%20Basics/Custom%20Widgets/Right%20pane%20widget.md">Right pane widget</a>).
|
||||
* For Preact widgets, a built-in helper called `defineWidget` needs to be used.
|
||||
|
||||
### parentWidget
|
||||
For more information, see <a class="reference-link" href="Frontend%20Basics/Custom%20Widgets.md">Custom Widgets</a>.
|
||||
|
||||
* `left-pane` - This renders the widget on the left side of the screen where the note tree lives.
|
||||
* `center-pane` - This renders the widget in the center of the layout in the same location that notes and splits appear.
|
||||
* `note-detail-pane` - This renders the widget _with_ the note in the center pane. This means it can appear multiple times with splits.
|
||||
* `right-pane` - This renders the widget to the right of any opened notes.
|
||||
## Script API
|
||||
|
||||
The front-end API of Trilium is available to all scripts running in the front-end context as global variable `api`. For a reference of the API, see <a class="reference-link" href="Script%20API/Frontend%20API">Frontend API</a>.
|
||||
|
||||
### Tutorial
|
||||
|
||||
|
||||
@@ -63,7 +63,7 @@ export default defineWidget({
|
||||
|
||||
A widget can be placed in one of the following sections of the applications:
|
||||
|
||||
<table class="ck-table-resized"><colgroup><col style="width:15.59%;"><col style="width:30.42%;"><col style="width:16.68%;"><col style="width:37.31%;"></colgroup><thead><tr><th>Value for <code>parentWidget</code></th><th>Description</th><th>Sample widget</th><th>Special requirements</th></tr></thead><tbody><tr><th><code>left-pane</code></th><td>Appears within the same pane that holds the <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Note%20Tree.md">Note Tree</a>.</td><td>Same as above, with only a different <code>parentWidget</code>.</td><td>None.</td></tr><tr><th><code>center-pane</code></th><td>In the content area. If a split is open, the widget will span all of the splits.</td><td>See example above.</td><td>None.</td></tr><tr><th><code>note-detail-pane</code></th><td><p>In the content area, inside the note detail area. If a split is open, the widget will be contained inside the split.</p><p>This is ideal if the widget is note-specific.</p></td><td><a class="reference-link" href="Custom%20Widgets/Note%20context%20aware%20widget.md">Note context aware widget</a></td><td><ul><li data-list-item-id="ec06332efcc3039721606c052f0d913fa">The widget must export a <code>class</code> and not an instance of the class (e.g. <code>no new</code>) because it needs to be multiplied for each note, so that splits work correctly.</li><li data-list-item-id="e8da690a2a8df148f6b5fc04ba1611688">Since the <code>class</code> is exported instead of an instance, the <code>parentWidget</code> getter must be <code>static</code>, otherwise the widget is ignored.</li></ul></td></tr><tr><th><code>right-pane</code></th><td>In the <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Right%20Sidebar.md">Right Sidebar</a>, as a dedicated section.</td><td><a class="reference-link" href="Custom%20Widgets/Right%20pane%20widget.md">Right pane widget</a></td><td><ul><li data-list-item-id="efe008d361e224f422582552648e1afe7">Although not mandatory, it's best to use a <code>RightPanelWidget</code> instead of a <code>BasicWidget</code> or a <code>NoteContextAwareWidget</code>.</li></ul></td></tr></tbody></table>
|
||||
<table class="ck-table-resized"><colgroup><col style="width:15.59%;"><col style="width:30.42%;"><col style="width:16.68%;"><col style="width:37.31%;"></colgroup><thead><tr><th>Value for <code spellcheck="false">parentWidget</code></th><th>Description</th><th>Sample widget</th><th>Special requirements</th></tr></thead><tbody><tr><th><code spellcheck="false">left-pane</code></th><td>Appears within the same pane that holds the <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Note%20Tree.md">Note Tree</a>.</td><td>Same as above, with only a different <code spellcheck="false">parentWidget</code>.</td><td>None.</td></tr><tr><th><code spellcheck="false">center-pane</code></th><td>In the content area. If a split is open, the widget will span all of the splits.</td><td>See example above.</td><td>None.</td></tr><tr><th><code spellcheck="false">note-detail-pane</code></th><td><p>In the content area, inside the note detail area. If a split is open, the widget will be contained inside the split.</p><p>This is ideal if the widget is note-specific.</p></td><td><a class="reference-link" href="Custom%20Widgets/Note%20context%20aware%20widget.md">Note context aware widget</a></td><td><ul><li data-list-item-id="ec06332efcc3039721606c052f0d913fa">The widget must export a <code spellcheck="false">class</code> and not an instance of the class (e.g. <code spellcheck="false">no new</code>) because it needs to be multiplied for each note, so that splits work correctly.</li><li data-list-item-id="e8da690a2a8df148f6b5fc04ba1611688">Since the <code spellcheck="false">class</code> is exported instead of an instance, the <code spellcheck="false">parentWidget</code> getter must be <code spellcheck="false">static</code>, otherwise the widget is ignored.</li></ul></td></tr><tr><th><code spellcheck="false">right-pane</code></th><td>In the <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Right%20Sidebar.md">Right Sidebar</a>, as a dedicated section.</td><td><a class="reference-link" href="Custom%20Widgets/Right%20pane%20widget.md">Right pane widget</a></td><td><ul><li data-list-item-id="efe008d361e224f422582552648e1afe7">Although not mandatory, it's best to use a <code spellcheck="false">RightPanelWidget</code> instead of a <code spellcheck="false">BasicWidget</code> or a <code spellcheck="false">NoteContextAwareWidget</code>.</li></ul></td></tr></tbody></table>
|
||||
|
||||
To position the widget somewhere else, just change the value passed to `get parentWidget()` for legacy widgets or the `parent` field for Preact. Do note that some positions such as `note-detail-pane` and `right-pane` have special requirements that need to be accounted for (see the table above).
|
||||
|
||||
@@ -71,4 +71,24 @@ To position the widget somewhere else, just change the value passed to `get pare
|
||||
|
||||
Launch bar widgets are similar to _Custom widgets_ but are specific to the <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Launch%20Bar.md">Launch Bar</a>. See <a class="reference-link" href="Launch%20Bar%20Widgets.md">Launch Bar Widgets</a> for more information.
|
||||
|
||||
## Custom position
|
||||
## Custom position
|
||||
|
||||
The position of a custom widget is defined via a `position` integer.
|
||||
|
||||
In legacy widgets:
|
||||
|
||||
```
|
||||
class MyWidget extends api.BasicWidget {
|
||||
// [..
|
||||
get position() { return 10; }
|
||||
}
|
||||
```
|
||||
|
||||
In Preact widgets:
|
||||
|
||||
```
|
||||
export default defineWidget({
|
||||
// [...]
|
||||
position: 10
|
||||
});
|
||||
```
|
||||
@@ -5,12 +5,12 @@ Launch bar widgets are a subset of <a class="reference-link" href="Custom%20Wid
|
||||
|
||||
Unlike <a class="reference-link" href="Custom%20Widgets.md">Custom Widgets</a>, the process of setting up a launch bar widget is slightly different:
|
||||
|
||||
1. Create a Code note of type _JavaScript (front-end)_.
|
||||
1. Create a Code note of type _JavaScript (front-end)_ or JSX (for Preact-based widgets).
|
||||
* The script itself uses the same concepts as <a class="reference-link" href="Custom%20Widgets.md">Custom Widgets</a>, including the use of a `NoteContextAwareWidget` or a `BasicWidget` (according to needs).
|
||||
* As examples, see <a class="reference-link" href="Launch%20Bar%20Widgets/Note%20Title%20Widget.md">Note Title Widget</a> and <a class="reference-link" href="Launch%20Bar%20Widgets/Analog%20Watch.md">Analog Watch</a>.
|
||||
* As examples in both legacy and Preact format, see <a class="reference-link" href="Launch%20Bar%20Widgets/Note%20Title%20Widget.md">Note Title Widget</a> and <a class="reference-link" href="Launch%20Bar%20Widgets/Analog%20Watch.md">Analog Watch</a>.
|
||||
2. Don't set `#widget`, as that attribute is reserved for <a class="reference-link" href="Custom%20Widgets.md">Custom Widgets</a>.
|
||||
3. In the <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Global%20menu.md">Global menu</a>, select _Configure launchbar_.
|
||||
4. In the _Visible Launchers_ section, select _Add a custom widget_.
|
||||
5. Give the newly created launcher a name (and optionally a name).
|
||||
6. In the <a class="reference-link" href="../../Advanced%20Usage/Attributes/Promoted%20Attributes.md">Promoted Attributes</a> section, modify the _widget_ field to point to the newly created note.
|
||||
7. Refresh the UI.
|
||||
7. [Refresh](../../Troubleshooting/Refreshing%20the%20application.md) the UI.
|
||||
Reference in New Issue
Block a user