mirror of
https://github.com/zadam/trilium.git
synced 2025-10-30 01:36:24 +01:00
651 lines
21 KiB
HTML
651 lines
21 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>JSDoc: Source: services/frontend_script_api.js</title>
|
|
|
|
<script src="scripts/prettify/prettify.js"> </script>
|
|
<script src="scripts/prettify/lang-css.js"> </script>
|
|
<!--[if lt IE 9]>
|
|
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
|
|
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div id="main">
|
|
|
|
<h1 class="page-title">Source: services/frontend_script_api.js</h1>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section>
|
|
<article>
|
|
<pre class="prettyprint source linenums"><code>import server from './server.js';
|
|
import utils from './utils.js';
|
|
import toastService from './toast.js';
|
|
import linkService from './link.js';
|
|
import froca from './froca.js';
|
|
import noteTooltipService from './note_tooltip.js';
|
|
import protectedSessionService from './protected_session.js';
|
|
import dateNotesService from './date_notes.js';
|
|
import searchService from './search.js';
|
|
import CollapsibleWidget from '../widgets/collapsible_widget.js';
|
|
import ws from "./ws.js";
|
|
import appContext from "./app_context.js";
|
|
import NoteContextAwareWidget from "../widgets/note_context_aware_widget.js";
|
|
import NoteContextCachingWidget from "../widgets/note_context_caching_widget.js";
|
|
import BasicWidget from "../widgets/basic_widget.js";
|
|
|
|
/**
|
|
* This is the main frontend API interface for scripts. It's published in the local "api" object.
|
|
*
|
|
* @constructor
|
|
* @hideconstructor
|
|
*/
|
|
function FrontendScriptApi(startNote, currentNote, originEntity = null, $container = null) {
|
|
const $pluginButtons = $("#plugin-buttons");
|
|
|
|
/** @property {jQuery} container of all the rendered script content */
|
|
this.$container = $container;
|
|
|
|
/** @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;
|
|
|
|
// to keep consistency with backend API
|
|
this.dayjs = dayjs;
|
|
|
|
/** @property {CollapsibleWidget} */
|
|
this.CollapsibleWidget = CollapsibleWidget;
|
|
|
|
/**
|
|
* @property {NoteContextAwareWidget}
|
|
* @deprecated use NoteContextAwareWidget instead
|
|
*/
|
|
this.TabAwareWidget = NoteContextAwareWidget;
|
|
|
|
/** @property {NoteContextAwareWidget} */
|
|
this.NoteContextAwareWidget = NoteContextAwareWidget;
|
|
|
|
/**
|
|
* @property {NoteContextCachingWidget}
|
|
* @deprecated use NoteContextCachingWidget instead
|
|
*/
|
|
this.TabCachingWidget = NoteContextCachingWidget;
|
|
|
|
/** @property {NoteContextAwareWidget} */
|
|
this.NoteContextCachingWidget = NoteContextCachingWidget;
|
|
|
|
/** @property {BasicWidget} */
|
|
this.BasicWidget = BasicWidget;
|
|
|
|
/**
|
|
* Activates note in the tree and in the note detail.
|
|
*
|
|
* @method
|
|
* @param {string} notePath (or noteId)
|
|
* @returns {Promise<void>}
|
|
*/
|
|
this.activateNote = async notePath => {
|
|
await appContext.tabManager.getActiveContext().setNote(notePath);
|
|
};
|
|
|
|
/**
|
|
* Activates newly created note. Compared to this.activateNote() also makes sure that frontend has been fully synced.
|
|
*
|
|
* @param {string} notePath (or noteId)
|
|
* @return {Promise<void>}
|
|
*/
|
|
this.activateNewNote = async notePath => {
|
|
await ws.waitForMaxKnownEntityChangeId();
|
|
|
|
await appContext.tabManager.getActiveContext().setNote(notePath);
|
|
appContext.triggerEvent('focusAndSelectTitle');
|
|
};
|
|
|
|
/**
|
|
* Open a note in a new tab.
|
|
*
|
|
* @param {string} notePath (or noteId)
|
|
* @param {boolean} activate - set to true to activate the new tab, false to stay on the current tab
|
|
* @return {Promise<void>}
|
|
*/
|
|
this.openTabWithNote = async (notePath, activate) => {
|
|
await ws.waitForMaxKnownEntityChangeId();
|
|
|
|
await appContext.tabManager.openContextWithNote(notePath, activate);
|
|
|
|
if (activate) {
|
|
appContext.triggerEvent('focusAndSelectTitle');
|
|
}
|
|
};
|
|
|
|
/**
|
|
* Open a note in a new split.
|
|
*
|
|
* @param {string} notePath (or noteId)
|
|
* @param {boolean} activate - set to true to activate the new split, false to stay on the current split
|
|
* @return {Promise<void>}
|
|
*/
|
|
this.openSplitWithNote = async (notePath, activate) => {
|
|
await ws.waitForMaxKnownEntityChangeId();
|
|
|
|
const subContexts = appContext.tabManager.getActiveContext().getSubContexts();
|
|
const {ntxId} = subContexts[subContexts.length - 1];
|
|
|
|
appContext.triggerCommand("openNewNoteSplit", {ntxId, notePath});
|
|
|
|
if (activate) {
|
|
appContext.triggerEvent('focusAndSelectTitle');
|
|
}
|
|
};
|
|
|
|
/**
|
|
* @typedef {Object} ToolbarButtonOptions
|
|
* @property {string} title
|
|
* @property {string} [icon] - name of the boxicon to be used (e.g. "time" for "bx-time" icon)
|
|
* @property {function} action - callback handling the click on the button
|
|
* @property {string} [shortcut] - keyboard shortcut for the button, e.g. "alt+t"
|
|
*/
|
|
|
|
/**
|
|
* Adds new button the the plugin area.
|
|
*
|
|
* @param {ToolbarButtonOptions} opts
|
|
*/
|
|
this.addButtonToToolbar = opts => {
|
|
const buttonId = "toolbar-button-" + opts.title.replace(/\s/g, "-");
|
|
|
|
let button;
|
|
if (utils.isMobile()) {
|
|
$('#plugin-buttons-placeholder').remove();
|
|
button = $('<a class="dropdown-item" href="#">')
|
|
.on('click', () => {
|
|
setTimeout(() => $pluginButtons.dropdown('hide'), 0);
|
|
});
|
|
|
|
if (opts.icon) {
|
|
button.append($("<span>").addClass("bx bx-" + opts.icon))
|
|
.append("&nbsp;");
|
|
}
|
|
|
|
button.append($("<span>").text(opts.title));
|
|
} else {
|
|
button = $('<span class="button-widget icon-action bx" data-toggle="tooltip" title="" data-placement="right"></span>')
|
|
.addClass("bx bx-" + (opts.icon || "question-mark"));
|
|
|
|
button.attr("title", opts.title);
|
|
button.tooltip({html: true});
|
|
}
|
|
|
|
button = button.on('click', opts.action);
|
|
|
|
button.attr('id', buttonId);
|
|
|
|
if ($("#" + buttonId).replaceWith(button).length === 0) {
|
|
$pluginButtons.append(button);
|
|
}
|
|
|
|
if (opts.shortcut) {
|
|
utils.bindGlobalShortcut(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 backend.
|
|
* 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.runOnBackend = 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
|
|
}, "script");
|
|
|
|
if (ret.success) {
|
|
await ws.waitForMaxKnownEntityChangeId();
|
|
|
|
return ret.executionResult;
|
|
}
|
|
else {
|
|
throw new Error("server error: " + ret.error);
|
|
}
|
|
};
|
|
|
|
/**
|
|
* @deprecated new name of this API call is runOnBackend so use that
|
|
* @method
|
|
*/
|
|
this.runOnServer = this.runOnBackend;
|
|
|
|
/**
|
|
* This is a powerful search method - you can search by attributes and their values, e.g.:
|
|
* "#dateModified =* MONTH AND #log". See full documentation for all options at: https://github.com/zadam/trilium/wiki/Search
|
|
*
|
|
* @method
|
|
* @param {string} searchString
|
|
* @returns {Promise<NoteShort[]>}
|
|
*/
|
|
this.searchForNotes = async searchString => {
|
|
return await searchService.searchForNotes(searchString);
|
|
};
|
|
|
|
/**
|
|
* This is a powerful search method - you can search by attributes and their values, e.g.:
|
|
* "#dateModified =* MONTH AND #log". See full documentation for all options at: https://github.com/zadam/trilium/wiki/Search
|
|
*
|
|
* @method
|
|
* @param {string} searchString
|
|
* @returns {Promise<NoteShort|null>}
|
|
*/
|
|
this.searchForNote = async searchString => {
|
|
const notes = await this.searchForNotes(searchString);
|
|
|
|
return notes.length > 0 ? notes[0] : null;
|
|
};
|
|
|
|
/**
|
|
* Returns note by given noteId. If note is missing from cache, it's loaded.
|
|
**
|
|
* @param {string} noteId
|
|
* @return {Promise<NoteShort>}
|
|
*/
|
|
this.getNote = async noteId => await froca.getNote(noteId);
|
|
|
|
/**
|
|
* 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 {string[]} noteIds
|
|
* @param {boolean} [silentNotFoundError] - don't report error if the note is not found
|
|
* @return {Promise<NoteShort[]>}
|
|
*/
|
|
this.getNotes = async (noteIds, silentNotFoundError = false) => await froca.getNotes(noteIds, silentNotFoundError);
|
|
|
|
/**
|
|
* Update frontend tree (note) cache from the backend.
|
|
*
|
|
* @param {string[]} noteIds
|
|
* @method
|
|
*/
|
|
this.reloadNotes = async noteIds => await froca.reloadNotes(noteIds);
|
|
|
|
/**
|
|
* 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 = toastService.showMessage;
|
|
|
|
/**
|
|
* Show error message to the user.
|
|
*
|
|
* @method
|
|
* @param {string} message
|
|
*/
|
|
this.showError = toastService.showError;
|
|
|
|
/**
|
|
* Trigger command.
|
|
*
|
|
* @method
|
|
* @param {string} name
|
|
* @param {object} data
|
|
*/
|
|
this.triggerCommand = (name, data) => appContext.triggerCommand(name, data);
|
|
|
|
/**
|
|
* Trigger event.
|
|
*
|
|
* @method
|
|
* @param {string} name
|
|
* @param {object} data
|
|
*/
|
|
this.triggerEvent = (name, data) => appContext.triggerEvent(name, data);
|
|
|
|
/**
|
|
* @method
|
|
* @deprecated - this is now no-op since all the changes should be gracefully handled per widget
|
|
*/
|
|
this.refreshTree = () => {};
|
|
|
|
/**
|
|
* Create note link (jQuery object) for given note.
|
|
*
|
|
* @method
|
|
* @param {string} notePath (or noteId)
|
|
* @param {object} [params]
|
|
* @param {boolean} [params.showTooltip=true] - enable/disable tooltip on the link
|
|
* @param {boolean} [params.showNotePath=false] - show also whole note's path as part of the link
|
|
* @param {boolean} [params.showNoteIcon=false] - show also note icon before the title
|
|
* @param {string} [title=] - custom link tile with note's title as default
|
|
*/
|
|
this.createNoteLink = linkService.createNoteLink;
|
|
|
|
/**
|
|
* Adds given text to the editor cursor
|
|
*
|
|
* @deprecated use addTextToActiveContextEditor() instead
|
|
* @param {string} text - this must be clear text, HTML is not supported.
|
|
* @method
|
|
*/
|
|
this.addTextToActiveTabEditor = text => {
|
|
console.warn("api.addTextToActiveTabEditor() is deprecated, use addTextToActiveContextEditor() instead.");
|
|
|
|
return appContext.triggerCommand('addTextToActiveEditor', {text});
|
|
};
|
|
|
|
/**
|
|
* Adds given text to the editor cursor
|
|
*
|
|
* @param {string} text - this must be clear text, HTML is not supported.
|
|
* @method
|
|
*/
|
|
this.addTextToActiveContextEditor = text => appContext.triggerCommand('addTextToActiveEditor', {text});
|
|
|
|
/**
|
|
* @method
|
|
* @deprecated use getActiveContextNote() instead
|
|
* @returns {NoteShort} active note (loaded into right pane)
|
|
*/
|
|
this.getActiveTabNote = () => {
|
|
console.warn("api.getActiveTabNote() is deprecated, use getActiveContextNote() instead.");
|
|
|
|
return appContext.tabManager.getActiveContextNote();
|
|
};
|
|
|
|
/**
|
|
* @method
|
|
* @returns {NoteShort} active note (loaded into right pane)
|
|
*/
|
|
this.getActiveContextNote = () => appContext.tabManager.getActiveContextNote();
|
|
|
|
/**
|
|
* See https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editor-Editor.html for a documentation on the returned instance.
|
|
*
|
|
* @deprecated use getActiveContextTextEditor()
|
|
* @method
|
|
* @param [callback] - callback receiving "textEditor" instance
|
|
*/
|
|
this.getActiveTabTextEditor = callback => {
|
|
console.warn("api.getActiveTabTextEditor() is deprecated, use getActiveContextTextEditor() instead.");
|
|
|
|
return appContext.tabManager.getActiveContext()?.getTextEditor(callback);
|
|
};
|
|
|
|
/**
|
|
* See https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editor-Editor.html for a documentation on the returned instance.
|
|
*
|
|
* @method
|
|
* @returns {Promise<CKEditor>} instance of CKEditor
|
|
*/
|
|
this.getActiveContextTextEditor = () => appContext.tabManager.getActiveContext()?.getTextEditor();
|
|
|
|
/**
|
|
* See https://codemirror.net/doc/manual.html#api
|
|
*
|
|
* @method
|
|
* @returns {Promise<CodeMirror>} instance of CodeMirror
|
|
*/
|
|
this.getActiveContextCodeEditor = () => appContext.tabManager.getActiveContext()?.getCodeEditor();
|
|
|
|
/**
|
|
* Get access to the widget handling note detail. Methods like `getWidgetType()` and `getTypeWidget()` to get to the
|
|
* implementation of actual widget type.
|
|
*
|
|
* @method
|
|
* @returns {Promise<NoteDetailWidget>}
|
|
*/
|
|
this.getActiveNoteDetailWidget = () => new Promise(resolve => appContext.triggerCommand('executeInActiveNoteDetailWidget', {callback: resolve}));
|
|
|
|
/**
|
|
* @method
|
|
* @deprecated use getActiveContextNotePath() instead
|
|
* @returns {Promise<string|null>} returns note path of active note or null if there isn't active note
|
|
*/
|
|
this.getActiveTabNotePath = () => {
|
|
console.warn("api.getActiveTabNotePath() is deprecated, use getActiveContextNotePath() instead.");
|
|
|
|
return appContext.tabManager.getActiveContextNotePath();
|
|
};
|
|
|
|
/**
|
|
* @method
|
|
* @returns {Promise<string|null>} returns note path of active note or null if there isn't active note
|
|
*/
|
|
this.getActiveContextNotePath = () => appContext.tabManager.getActiveContextNotePath();
|
|
|
|
/**
|
|
* Returns component which owns given DOM element (the nearest parent component in DOM tree)
|
|
*
|
|
* @method
|
|
* @param {Element} el - DOM element
|
|
* @returns {Component}
|
|
*/
|
|
this.getComponentByEl = el => appContext.getComponentByEl(el);
|
|
|
|
/**
|
|
* @method
|
|
* @param {object} $el - jquery object on which to setup the tooltip
|
|
*/
|
|
this.setupElementTooltip = noteTooltipService.setupElementTooltip;
|
|
|
|
/**
|
|
* @deprecated use protectNote and protectSubtree instead
|
|
* @method
|
|
*/
|
|
this.protectActiveNote = async () => {
|
|
const activeNote = appContext.tabManager.getActiveContextNote();
|
|
|
|
await protectedSessionService.protectNote(activeNote.noteId, true, false);
|
|
};
|
|
|
|
/**
|
|
* @method
|
|
* @param {string} noteId
|
|
* @param {boolean} protect - true to protect note, false to unprotect
|
|
*/
|
|
this.protectNote = async (noteId, protect) => {
|
|
await protectedSessionService.protectNote(noteId, protect, false);
|
|
};
|
|
|
|
/**
|
|
* @method
|
|
* @param {string} noteId
|
|
* @param {boolean} protect - true to protect subtree, false to unprotect
|
|
*/
|
|
this.protectSubTree = async (noteId, protect) => {
|
|
await protectedSessionService.protectNote(noteId, protect, true);
|
|
};
|
|
|
|
/**
|
|
* Returns date-note for today. If it doesn't exist, it is automatically created.
|
|
*
|
|
* @method
|
|
* @return {Promise<NoteShort>}
|
|
*/
|
|
this.getTodayNote = dateNotesService.getTodayNote;
|
|
|
|
/**
|
|
* Returns day note for a given date. If it doesn't exist, it is automatically created.
|
|
*
|
|
* @method
|
|
* @param {string} date - e.g. "2019-04-29"
|
|
* @return {Promise<NoteShort>}
|
|
* @deprecated use getDayNote instead
|
|
*/
|
|
this.getDateNote = dateNotesService.getDayNote;
|
|
|
|
/**
|
|
* Returns day note for a given date. If it doesn't exist, it is automatically created.
|
|
*
|
|
* @method
|
|
* @param {string} date - e.g. "2019-04-29"
|
|
* @return {Promise<NoteShort>}
|
|
*/
|
|
this.getDayNote = dateNotesService.getDayNote;
|
|
|
|
/**
|
|
* Returns day note for the first date of the week of the given date. If it doesn't exist, it is automatically created.
|
|
*
|
|
* @method
|
|
* @param {string} date - e.g. "2019-04-29"
|
|
* @return {Promise<NoteShort>}
|
|
*/
|
|
this.getWeekNote = dateNotesService.getWeekNote;
|
|
|
|
/**
|
|
* Returns month-note. If it doesn't exist, it is automatically created.
|
|
*
|
|
* @method
|
|
* @param {string} month - e.g. "2019-04"
|
|
* @return {Promise<NoteShort>}
|
|
*/
|
|
this.getMonthNote = dateNotesService.getMonthNote;
|
|
|
|
/**
|
|
* Returns year-note. If it doesn't exist, it is automatically created.
|
|
*
|
|
* @method
|
|
* @param {string} year - e.g. "2019"
|
|
* @return {Promise<NoteShort>}
|
|
*/
|
|
this.getYearNote = dateNotesService.getYearNote;
|
|
|
|
/**
|
|
* Hoist note in the current tab. See https://github.com/zadam/trilium/wiki/Note-hoisting
|
|
*
|
|
* @method
|
|
* @param {string} noteId - set hoisted note. 'root' will effectively unhoist
|
|
* @return {Promise}
|
|
*/
|
|
this.setHoistedNoteId = (noteId) => {
|
|
const activeNoteContext = appContext.tabManager.getActiveContext();
|
|
|
|
if (activeNoteContext) {
|
|
activeNoteContext.setHoistedNoteId(noteId);
|
|
}
|
|
};
|
|
|
|
/**
|
|
* @method
|
|
* @param {string} keyboardShortcut - e.g. "ctrl+shift+a"
|
|
* @param {function} handler
|
|
*/
|
|
this.bindGlobalShortcut = utils.bindGlobalShortcut;
|
|
|
|
/**
|
|
* Trilium runs in backend and frontend process, when something is changed on the backend from script,
|
|
* frontend will get asynchronously synchronized.
|
|
*
|
|
* This method returns a promise which resolves once all the backend -> frontend synchronization is finished.
|
|
* Typical use case is when new note has been created, we should wait until it is synced into frontend and only then activate it.
|
|
*
|
|
* @method
|
|
*/
|
|
this.waitUntilSynced = ws.waitForMaxKnownEntityChangeId;
|
|
|
|
/**
|
|
* This will refresh all currently opened notes which have included note specified in the parameter
|
|
*
|
|
* @param includedNoteId - noteId of the included note
|
|
*/
|
|
this.refreshIncludedNote = includedNoteId => appContext.triggerEvent('refreshIncludedNote', {noteId: includedNoteId});
|
|
|
|
/**
|
|
* Return randomly generated string of given length. This random string generation is NOT cryptographically secure.
|
|
*
|
|
* @method
|
|
* @param {number} length of the string
|
|
* @returns {string} random string
|
|
*/
|
|
this.randomString = utils.randomString;
|
|
}
|
|
|
|
export default FrontendScriptApi;
|
|
</code></pre>
|
|
</article>
|
|
</section>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
<nav>
|
|
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Attribute.html">Attribute</a></li><li><a href="Branch.html">Branch</a></li><li><a href="FrontendScriptApi.html">FrontendScriptApi</a></li><li><a href="module.exports.html">exports</a></li><li><a href="NoteComplement.html">NoteComplement</a></li><li><a href="NoteShort.html">NoteShort</a></li></ul><h3>Global</h3><ul><li><a href="global.html#doRenderBody">doRenderBody</a></li></ul>
|
|
</nav>
|
|
|
|
<br class="clear">
|
|
|
|
<footer>
|
|
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.10</a>
|
|
</footer>
|
|
|
|
<script> prettyPrint(); </script>
|
|
<script src="scripts/linenumber.js"> </script>
|
|
</body>
|
|
</html>
|