trilium/docs/frontend_api/services_frontend_script_api.js.html

459 lines
14 KiB
HTML
Raw Normal View History

2018-08-30 02:44:35 +08:00
<!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 treeService from './tree.js';
import server from './server.js';
import utils from './utils.js';
2019-10-20 16:00:18 +08:00
import toastService from './toast.js';
2018-08-30 02:44:35 +08:00
import linkService from './link.js';
import treeCache from './tree_cache.js';
2018-12-23 05:28:49 +08:00
import noteTooltipService from './note_tooltip.js';
import protectedSessionService from './protected_session.js';
import dateNotesService from './date_notes.js';
2020-03-08 18:41:42 +08:00
import CollapsibleWidget from '../widgets/collapsible_widget.js';
import ws from "./ws.js";
import hoistedNoteService from "./hoisted_note.js";
2020-02-02 18:44:08 +08:00
import appContext from "./app_context.js";
2020-04-08 01:19:20 +08:00
import TabAwareWidget from "../widgets/tab_aware_widget.js";
import TabCachingWidget from "../widgets/tab_caching_widget.js";
import BasicWidget from "../widgets/basic_widget.js";
2018-08-30 02:44:35 +08:00
/**
* This is the main frontend API interface for scripts. It's published in the local "api" object.
*
* @constructor
* @hideconstructor
*/
2020-03-08 18:41:42 +08:00
function FrontendScriptApi(startNote, currentNote, originEntity = null, $container = null) {
2018-08-30 02:44:35 +08:00
const $pluginButtons = $("#plugin-buttons");
/** @property {jQuery} container of all the rendered script content */
this.$container = $container;
2018-08-30 02:44:35 +08:00
/** @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;
2020-03-08 18:41:42 +08:00
/** @property {CollapsibleWidget} */
this.CollapsibleWidget = CollapsibleWidget;
2020-04-08 01:19:20 +08:00
/** @property {TabAwareWidget} */
this.TabAwareWidget = TabAwareWidget;
/** @property {TabCachingWidget} */
this.TabCachingWidget = TabCachingWidget;
/** @property {BasicWidget} */
this.BasicWidget = BasicWidget;
2018-08-30 02:44:35 +08:00
/**
* Activates note in the tree and in the note detail.
*
* @method
* @param {string} notePath (or noteId)
* @returns {Promise&lt;void>}
*/
2020-03-08 18:41:42 +08:00
this.activateNote = async notePath => {
await appContext.tabManager.getActiveTabContext().setNote(notePath);
};
2018-08-30 02:44:35 +08:00
/**
* Activates newly created note. Compared to this.activateNote() also makes sure that frontend has been fully synced.
2018-08-30 02:44:35 +08:00
*
* @param {string} notePath (or noteId)
* @return {Promise&lt;void>}
*/
this.activateNewNote = async notePath => {
await ws.waitForMaxKnownSyncId();
2018-08-30 02:44:35 +08:00
2020-03-08 18:41:42 +08:00
await appContext.tabManager.getActiveTabContext().setNote(notePath);
appContext.triggerEvent('focusAndSelectTitle');
2018-08-30 02:44:35 +08:00
};
/**
* @typedef {Object} ToolbarButtonOptions
* @property {string} title
2019-11-09 05:34:30 +08:00
* @property {string} [icon] - name of the boxicon to be used (e.g. "time" for "bx-time" icon)
2018-08-30 02:44:35 +08:00
* @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(/[^a-zA-Z0-9]/g, "-");
const button = $('&lt;button>')
.addClass("btn btn-sm")
2019-11-19 06:01:31 +08:00
.on('click', opts.action);
if (opts.icon) {
2019-11-09 05:34:30 +08:00
button.append($("&lt;span>").addClass("bx bx-" + opts.icon))
.append("&amp;nbsp;");
}
button.append($("&lt;span>").text(opts.title));
2018-08-30 02:44:35 +08:00
button.attr('id', buttonId);
if ($("#" + buttonId).replaceWith(button).length === 0) {
$pluginButtons.append(button);
}
if (opts.shortcut) {
utils.bindGlobalShortcut(opts.shortcut, opts.action);
2018-08-30 02:44:35 +08:00
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;
}
});
}
/**
2020-01-02 05:03:27 +08:00
* Executes given anonymous function on the backend.
2018-08-30 02:44:35 +08:00
* 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.&lt;?>} params - list of parameters to the anonymous function to be send to backend
* @return {Promise&lt;*>} return value of the executed function on the backend
*/
2020-01-02 05:03:27 +08:00
this.runOnBackend = async (script, params = []) => {
2018-08-30 02:44:35 +08:00
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
2020-02-02 18:44:08 +08:00
}, "script");
2018-08-30 02:44:35 +08:00
if (ret.success) {
// wait until all the changes done in the script has been synced to frontend before continuing
await ws.waitForSyncId(ret.maxSyncId);
2018-08-30 02:44:35 +08:00
return ret.executionResult;
}
else {
throw new Error("server error: " + ret.error);
}
};
2020-01-02 05:03:27 +08:00
/**
* @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&lt;NoteShort[]>}
*/
this.searchForNotes = async searchString => {
const noteIds = await this.runOnServer(async searchString => {
const notes = await api.searchForNotes(searchString);
return notes.map(note => note.noteId);
}, [searchString]);
return await treeCache.getNotes(noteIds);
};
/**
* 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&lt;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&lt;NoteShort>}
*/
this.getNote = async noteId => await treeCache.getNote(noteId);
2018-08-30 02:44:35 +08:00
/**
* 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&lt;NoteShort[]>}
*/
this.getNotes = async (noteIds, silentNotFoundError = false) => await treeCache.getNotes(noteIds, silentNotFoundError);
/**
* Update frontend tree (note) cache from the backend.
*
2019-10-26 16:00:26 +08:00
* @param {string[]} noteIds
* @method
*/
2019-10-26 16:00:26 +08:00
this.reloadNotes = async noteIds => await treeCache.reloadNotes(noteIds);
2018-08-30 02:44:35 +08:00
/**
* 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
*/
2019-10-20 16:00:18 +08:00
this.showMessage = toastService.showMessage;
2018-08-30 02:44:35 +08:00
/**
* Show error message to the user.
*
* @method
* @param {string} message
*/
2019-10-20 16:00:18 +08:00
this.showError = toastService.showError;
2018-08-30 02:44:35 +08:00
/**
* @method
2020-04-08 01:19:20 +08:00
* @deprecated - this is now no-op since all the changes should be gracefully handled per widget
2018-08-30 02:44:35 +08:00
*/
2020-04-08 01:19:20 +08:00
this.refreshTree = () => {};
2018-08-30 02:44:35 +08:00
/**
* 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;
/**
* Adds given text to the editor cursor
*
2020-02-02 18:44:08 +08:00
* @param {string} text - this must be clear text, HTML is not supported.
* @method
*/
2020-03-08 18:41:42 +08:00
this.addTextToActiveTabEditor = text => appContext.triggerCommand('addTextToActiveEditor', {text});
2019-03-13 04:42:27 +08:00
/**
* @method
2020-02-02 18:44:08 +08:00
* @returns {NoteShort} active note (loaded into right pane)
2019-03-13 04:42:27 +08:00
*/
this.getActiveTabNote = () => appContext.tabManager.getActiveTabNote();
2019-03-13 04:42:27 +08:00
/**
* See https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editor-Editor.html for a documentation on the returned instance.
*
* @method
2020-02-02 18:44:08 +08:00
* @param callback - method receiving "textEditor" instance
*/
2020-03-08 18:41:42 +08:00
this.getActiveTabTextEditor = callback => appContext.triggerCommand('executeInActiveEditor', {callback});
/**
* @method
* @returns {Promise&lt;string|null>} returns note path of active note or null if there isn't active note
*/
this.getActiveTabNotePath = () => appContext.tabManager.getActiveTabNotePath();
2019-02-21 05:24:51 +08:00
/**
* @method
2020-03-08 18:41:42 +08:00
* @param {object} $el - jquery object on which to setup the tooltip
*/
this.setupElementTooltip = noteTooltipService.setupElementTooltip;
/**
* @deprecated use protectNote and protectSubtree instead
* @method
2019-02-21 05:24:51 +08:00
*/
2020-03-08 18:41:42 +08:00
this.protectActiveNote = async () => {
const activeNote = appContext.tabManager.getActiveTabNote();
await protectedSessionService.protectNote(activeNote.noteId, true, false);
2019-02-21 05:24:51 +08:00
};
2018-12-23 05:28:49 +08:00
/**
* @method
2020-03-08 18:41:42 +08:00
* @param {string} noteId
* @param {boolean} protect - true to protect note, false to unprotect
2018-12-23 05:28:49 +08:00
*/
2020-03-08 18:41:42 +08:00
this.protectNote = async (noteId, protect) => {
await protectedSessionService.protectNote(noteId, protect, false);
};
2019-02-21 05:24:51 +08:00
/**
* @method
2020-03-08 18:41:42 +08:00
* @param {string} noteId
* @param {boolean} protect - true to protect subtree, false to unprotect
2019-02-21 05:24:51 +08:00
*/
2020-03-08 18:41:42 +08:00
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&lt;NoteShort>}
*/
this.getTodayNote = dateNotesService.getTodayNote;
/**
* Returns date-note. If it doesn't exist, it is automatically created.
*
* @method
* @param {string} date - e.g. "2019-04-29"
* @return {Promise&lt;NoteShort>}
*/
this.getDateNote = dateNotesService.getDateNote;
/**
* Returns month-note. If it doesn't exist, it is automatically created.
*
* @method
* @param {string} month - e.g. "2019-04"
* @return {Promise&lt;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&lt;NoteShort>}
*/
this.getYearNote = dateNotesService.getYearNote;
/**
* Hoist note. See https://github.com/zadam/trilium/wiki/Note-hoisting
*
* @method
* @param {string} noteId - set hoisted note. 'root' will effectively unhoist
* @return {Promise}
*/
this.setHoistedNoteId = hoistedNoteService.setHoistedNoteId;
/**
* @method
* @param {string} keyboardShortcut - e.g. "ctrl+shift+a"
* @param {function} handler
*/
this.bindGlobalShortcut = utils.bindGlobalShortcut;
/**
2020-01-02 05:03:27 +08:00
* 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.waitForMaxKnownSyncId;
2018-08-30 02:44:35 +08:00
}
export default FrontendScriptApi;</code></pre>
</article>
</section>
</div>
<nav>
2020-02-02 18:44:08 +08:00
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Branch.html">Branch</a></li><li><a href="FrontendScriptApi.html">FrontendScriptApi</a></li><li><a href="NoteComplement.html">NoteComplement</a></li><li><a href="NoteShort.html">NoteShort</a></li></ul><h3><a href="global.html">Global</a></h3>
2018-08-30 02:44:35 +08:00
</nav>
<br class="clear">
<footer>
2020-04-08 01:19:20 +08:00
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.4</a>
2018-08-30 02:44:35 +08:00
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>