feat(docs): reorganize scripting notes and finalize attribute reference

docs/User Guide/User Guide/Scripting/Custom Widgets.md

@@ -0,0 +1,9 @@
+# Custom Widgets
+It's possible to create custom widget in three possible locations where you can display your custom content.
+
+Positions are:
+
+*   `left-pane`
+*   `center-pane`
+*   `note-detail-pane` - located within `center-pane`, but specific to note (split)
+*   `right-pane`

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

@@ -22,10 +22,10 @@ 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](../Advanced%20Usage/Attributes.md) to the [note](../Basic%20Concepts%20and%20Features/Notes.md).
+2.  Assign the `#widget` [attribute](../../Advanced%20Usage/Attributes.md) to the [note](../../Basic%20Concepts%20and%20Features/Notes.md).
 3.  Restart Trilium or reload the window.
 
-To verify that the widget is working, open the developer tools (`Cmd` + `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](../Basic%20Concepts%20and%20Features/Notes.md) has the `#widget` [attribute](../Advanced%20Usage/Attributes.md).
+To verify that the widget is working, open the developer tools (`Cmd` + `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](../../Basic%20Concepts%20and%20Features/Notes.md) has the `#widget` [attribute](../../Advanced%20Usage/Attributes.md).
 
 ### Step 2: Adding an UI Element
 
@@ -85,7 +85,7 @@ After reloading Trilium, the button should now appear at the bottom left of the
 
 ### 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](../Note%20Types/Code/Script%20API.md).
+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](../Script%20API.md).
 
 ```
 class MyWidget extends api.BasicWidget {

docs/User Guide/User Guide/Scripting/Custom Widgets/Word count widget.md

@@ -0,0 +1,89 @@
+# Word count widget
+> [!TIP]
+> This widget is also present in new installations in the <a class="reference-link" href="../../Advanced%20Usage/Database/Demo%20Notes.md">Demo Notes</a>.
+
+Create a <a class="reference-link" href="../../Note%20Types/Code.md">Code</a> note of type JS frontend and **give it a** `#widget` **label**.
+
+```
+/*
+ * This defines a custom widget which displays number of words and characters in a current text note.
+ * To be activated for a given note, add label 'wordCount' to the note, you can also make it inheritable and thus activate it for the whole subtree.
+ * 
+ * See it in action in "Books" and its subtree.
+ */
+const TPL = `<div style="padding: 10px; border-top: 1px solid var(--main-border-color); contain: none;">
+    <strong>Word count: </strong>
+    <span class="word-count"></span>
+
+    &nbsp;
+
+    <strong>Character count: </strong>
+    <span class="character-count"></span>
+</div`;
+
+class WordCountWidget extends api.NoteContextAwareWidget {
+    get position() { return 100; } // higher value means position towards the bottom/right
+    
+    get parentWidget() { return 'center-pane'; }
+    
+    doRender() {
+        this.$widget = $(TPL);
+        this.$wordCount = this.$widget.find('.word-count');
+        this.$characterCount = this.$widget.find('.character-count');
+        return this.$widget;
+    }
+    
+    async refreshWithNote(note) {
+        if (note.type !== 'text' || !note.hasLabel('wordCount')) { 
+            // show widget only on text notes and when marked with 'wordCount' label
+            this.toggleInt(false); // hide
+            
+            return;
+        }
+        
+        this.toggleInt(true); // display
+        
+        const {content} = await note.getNoteComplement();
+        
+        const text = $(content).text(); // get plain text only
+        
+        const counts = this.getCounts(text);
+
+        this.$wordCount.text(counts.words);
+        this.$characterCount.text(counts.characters);
+    }
+    
+    getCounts(text) {
+        const chunks = text
+            .split(/[\s-+:,/\\]+/)
+            .filter(chunk => chunk !== '');
+        
+        let words;
+        
+        if (chunks.length === 1 && chunks[0] === '') {
+            words = 0;
+        }
+        else {
+            words = chunks.length;
+        }
+        
+        const characters = chunks.join('').length;
+        
+        return {words, characters};
+    }
+    
+    async entitiesReloadedEvent({loadResults}) {
+        if (loadResults.isNoteContentReloaded(this.noteId)) {
+            this.refresh();
+        }
+    }
+}
+
+module.exports = new WordCountWidget();
+```
+
+After you make changes it is necessary to [restart Trilium](../../Troubleshooting/Refreshing%20the%20application.md) so that the layout can be rebuilt.
+
+At the bottom of the note you can see the resulting widget:
+
+<figure class="image"><img style="aspect-ratio:792/603;" src="Word count widget_image.png" width="792" height="603"></figure>

docs/User Guide/User Guide/Scripting/Events.md

@@ -0,0 +1,14 @@
+# Events
+[Script](../Scripting.md) notes can be triggered by events. Note that these are backend events and thus relation need to point to the "JS backend" code note.
+
+## Global events
+
+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.
+
+<figure class="table"><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><code>frontendStartup</code> - when Trilium frontend starts up (or is refreshed), but not on mobile.</li><li><code>mobileStartup</code> - when Trilium frontend starts up (or is refreshed), on mobile.</li><li><code>backendStartup</code> - when Trilium backend starts up</li><li><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><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&nbsp;<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></figure>
+
+## Entity events
+
+Other events are bound to some entity, these are defined as [relations](../Advanced%20Usage/Attributes.md) - meaning that script is triggered only if note has this script attached to it through relations (or it can inherit it).
+
+<figure class="table"><table><thead><tr><th>Relation</th><th>Description</th></tr></thead><tbody><tr><td><code>runOnNoteCreation</code></td><td>executes when note is created on backend. Use this relation if you want to run the script for all notes created under a specific subtree. In that case, create it on the subtree root note and make it inheritable. A new note created within the subtree (any depth) will trigger the script.</td></tr><tr><td><code>runOnChildNoteCreation</code></td><td>executes when new note is created under the note where this relation is defined</td></tr><tr><td><code>runOnNoteTitleChange</code></td><td>executes when note title is changed (includes note creation as well)</td></tr><tr><td><code>runOnNoteContentChange</code></td><td>executes when note content is changed (includes note creation as well).</td></tr><tr><td><code>runOnNoteChange</code></td><td>executes when note is changed (includes note creation as well). Does not include content changes</td></tr><tr><td><code>runOnNoteDeletion</code></td><td>executes when note is being deleted</td></tr><tr><td><code>runOnBranchCreation</code></td><td>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.</td></tr><tr><td><code>runOnBranchChange</code></td><td>executes when a branch is updated. (since v0.62)</td></tr><tr><td><code>runOnBranchDeletion</code></td><td>executes when a branch is deleted. Branch is a link between parent note and child note and is deleted e.g. when moving note (old branch/link is deleted).</td></tr><tr><td><code>runOnAttributeCreation</code></td><td>executes when new attribute is created for the note which defines this relation</td></tr><tr><td><code>runOnAttributeChange</code></td><td>executes when the attribute is changed of a note which defines this relation. This is triggered also when the attribute is deleted</td></tr></tbody></table></figure>

docs/User Guide/User Guide/Scripting/Frontend Basics.md

@@ -1,7 +1,7 @@
 # Frontend Basics
 ## Frontend API
 
-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](../Note%20Types/Code/Script%20API.md) page.
+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.
 
 ## Scripts
 
@@ -54,4 +54,4 @@ Conversely to scripts, widgets do have some specific requirements in order to wo
 
 ### Tutorial
 
-For more information on building widgets, take a look at [Widget Basics](Widget%20Basics.md).
+For more information on building widgets, take a look at [Widget Basics](Custom%20Widgets/Widget%20Basics.md).

docs/User Guide/User Guide/Scripting/Script API.md

@@ -0,0 +1,7 @@
+# Script API
+Trilium offers a "Script API" that enables scripts to perform various useful functions. There are two main APIs available:
+
+*   [Frontend API](https://triliumnext.github.io/Notes/frontend_api/FrontendScriptApi.html)
+*   [Backend API](https://triliumnext.github.io/Notes/backend_api/BackendScriptApi.html)
+
+Please note that the Script API is currently experimental and may undergo changes in future updates.