gaschz/trilium
1
0
Fork 0
mirror of https://github.com/zadam/trilium.git synced 2025-12-22 07:14:24 +01:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

docs(user): improve examples for right pane widgets

Browse Source
This commit is contained in:
Elian Doran 2025-12-20 13:29:38 +02:00
parent 666c434c74
commit c581ee7252
No known key found for this signature in database
3 changed files with 166 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Right pane widget.html generated vendored
View File

@ -1,17 +1,70 @@
<h2>Key highlights</h2>
<ul> <ul>
<li><code>doRender</code> must not be overridden, instead <code>doRenderBody()</code> has <li data-list-item-id="e08ebed8d78d0359c71a72be31cd95074"><code spellcheck="false">doRender</code> must not be overridden, instead
to be overridden. <code
<ul> spellcheck="false">doRenderBody()</code>has to be overridden.
<li><code>doRenderBody</code> can optionally be <code>async</code>.</li> <ul>
</ul> <li data-list-item-id="e34a4e9826ab89e0ce8ded8786a803f3a"><code spellcheck="false">doRenderBody</code> can optionally be <code spellcheck="false">async</code>.</li>
</ul>
</li> </li>
<li><code>parentWidget()</code> must be set to <code>“rightPane”</code>.</li> <li data-list-item-id="e24bc184054a9c87a6c7695bb65c8d30b"><code spellcheck="false">parentWidget()</code> must be set to <code spellcheck="false">“rightPane”</code>.</li>
<li><code>widgetTitle()</code> getter can optionally be overriden, otherwise <li
the widget will be displayed as “Untitled widget”.</li> data-list-item-id="e581cbed615c9be4f249274c5c51c6a18"><code spellcheck="false">widgetTitle()</code> getter can optionally be
</ul><pre><code class="language-text-x-trilium-auto">const template = `&lt;div&gt;Hi&lt;/div&gt;`; overriden, otherwise the widget will be displayed as “Untitled widget”.</li>
</ul>
<h2>Example for new layout</h2>
<aside class="admonition important">
<p>This section addresses example that are tailored for the&nbsp;<a class="reference-link"
href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/Vc8PjrjAGuOp/_help_IjZS7iK5EXtb">New Layout</a>&nbsp;(available
starting with v0.101.0) where the right pane widget/sidebar is no longer
shown or hidden based on the widgets it has.&nbsp;</p>
</aside>
<h3>Title widget</h3>
<p>This is an example of a context-aware widget which displays the title
of the current note:</p><pre><code class="language-text-x-trilium-auto">class NoteTitleWidget extends api.RightPanelWidget {
get widgetTitle() { return "Note title"; }
get parentWidget() { return "right-pane" }
doRenderBody() {
this.$body.empty();
if (this.note) {
this.$body.append($("&lt;div&gt;").text(this.note.title));
}
}
async refreshWithNote() {
this.doRenderBody();
}
}
module.exports = new NoteTitleWidget();</code></pre>
<h3>Clock</h3>
<p>A simple widget which will show the current time, as an example on how
to dynamically change the content of the widget periodically.</p><pre><code class="language-text-x-trilium-auto">const template = `&lt;div&gt;&lt;/div&gt;`;
class ToDoListWidget extends api.RightPanelWidget { class ToDoListWidget extends api.RightPanelWidget {
get widgetTitle() { return "Clock"; }
get parentWidget() { return "right-pane" }
async doRenderBody() {
if (!this.timer) {
this.timer = setInterval(() =&gt; {
this.$body.empty().append(`The time is: &lt;span&gt;${new Date().toLocaleString()}&lt;/span&gt;`);
}, 1000);
}
this.$body.empty().append(`The time is: &lt;span&gt;${new Date().toLocaleString()}&lt;/span&gt;`);
}
}
module.exports = new ToDoListWidget();</code></pre>
<h2>Example for old layout</h2>
<p>Here's a widget that displays a basic message ("Hi"):</p><pre><code class="language-text-x-trilium-auto">const template = `&lt;div&gt;Hi&lt;/div&gt;`;
class HelloWorldWidget extends api.RightPanelWidget {
get widgetTitle() { get widgetTitle() {
return "Title goes here"; return "Title goes here";
} }
@ -27,9 +80,19 @@ class ToDoListWidget extends api.RightPanelWidget {
} }
} }
module.exports = new ToDoListWidget();</code></pre> module.exports = new HelloWorldWidget();</code></pre>
<p>The implementation is in <code>src/public/app/widgets/right_panel_widget.js</code>.</p> <h3>Conditionally changing visibility</h3>
<h2>Conditionally changing visibility</h2> <p>In <code spellcheck="false">refreshWithNote</code>:</p><pre><code class="language-text-x-trilium-auto">const visible = true; // replace with your own visibility logic
<p>In <code>refreshWithNote</code>:</p><pre><code class="language-text-x-trilium-auto">const visible = true; // replace with your own visibility logic
this.toggleInt(visible); this.toggleInt(visible);
this.triggerCommand("reEvaluateRightPaneVisibility");</code></pre> this.triggerCommand("reEvaluateRightPaneVisibility");</code></pre>
<h2>Altering the position within the sidebar</h2>
<p>By default, the sidebar items are displayed in the order they are found
by the application when searching for <code spellcheck="false">#widget</code> notes.</p>
<p>It is possible to make a widget appear higher or lower up, by adjusting
its <code spellcheck="false">position</code> property:</p><pre><code class="language-text-x-diff">class MyWidget extends api.RightPanelWidget {
+ get position() { return 20 };
}</code></pre>
<p>Generally the default position starts from 10 and increases by 10 with
each item, including the default Table of Contents and Highlights list.</p>

7
docs/User Guide/!!!meta.json vendored
View File

@ -15734,6 +15734,13 @@
"value": "right-pane-widget", "value": "right-pane-widget",
"isInheritable": false, "isInheritable": false,
"position": 20 "position": 20
},
{
"type": "relation",
"name": "internalLink",
"value": "IjZS7iK5EXtb",
"isInheritable": false,
"position": 30
} }
], ],
"format": "markdown", "format": "markdown",

88
docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Right pane widget.md vendored
View File

@ -1,13 +1,75 @@
# Right pane widget # Right pane widget
## Key highlights
* `doRender` must not be overridden, instead `doRenderBody()` has to be overridden. * `doRender` must not be overridden, instead `doRenderBody()` has to be overridden.
* `doRenderBody` can optionally be `async`. * `doRenderBody` can optionally be `async`.
* `parentWidget()` must be set to `“rightPane”`. * `parentWidget()` must be set to `“rightPane”`.
* `widgetTitle()` getter can optionally be overriden, otherwise the widget will be displayed as “Untitled widget”. * `widgetTitle()` getter can optionally be overriden, otherwise the widget will be displayed as “Untitled widget”.
## Example for new layout
> [!IMPORTANT]
> This section addresses example that are tailored for the <a class="reference-link" href="../../../Basic%20Concepts%20and%20Features/UI%20Elements/New%20Layout.md">New Layout</a> (available starting with v0.101.0) where the right pane widget/sidebar is no longer shown or hidden based on the widgets it has. 
### Title widget
This is an example of a context-aware widget which displays the title of the current note:
```
class NoteTitleWidget extends api.RightPanelWidget {
get widgetTitle() { return "Note title"; }
get parentWidget() { return "right-pane" }
doRenderBody() {
this.$body.empty();
if (this.note) {
this.$body.append($("<div>").text(this.note.title));
}
}
async refreshWithNote() {
this.doRenderBody();
}
}
module.exports = new NoteTitleWidget();
```
### Clock
A simple widget which will show the current time, as an example on how to dynamically change the content of the widget periodically.
```
const template = `<div></div>`;
class ToDoListWidget extends api.RightPanelWidget {
get widgetTitle() { return "Clock"; }
get parentWidget() { return "right-pane" }
async doRenderBody() {
if (!this.timer) {
this.timer = setInterval(() => {
this.$body.empty().append(`The time is: <span>${new Date().toLocaleString()}</span>`);
}, 1000);
}
this.$body.empty().append(`The time is: <span>${new Date().toLocaleString()}</span>`);
}
}
module.exports = new ToDoListWidget();
```
## Example for old layout
Here's a widget that displays a basic message ("Hi"):
``` ```
const template = `<div>Hi</div>`; const template = `<div>Hi</div>`;
class ToDoListWidget extends api.RightPanelWidget { class HelloWorldWidget extends api.RightPanelWidget {
get widgetTitle() { get widgetTitle() {
return "Title goes here"; return "Title goes here";
@ -24,12 +86,10 @@ class ToDoListWidget extends api.RightPanelWidget {
} }
} }
module.exports = new ToDoListWidget(); module.exports = new HelloWorldWidget();
``` ```
The implementation is in `src/public/app/widgets/right_panel_widget.js`. ### Conditionally changing visibility
## Conditionally changing visibility
In `refreshWithNote`: In `refreshWithNote`:
@ -37,4 +97,20 @@ In `refreshWithNote`:
const visible = true; // replace with your own visibility logic const visible = true; // replace with your own visibility logic
this.toggleInt(visible); this.toggleInt(visible);
this.triggerCommand("reEvaluateRightPaneVisibility"); this.triggerCommand("reEvaluateRightPaneVisibility");
``` ```
## Altering the position within the sidebar
By default, the sidebar items are displayed in the order they are found by the application when searching for `#widget` notes.
It is possible to make a widget appear higher or lower up, by adjusting its `position` property:
```diff
class MyWidget extends api.RightPanelWidget {
+ get position() { return 20 };
}
```
Generally the default position starts from 10 and increases by 10 with each item, including the default Table of Contents and Highlights list.