gaschz/trilium
1
0
Fork 0
mirror of https://github.com/zadam/trilium.git synced 2026-01-03 05:04:23 +01:00
Code Issues Actions 12 Packages Projects Releases Wiki Activity

docs(user): broken code blocks due to table

Browse Source
This commit is contained in:
Elian Doran 2025-12-24 00:26:29 +02:00
parent 04fffb7ee0
commit fc8605a14f
No known key found for this signature in database
2 changed files with 143 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,149 +4,146 @@
<h2>Preact with JSX vs. vanilla jQuery</h2>
<p>In older versions of Trilium, custom widgets were exclusively written
in a combination of jQuery with Trilium's internal widget architecture
(e.g., <code>BasicWidget</code>, <code>NoteContextAwareWidget</code>).</p>
(e.g., <code spellcheck="false">BasicWidget</code>, <code spellcheck="false">NoteContextAwareWidget</code>).</p>
<p>Starting with v0.101.0, custom widgets can also be written in JSX using
the&nbsp;<a class="reference-link" href="#root/_help_KLsqhjaqh1QW">Preact</a>&nbsp;framework.
Both legacy and Preact widgets have the same capabilities, with a single
difference:</p>
<ul>
<li>Preact widgets are content-sized by default whereas legacy widgets need <code>this.contentSized()</code> applied
in the constructor. For more information, see the corresponding section
in&nbsp;<a class="reference-link" href="#root/_help_gMkgcLJ6jBkg">Troubleshooting</a>.</li>
<li data-list-item-id="eb15aa9f439c6bdb1c8e88a5319a8955f">Preact widgets are content-sized by default whereas legacy widgets need
<code
spellcheck="false">this.contentSized()</code>applied in the constructor. For more information,
see the corresponding section in&nbsp;<a class="reference-link" href="#root/_help_gMkgcLJ6jBkg">Troubleshooting</a>.</li>
</ul>
<p>Wherever possible, widget examples will be both in the legacy and Preact
format.</p>
<h2>Creating a custom widget</h2>
<ol>
<li>Create a&nbsp;<a class="reference-link" href="#root/_help_6f9hih2hXXZk">Code</a>&nbsp;note.</li>
<li>Set the language to:
<li data-list-item-id="ecec088aa52d1e12a9f32d37574ee5249">Create a&nbsp;<a class="reference-link" href="#root/_help_6f9hih2hXXZk">Code</a>&nbsp;note.</li>
<li
data-list-item-id="e409320f56952473e762318b10e553b66">Set the language to:
<ol>
<li>JavaScript (frontend) for legacy widgets using jQuery.</li>
<li>JSX for Preact widgets. You might need to go to Options → Code to enable
<li data-list-item-id="e5817ea91f2dc0d56ceb0066c20c33f43">JavaScript (frontend) for legacy widgets using jQuery.</li>
<li data-list-item-id="e59157f3af10c4e325b925e49f6abc649">JSX for Preact widgets. You might need to go to Options → Code to enable
the language first.</li>
</ol>
</li>
<li>Apply the <code>#widget</code> <a href="#root/_help_HI6GBBIduIgv">label</a>.</li>
</li>
<li data-list-item-id="eccbc8c98b9fc01d638c0b76273d5fff5">Apply the <code spellcheck="false">#widget</code> <a href="#root/_help_HI6GBBIduIgv">label</a>.</li>
</ol>
<h2>Getting started with a simple example</h2>
<p>Let's start by creating a widget that shows a message near the content
area. Follow the previous section to create a code note, and use the following
content.</p>
<table>
<thead>
<tr>
<th>Legacy</th>
<th>Preact (v0.101.0+)</th>
</tr>
</thead>
<tbody>
<tr>
<td><pre><code class="language-text-x-trilium-auto">class HelloNoteDetail extends api.BasicWidget {
<h3>Legacy version (jQuery)</h3><pre><code class="language-text-x-trilium-auto">class HelloCenterPane extends api.BasicWidget {
<pre><code class="language-text-x-trilium-auto">constructor() {
super();
this.contentSized();
constructor() {
super();
this.contentSized();
}
get parentWidget() { return "center-pane" }
doRender() {
this.$widget = $("&lt;span&gt;Center pane&lt;/span&gt;");
}
}
get parentWidget() { return "center-pane" }
module.exports = new HelloCenterPane();</code></pre>
<p><a href="#root/_help_s8alTXmpFR61">Refresh the application</a> and the widget
should appear underneath the content area.</p>
<h3>Preact version</h3><pre><code class="language-text-x-trilium-auto">import { defineWidget } from "trilium:preact";
doRender() {
this.&lt;!--FORMULA_INLINE_1766517018225_0--&gt;("&amp;lt;span&amp;gt;Center pane&amp;lt;/span&amp;gt;");
}</code></pre>
<p>}</p>
<p>module.exports = new HelloNoteDetail();</p>
</code>
</pre>
</td>
<td><pre><code class="language-text-x-trilium-auto">import { defineWidget } from "trilium:preact";<p></p><p>export default defineWidget({
</p><pre><code class="language-text-x-trilium-auto">parent: "center-pane",
render: () =&amp;gt; &amp;lt;span&amp;gt;Center pane from Preact.&amp;lt;/span&amp;gt;</code></pre>
<p>});</p>
</code>
</pre>
</td>
</tr>
</tbody>
</table>
<p></p>
export default defineWidget({
parent: "center-pane",
render: () =&gt; &lt;span&gt;Center pane from Preact.&lt;/span&gt;
});</code></pre>
<p><a href="#root/_help_s8alTXmpFR61">Refresh the application</a> and the widget
should appear underneath the content area.</p>
<h2>Widget location (parent widget)</h2>
<p>A widget can be placed in one of the following sections of the applications:</p>
<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&nbsp;<a class="reference-link"
href="#root/_help_oPVyFC7WL2Lp">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="#root/_help_GhurYZjh8e1V">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&nbsp;<a class="reference-link" href="#root/_help_RnaPdbciOfeq">Right Sidebar</a>,
as a dedicated section.</td>
<td><a class="reference-link" href="#root/_help_M8IppdwVHSjG">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>
<figure
class="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&nbsp;<a class="reference-link"
href="#root/_help_oPVyFC7WL2Lp">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="#root/_help_GhurYZjh8e1V">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&nbsp;<a class="reference-link" href="#root/_help_RnaPdbciOfeq">Right Sidebar</a>,
as a dedicated section.</td>
<td><a class="reference-link" href="#root/_help_M8IppdwVHSjG">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>
<p>To position the widget somewhere else, just change the value passed to <code>get parentWidget()</code> for
legacy widgets or the <code>parent</code> field for Preact. Do note that
some positions such as <code>note-detail-pane</code> and <code>right-pane</code> have
special requirements that need to be accounted for (see the table above).</p>
</figure>
<p>To position the widget somewhere else, just change the value passed to
<code
spellcheck="false">get parentWidget()</code>for legacy widgets or the <code spellcheck="false">parent</code> field
for Preact. Do note that some positions such as <code spellcheck="false">note-detail-pane</code> and
<code
spellcheck="false">right-pane</code>have special requirements that need to be accounted for
(see the table above).</p>
<h2>Launch bar widgets</h2>
<p>Launch bar widgets are similar to <em>Custom widgets</em> but are specific
to the&nbsp;<a class="reference-link" href="#root/_help_xYmIYSP6wE3F">Launch Bar</a>.

41
docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.md vendored
View File

@ -23,20 +23,39 @@ Wherever possible, widget examples will be both in the legacy and Preact format.
Let's start by creating a widget that shows a message near the content area. Follow the previous section to create a code note, and use the following content.
<table><thead><tr><th>Legacy</th><th>Preact (v0.101.0+)</th></tr></thead><tbody><tr><td><pre><code class="language-text-x-trilium-auto">class HelloNoteDetail extends api.BasicWidget {
### Legacy version (jQuery)
<pre><code class="language-text-x-trilium-auto">constructor() {
super();
this.contentSized();
```
class HelloCenterPane extends api.BasicWidget {
constructor() {
super();
this.contentSized();
}
get parentWidget() { return "center-pane" }
doRender() {
this.$widget = $("<span>Center pane</span>");
}
}
get parentWidget() { return "center-pane" }
module.exports = new HelloCenterPane();
```
doRender() {
this.&lt;!--FORMULA_INLINE_1766517018225_0--&gt;("&amp;lt;span&amp;gt;Center pane&amp;lt;/span&amp;gt;");
}</code></pre><p>}</p><p>module.exports = new HelloNoteDetail();</p></code></pre></td><td><pre><code class="language-text-x-trilium-auto">import { defineWidget } from "trilium:preact";<p></p><p>export default defineWidget({
</p><pre><code class="language-text-x-trilium-auto">parent: "center-pane",
render: () =&amp;gt; &amp;lt;span&amp;gt;Center pane from Preact.&amp;lt;/span&amp;gt;</code></pre><p>});</p></code></pre></td></tr></tbody></table>
[Refresh the application](../../Troubleshooting/Refreshing%20the%20application.md) and the widget should appear underneath the content area.
### Preact version
```
import { defineWidget } from "trilium:preact";
export default defineWidget({
parent: "center-pane",
render: () => <span>Center pane from Preact.</span>
});
```
[Refresh the application](../../Troubleshooting/Refreshing%20the%20application.md) and the widget should appear underneath the content area.
@ -44,7 +63,7 @@ render: () =&amp;gt; &amp;lt;span&amp;gt;Center pane from Preact.&amp;lt;/span&a
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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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).