diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.html index ce9190a4e..56a1c3491 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.html @@ -4,149 +4,146 @@

Preact with JSX vs. vanilla jQuery

In older versions of Trilium, custom widgets were exclusively written in a combination of jQuery with Trilium's internal widget architecture - (e.g., BasicWidget, NoteContextAwareWidget).

+ (e.g., BasicWidget, NoteContextAwareWidget).

Starting with v0.101.0, custom widgets can also be written in JSX using the Preact framework. Both legacy and Preact widgets have the same capabilities, with a single difference:

Wherever possible, widget examples will be both in the legacy and Preact format.

Creating a custom widget

    -
  1. Create a Code note.
    2. -
  2. Set the language to: +
  3. Create a Code note.
    4. +
  4. Set the language to:
      -
    1. JavaScript (frontend) for legacy widgets using jQuery.
      2. -
    2. JSX for Preact widgets. You might need to go to Options → Code to enable +
    3. JavaScript (frontend) for legacy widgets using jQuery.
      4. +
    4. JSX for Preact widgets. You might need to go to Options → Code to enable the language first.
    -
    5. -
  5. Apply the #widget label.
    6. + +
  6. Apply the #widget label.

Getting started with a simple example

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.

- - - - - - - - - - - - - -
LegacyPreact (v0.101.0+)
class HelloNoteDetail extends api.BasicWidget {
+
Legacy version (jQuery)
class HelloCenterPane extends api.BasicWidget {
 
-
constructor() {
-    super();
-    this.contentSized();
+    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();

+
Refresh the application and the widget
+  should appear underneath the content area.

+
Preact version
import { defineWidget } from "trilium:preact";
 
-doRender() {
-    this.<!--FORMULA_INLINE_1766517018225_0-->("&lt;span&gt;Center pane&lt;/span&gt;");
-}

-        
}

-        
module.exports = new HelloNoteDetail();

-        
-        

-      
import { defineWidget } from "trilium:preact";
export default defineWidget({
-
parent: "center-pane",
-render: () =&gt; &lt;span&gt;Center pane from Preact.&lt;/span&gt;

-        
});

-        
-
-
-

+export default defineWidget({ + parent: "center-pane", + render: () => <span>Center pane from Preact.</span> +});

Refresh the application and the widget should appear underneath the content area.

Widget location (parent widget)

A widget can be placed in one of the following sections of the applications:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
+
Value for parentWidget - DescriptionSample widgetSpecial requirements
left-pane - Appears within the same pane that holds the Note Tree.Same as above, with only a different parentWidget.None.
center-pane - In the content area. If a split is open, the widget will span all of the - splits.See example above.None.
note-detail-pane - -

In the content area, inside the note detail area. If a split is open, - the widget will be contained inside the split.

-

This is ideal if the widget is note-specific.

- 		Note context aware widget - -
    -
  • The widget must export a class and not an instance of the class - (e.g. no new) because it needs to be multiplied for each note, - so that splits work correctly.
    • -
  • Since the class is exported instead of an instance, the parentWidget getter - must be static, otherwise the widget is ignored.
    • -
-
right-pane - In the Right Sidebar, - as a dedicated section.Right pane widget - -
    -
  • Although not mandatory, it's best to use a RightPanelWidget instead - of a BasicWidget or a NoteContextAwareWidget.
    • -
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value for parentWidget + DescriptionSample widgetSpecial requirements
left-pane + Appears within the same pane that holds the Note Tree.Same as above, with only a different parentWidget.None.
center-pane + In the content area. If a split is open, the widget will span all of the + splits.See example above.None.
note-detail-pane + +

In the content area, inside the note detail area. If a split is open, + the widget will be contained inside the split.

+

This is ideal if the widget is note-specific.

+ 		Note context aware widget + +
    +
  • The widget must export a class and not an + instance of the class (e.g. no new) because + it needs to be multiplied for each note, so that splits work correctly.
    • +
  • Since the class is exported instead of an + instance, the parentWidget getter must be + static, otherwise the widget is ignored.
    • +
+
right-pane + In the Right Sidebar, + as a dedicated section.Right pane widget + +
    +
  • Although not mandatory, it's best to use a RightPanelWidget instead + of a BasicWidget or a NoteContextAwareWidget.
    • +
+
-

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).

+ +

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-panehave special requirements that need to be accounted for + (see the table above).

Launch bar widgets

Launch bar widgets are similar to Custom widgets but are specific to the Launch Bar. diff --git a/docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.md b/docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.md index 431b814db..392f5a734 100644 --- a/docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.md +++ b/docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.md @@ -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. -
LegacyPreact (v0.101.0+)
class HelloNoteDetail extends api.BasicWidget {
+### Legacy version (jQuery)
 
-
constructor() {
-    super();
-    this.contentSized();
+```
+class HelloCenterPane extends api.BasicWidget {
+
+    constructor() {
+        super();
+        this.contentSized();
+    }
+
+    get parentWidget() { return "center-pane" }
+
+    doRender() {
+        this.$widget = $("Center pane");
+    }
+    
 }
 
-get parentWidget() { return "center-pane" }
+module.exports = new HelloCenterPane();
+```
 
-doRender() {
-    this.<!--FORMULA_INLINE_1766517018225_0-->("&lt;span&gt;Center pane&lt;/span&gt;");
-}
}
module.exports = new HelloNoteDetail();
import { defineWidget } from "trilium:preact";
export default defineWidget({
-
parent: "center-pane",
-render: () =&gt; &lt;span&gt;Center pane from Preact.&lt;/span&gt;
});
+[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: () => Center pane from Preact. +}); +``` [Refresh the application](../../Troubleshooting/Refreshing%20the%20application.md) and the widget should appear underneath the content area. @@ -44,7 +63,7 @@ render: () =&gt; &lt;span&gt;Center pane from Preact.&lt;/span&a A widget can be placed in one of the following sections of the applications: -
Value for parentWidgetDescriptionSample widgetSpecial requirements
left-paneAppears within the same pane that holds the Note Tree.Same as above, with only a different parentWidget.None.
center-paneIn the content area. If a split is open, the widget will span all of the splits.See example above.None.
note-detail-pane

In the content area, inside the note detail area. If a split is open, the widget will be contained inside the split.

This is ideal if the widget is note-specific.

Note context aware widget
  • The widget must export a class and not an instance of the class (e.g. no new) because it needs to be multiplied for each note, so that splits work correctly.
  • Since the class is exported instead of an instance, the parentWidget getter must be static, otherwise the widget is ignored.
right-paneIn the Right Sidebar, as a dedicated section.Right pane widget
  • Although not mandatory, it's best to use a RightPanelWidget instead of a BasicWidget or a NoteContextAwareWidget.
+
Value for parentWidgetDescriptionSample widgetSpecial requirements
left-paneAppears within the same pane that holds the Note Tree.Same as above, with only a different parentWidget.None.
center-paneIn the content area. If a split is open, the widget will span all of the splits.See example above.None.
note-detail-pane

In the content area, inside the note detail area. If a split is open, the widget will be contained inside the split.

This is ideal if the widget is note-specific.

Note context aware widget
  • The widget must export a class and not an instance of the class (e.g. no new) because it needs to be multiplied for each note, so that splits work correctly.
  • Since the class is exported instead of an instance, the parentWidget getter must be static, otherwise the widget is ignored.
right-paneIn the Right Sidebar, as a dedicated section.Right pane widget
  • Although not mandatory, it's best to use a RightPanelWidget instead of a BasicWidget or a NoteContextAwareWidget.
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).