Trilium/docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Widget Basics.md

Widget Basics

This guide will walk you through creating a basic widget inside Trilium. By following these steps, you'll learn how to build a simple UI element that interacts with the user.

Step 1: The Basic Widget Structure

To start, we'll create the most basic widget possible. Here's a simple example:

class MyWidget extends api.BasicWidget {
    get position() { return 1; }
    get parentWidget() { return "left-pane"; }
    
    doRender() {
        this.$widget = $("<div id='my-widget'>");
        return this.$widget;
    }
}

module.exports = new MyWidget();

To implement this widget:

1. Create a new JS Frontend note in Trilium and paste in the code above.
2. Assign the #widget attribute to the note.
3. Restart Trilium or reload the window.

To verify that the widget is working, open the developer tools (Ctrl + Shift + I) and run document.querySelector("#my-widget"). If the element is found, the widget is functioning correctly. If undefined is returned, double-check that the note has the #widget attribute.

Step 2: Adding an UI Element

Next, let's improve the widget by adding a button to it.

const template = `<div id="my-widget"><button>Click Me!</button></div>`;

class MyWidget extends api.BasicWidget {
    get position() {return 1;}
    get parentWidget() {return "left-pane"}

    doRender() {
        this.$widget = $(template);
        return this.$widget;
    }
}

module.exports = new MyWidget();

After making this change, reload Trilium. You should now see a button in the top-left corner of the left pane.

Step 3: Styling the Widget

To make the button more visually appealing and position it correctly, we'll apply some custom styling. Trilium includes Box Icons, which we'll use to replace the button text with an icon. For example the bx bxs-magic-wand icon.

Here's the updated template:

const template = `<div id="my-widget"><button class="tree-floating-button bx bxs-magic-wand tree-settings-button"></button></div>`;

Next, we'll adjust the button's position using CSS:

class MyWidget extends api.BasicWidget {
    get position() { return 1; }
    get parentWidget() { return "left-pane"; }
    
    doRender() {
        this.$widget = $(template);
        this.cssBlock(`#my-widget {
            position: absolute;
            bottom: 40px;
            left: 60px;
            z-index: 1;
        }`);
        return this.$widget;
    }
}

module.exports = new MyWidget();

After reloading Trilium, the button should now appear at the bottom left of the left pane, alongside other action buttons.

Step 4: Adding User Interaction

Let’s make the button interactive by showing a message when it’s clicked. We'll use the api.showMessage method from the Script API.

class MyWidget extends api.BasicWidget {
    get position() { return 1; }
    get parentWidget() { return "left-pane"; }
    
    doRender() {
        this.$widget = $(template);
        this.cssBlock(`#my-widget {
            position: absolute;
            bottom: 40px;
            left: 60px;
            z-index: 1;
        }`);
        this.$widget.find("button").on("click", () => api.showMessage("Hello World!"));
        return this.$widget;
    }
}

module.exports = new MyWidget();

parentWidget() can be given the following values:

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

Reload the application one last time. When you click the button, a "Hello World!" message should appear, confirming that your widget is fully functional.