frontend script API documentation

.gitignore

@@ -6,4 +6,5 @@ yarn-error.log
 *.db
 config.ini
 cert.key
-cert.crt
+cert.crt
+docs/

package.json

@@ -21,7 +21,9 @@
     "package-forge": "electron-forge package",
     "make-forge": "electron-forge make",
     "publish-forge": "electron-forge publish",
-    "build-docs": "jsdoc src/entities/*.js src/services/backend_script_api.js"
+    "build-backend-docs": "jsdoc -d ./docs/backend_api src/entities/*.js src/services/backend_script_api.js",
+    "build-frontend-docs": "jsdoc -d ./docs/frontend_api src/public/javascripts/entities/*.js src/public/javascripts/services/frontend_script_api.js",
+    "build-docs": "npm run build-backend-docs && npm run build-frontend-docs"
   },
   "dependencies": {
     "async-mutex": "^0.1.3",

src/public/javascripts/dialogs/jump_to_note.js

@@ -31,7 +31,7 @@ async function showDialog() {
 
             const notePath = linkService.getNotePathFromLabel(ui.item.value);
 
-            treeService.activateNode(notePath);
+            treeService.activateNote(notePath);
 
             $dialog.dialog('close');
         }

src/public/javascripts/entities/branch.js

@@ -1,19 +1,28 @@
+/** Represents mapping between note and parent note */
 class Branch {
     constructor(treeCache, row) {
         this.treeCache = treeCache;
+        /** @param {string} primary key */
         this.branchId = row.branchId;
+        /** @param {string} */
         this.noteId = row.noteId;
         this.note = null;
+        /** @param {string} */
         this.parentNoteId = row.parentNoteId;
+        /** @param {int} */
         this.notePosition = row.notePosition;
+        /** @param {string} */
         this.prefix = row.prefix;
+        /** @param {boolean} */
         this.isExpanded = row.isExpanded;
     }
 
+    /** @returns {NoteShort} */
     async getNote() {
         return await this.treeCache.getNote(this.noteId);
     }
 
+    /** @returns {boolean} true if it's top level, meaning its parent is root note */
     isTopLevel() {
         return this.parentNoteId === 'root';
     }

src/public/javascripts/entities/note_full.js

@@ -1,13 +1,18 @@
 import NoteShort from './note_short.js';
 
+/**
+ * Represents full note, specifically including note's content.
+ */
 class NoteFull extends NoteShort {
     constructor(treeCache, row) {
         super(treeCache, row);
 
+        /** @param {string} */
         this.content = row.content;
 
         if (this.content !== "" && this.isJson()) {
             try {
+                /** @param {object} */
                 this.jsonContent = JSON.parse(this.content);
             }
             catch(e) {}

src/public/javascripts/entities/note_short.js

@@ -1,19 +1,31 @@
+/**
+ * This note's representation is used in note tree and is kept in TreeCache.
+ * Its notable omission is the note content.
+ */
 class NoteShort {
     constructor(treeCache, row) {
         this.treeCache = treeCache;
+        /** @param {string} */
         this.noteId = row.noteId;
+        /** @param {string} */
         this.title = row.title;
+        /** @param {boolean} */
         this.isProtected = row.isProtected;
+        /** @param {string} one of 'text', 'code', 'file' or 'render' */
         this.type = row.type;
+        /** @param {string} content-type, e.g. "application/json" */
         this.mime = row.mime;
+        /** @param {boolean} */
         this.archived = row.archived;
         this.cssClass = row.cssClass;
     }
 
+    /** @returns {boolean} */
     isJson() {
         return this.mime === "application/json";
     }
 
+    /** @returns {Promise<Array.<Branch>>} */
     async getBranches() {
         const branchIds = this.treeCache.parents[this.noteId].map(
             parentNoteId => this.treeCache.getBranchIdByChildParent(this.noteId, parentNoteId));
@@ -21,11 +33,13 @@ class NoteShort {
         return this.treeCache.getBranches(branchIds);
     }
 
+    /** @returns {boolean} */
     hasChildren() {
         return this.treeCache.children[this.noteId]
             && this.treeCache.children[this.noteId].length > 0;
     }
 
+    /** @returns {Promise<Array.<Branch>>} */
     async getChildBranches() {
         if (!this.treeCache.children[this.noteId]) {
             return [];
@@ -37,18 +51,22 @@ class NoteShort {
         return await this.treeCache.getBranches(branchIds);
     }
 
+    /** @returns {Array.<string>} */
     getParentNoteIds() {
         return this.treeCache.parents[this.noteId] || [];
     }
 
+    /** @returns {Promise<Array.<NoteShort>>} */
     async getParentNotes() {
         return await this.treeCache.getNotes(this.getParentNoteIds());
     }
 
+    /** @returns {Array.<string>} */
     getChildNoteIds() {
         return this.treeCache.children[this.noteId] || [];
     }
 
+    /** @returns {Promise<Array.<NoteShort>>} */
     async getChildNotes() {
         return await this.treeCache.getNotes(this.getChildNoteIds());
     }

src/public/javascripts/services/bootstrap.js

@@ -17,7 +17,7 @@ import noteDetailService from './note_detail.js';
 import noteType from './note_type.js';
 import protected_session from './protected_session.js';
 import searchNotesService from './search_notes.js';
-import ScriptApi from './script_api.js';
+import FrontendScriptApi from './frontend_script_api.js';
 import ScriptContext from './script_context.js';
 import sync from './sync.js';
 import treeService from './tree.js';
@@ -88,7 +88,7 @@ if (utils.isElectron()) {
             await treeService.reload();
         }
 
-        await treeService.activateNode(parentNoteId);
+        await treeService.activateNote(parentNoteId);
 
         setTimeout(() => {
             const node = treeService.getCurrentNode();

src/public/javascripts/services/file.js

@@ -21,7 +21,7 @@ $("#file-upload").change(async function() {
 
     await treeService.reload();
 
-    await treeService.activateNode(resp.noteId);
+    await treeService.activateNote(resp.noteId);
 });
 
 export default {

src/public/javascripts/services/frontend_script_api.js

@@ -0,0 +1,186 @@
+import treeService from './tree.js';
+import server from './server.js';
+import utils from './utils.js';
+import infoService from './info.js';
+import linkService from './link.js';
+import treeCache from './tree_cache.js';
+
+/**
+ * @constructor
+ * @hideconstructor
+ */
+function FrontendScriptApi(startNote, currentNote, originEntity = null) {
+    const $pluginButtons = $("#plugin-buttons");
+
+    /** @property {object} note where script started executing */
+    this.startNote = startNote;
+    /** @property {object} note where script is currently executing */
+    this.currentNote = currentNote;
+    /** @property {object|null} entity whose event triggered this execution */
+    this.originEntity = originEntity;
+
+    /**
+     * Activates note in the tree and in the note detail.
+     *
+     * @method
+     * @param {string} notePath (or noteId)
+     * @returns {Promise<void>}
+     */
+    this.activateNote = treeService.activateNote;
+
+    /**
+     * Activates newly created note. Compared to this.activateNote() also refreshes tree.
+     *
+     * @param {string} notePath (or noteId)
+     * @return {Promise<void>}
+     */
+    this.activateNewNote = async notePath => {
+        await treeService.reload();
+
+        await treeService.activateNote(notePath, true);
+    };
+
+    /**
+     * Adds new button the the plugin area.
+     *
+     * @param {object} options
+     */
+    this.addButtonToToolbar = opts => {
+        const buttonId = "toolbar-button-" + opts.title.replace(/[^a-zA-Z0-9]/g, "-");
+
+        $("#" + buttonId).remove();
+
+        const icon = $("<span>")
+            .addClass("ui-icon ui-icon-" + opts.icon);
+
+        const button = $('<button>')
+            .addClass("btn btn-xs")
+            .click(opts.action)
+            .append(icon)
+            .append($("<span>").text(opts.title));
+
+        button.attr('id', buttonId);
+
+        $pluginButtons.append(button);
+
+        if (opts.shortcut) {
+            $(document).bind('keydown', opts.shortcut, opts.action);
+
+            button.attr("title", "Shortcut " + opts.shortcut);
+        }
+    };
+
+    function prepareParams(params) {
+        if (!params) {
+            return params;
+        }
+
+        return params.map(p => {
+            if (typeof p === "function") {
+                return "!@#Function: " + p.toString();
+            }
+            else {
+                return p;
+            }
+        });
+    }
+
+    /**
+     * Executes given anonymous function on the server.
+     * Internally this serializes the anonymous function into string and sends it to backend via AJAX.
+     *
+     * @param {string} script - script to be executed on the backend
+     * @param {Array.<*>} params - list of parameters to the anonymous function to be send to backend
+     * @return {Promise<*>} return value of the executed function on the backend
+     */
+    this.runOnServer = async (script, params = []) => {
+        if (typeof script === "function") {
+            script = script.toString();
+        }
+
+        const ret = await server.post('script/exec', {
+            script: script,
+            params: prepareParams(params),
+            startNoteId: startNote.noteId,
+            currentNoteId: currentNote.noteId,
+            originEntityName: "notes", // currently there's no other entity on frontend which can trigger event
+            originEntityId: originEntity ? originEntity.noteId : null
+        });
+
+        if (ret.success) {
+            return ret.executionResult;
+        }
+        else {
+            throw new Error("server error: " + ret.error);
+        }
+    };
+
+    /**
+     * Returns list of notes. If note is missing from cache, it's loaded.
+     *
+     * This is often used to bulk-fill the cache with notes which would have to be picked one by one
+     * otherwise (by e.g. createNoteLink())
+     *
+     * @param {Array.<string>} noteIds
+     * @param {boolean} [silentNotFoundError] - don't report error if the note is not found
+     * @return {Promise<Array.<NoteShort>>}
+     */
+    this.getNotes = async (noteIds, silentNotFoundError = false) => await treeCache.getNotes(noteIds, silentNotFoundError);
+
+    /**
+     * Instance name identifies particular Trilium instance. It can be useful for scripts
+     * if some action needs to happen on only one specific instance.
+     *
+     * @return {string}
+     */
+    this.getInstanceName = () => window.glob.instanceName;
+
+    /**
+     * @method
+     * @param {Date} date
+     * @returns {string} date in YYYY-MM-DD format
+     */
+    this.formatDateISO = utils.formatDateISO;
+
+    /**
+     * @method
+     * @param {string} str
+     * @returns {Date} parsed object
+     */
+    this.parseDate = utils.parseDate;
+
+    /**
+     * Show info message to the user.
+     *
+     * @method
+     * @param {string} message
+     */
+    this.showMessage = infoService.showMessage;
+
+    /**
+     * Show error message to the user.
+     *
+     * @method
+     * @param {string} message
+     */
+    this.showError = infoService.showError;
+
+    /**
+     * Refresh tree
+     *
+     * @method
+     * @returns {Promise<void>}
+     */
+    this.refreshTree = treeService.reload;
+
+    /**
+     * Create note link (jQuery object) for given note.
+     *
+     * @method
+     * @param {string} notePath (or noteId)
+     * @param {string} [noteTitle] - if not present we'll use note title
+     */
+    this.createNoteLink = linkService.createNoteLink;
+}
+
+export default FrontendScriptApi;

src/public/javascripts/services/link.js

@@ -61,7 +61,7 @@ function goToLink(e) {
         notePath = getNotePathFromLink(address);
     }
 
-    treeService.activateNode(notePath);
+    treeService.activateNote(notePath);
 
     // this is quite ugly hack, but it seems like we can't close the tooltip otherwise
     $("[role='tooltip']").remove();

src/public/javascripts/services/note_detail.js

@@ -336,7 +336,7 @@ async function loadAttributes() {
             const $openButton = $("<button>").addClass("btn btn-small").text("Open").click(() => {
                 const notePath = linkService.getNotePathFromLabel($input.val());
 
-                treeService.activateNode(notePath);
+                treeService.activateNote(notePath);
             });
 
             $actionCell.append($openButton);

src/public/javascripts/services/script_api.js

@@ -1,105 +0,0 @@
-import treeService from './tree.js';
-import server from './server.js';
-import utils from './utils.js';
-import infoService from './info.js';
-import linkService from './link.js';
-import treeCache from './tree_cache.js';
-
-function ScriptApi(startNote, currentNote, originEntity = null) {
-    const $pluginButtons = $("#plugin-buttons");
-
-    async function activateNote(notePath) {
-        await treeService.activateNode(notePath);
-    }
-
-    async function activateNewNote(notePath) {
-        await treeService.reload();
-
-        await treeService.activateNode(notePath, true);
-    }
-
-    function addButtonToToolbar(opts) {
-        const buttonId = "toolbar-button-" + opts.title.replace(/[^a-zA-Z0-9]/g, "-");
-
-        $("#" + buttonId).remove();
-
-        const icon = $("<span>")
-            .addClass("ui-icon ui-icon-" + opts.icon);
-
-        const button = $('<button>')
-            .addClass("btn btn-xs")
-            .click(opts.action)
-            .append(icon)
-            .append($("<span>").text(opts.title));
-
-        button.attr('id', buttonId);
-
-        $pluginButtons.append(button);
-
-        if (opts.shortcut) {
-            $(document).bind('keydown', opts.shortcut, opts.action);
-
-            button.attr("title", "Shortcut " + opts.shortcut);
-        }
-    }
-
-    function prepareParams(params) {
-        if (!params) {
-            return params;
-        }
-
-        return params.map(p => {
-            if (typeof p === "function") {
-                return "!@#Function: " + p.toString();
-            }
-            else {
-                return p;
-            }
-        });
-    }
-
-    async function runOnServer(script, params = []) {
-        if (typeof script === "function") {
-            script = script.toString();
-        }
-
-        const ret = await server.post('script/exec', {
-            script: script,
-            params: prepareParams(params),
-            startNoteId: startNote.noteId,
-            currentNoteId: currentNote.noteId,
-            originEntityName: "notes", // currently there's no other entity on frontend which can trigger event
-            originEntityId: originEntity ? originEntity.noteId : null
-        });
-
-        if (ret.success) {
-            return ret.executionResult;
-        }
-        else {
-            throw new Error("server error: " + ret.error);
-        }
-    }
-
-    return {
-        startNote: startNote,
-        currentNote: currentNote,
-        originEntity: originEntity,
-        // needs to have the longform, can't be shortened!
-        // used also to load many rows to cache before further code starts using them
-        getNotes: async (noteIds, silentNotFoundError = false) => await treeCache.getNotes(noteIds, silentNotFoundError),
-        addButtonToToolbar,
-        activateNote,
-        activateNewNote,
-        getInstanceName: () => window.glob.instanceName,
-        runOnServer,
-        formatDateISO: utils.formatDateISO,
-        parseDate: utils.parseDate,
-        showMessage: infoService.showMessage,
-        showError: infoService.showError,
-        reloadTree: treeService.reload, // deprecated
-        refreshTree: treeService.reload,
-        createNoteLink: linkService.createNoteLink
-    }
-}
-
-export default ScriptApi;

src/public/javascripts/services/script_context.js

@@ -1,4 +1,4 @@
-import ScriptApi from './script_api.js';
+import FrontendScriptApi from './frontend_script_api.js';
 import utils from './utils.js';
 
 function ScriptContext(startNote, allNotes, originEntity = null) {
@@ -7,7 +7,7 @@ function ScriptContext(startNote, allNotes, originEntity = null) {
     return {
         modules: modules,
         notes: utils.toObject(allNotes, note => [note.noteId, note]),
-        apis: utils.toObject(allNotes, note => [note.noteId, ScriptApi(startNote, note, originEntity)]),
+        apis: utils.toObject(allNotes, note => [note.noteId, new FrontendScriptApi(startNote, note, originEntity)]),
         require: moduleNoteIds => {
             return moduleName => {
                 const candidates = allNotes.filter(note => moduleNoteIds.includes(note.noteId));

src/public/javascripts/services/search_notes.js

@@ -73,7 +73,7 @@ async function saveSearch() {
 
     await treeService.reload();
 
-    await treeService.activateNode(noteId);
+    await treeService.activateNote(noteId);
 }
 
 $searchInput.keyup(e => {

src/public/javascripts/services/tree.js

@@ -100,7 +100,7 @@ async function expandToNote(notePath, expandOpts) {
     }
 }
 
-async function activateNode(notePath, newNote) {
+async function activateNote(notePath, newNote) {
     utils.assertArguments(notePath);
 
     const node = await expandToNote(notePath);
@@ -295,7 +295,7 @@ async function treeInitialized() {
     }
 
     if (startNotePath) {
-        const node = await activateNode(startNotePath);
+        const node = await activateNote(startNotePath);
 
         // looks like this this doesn't work when triggered immediatelly after activating node
         // so waiting a second helps
@@ -562,7 +562,7 @@ $(window).bind('hashchange', function() {
     if (getCurrentNotePath() !== notePath) {
         console.log("Switching to " + notePath + " because of hash change");
 
-        activateNode(notePath);
+        activateNote(notePath);
     }
 });
 
@@ -579,7 +579,7 @@ export default {
     setBranchBackgroundBasedOnProtectedStatus,
     setProtected,
     expandToNote,
-    activateNode,
+    activateNote,
     getCurrentNode,
     getCurrentNotePath,
     setCurrentNotePathToHash,

src/services/backend_script_api.js

@@ -17,11 +17,11 @@ const messagingService = require('./messaging');
  * @hideconstructor
  */
 function BackendScriptApi(startNote, currentNote, originEntity) {
-    /** @param {Note} */
+    /** @property {Note} note where script started executing */
     this.startNote = startNote;
-    /** @param {Note} */
+    /** @property {Note} note where script is currently executing */
     this.currentNote = currentNote;
-    /** @param {Entity} */
+    /** @property {Entity} entity whose event triggered this executions */
     this.originEntity = originEntity;
 
     this.axios = axios;
@@ -145,7 +145,7 @@ function BackendScriptApi(startNote, currentNote, originEntity) {
      * @param {string} parentNoteId - create new note under this parent
      * @param {string} title
      * @param {string} [content]
-     * @params {object} [extraOptions]
+     * @param {object} [extraOptions]
      * @returns {Promise<Object>} object contains attributes "note" and "branch" which contain newly created entities
      */
     this.createNote = noteService.createNote;
@@ -202,7 +202,7 @@ function BackendScriptApi(startNote, currentNote, originEntity) {
      * transactional by default.
      *
      * @method
-     * @params {function} func
+     * @param {function} func
      * @returns {Promise<?>} result of func callback
      */
     this.transactional = sql.transactional;