trilium/docs/backend_api/services_backend_script_api.js.html

454 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/backend_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/backend_script_api.js</h1>
<section>
<article>
<pre class="prettyprint source linenums"><code>const log = require('./log');
const noteService = require('./notes');
const sql = require('./sql');
const utils = require('./utils');
const attributeService = require('./attributes');
const dateNoteService = require('./date_notes');
const treeService = require('./tree');
const config = require('./config');
const repository = require('./repository');
const axios = require('axios');
const dayjs = require('dayjs');
2018-08-30 02:44:35 +08:00
const cloningService = require('./cloning');
2019-08-28 03:24:31 +08:00
const ws = require('./ws.js');
2019-02-21 05:24:51 +08:00
const appInfo = require('./app_info');
const searchService = require('./search');
2018-08-30 02:44:35 +08:00
/**
* This is the main backend API interface for scripts. It's published in the local "api" object.
*
* @constructor
* @hideconstructor
*/
2019-02-21 05:24:51 +08:00
function BackendScriptApi(currentNote, apiParams) {
2018-08-30 02:44:35 +08:00
/** @property {Note} note where script started executing */
2019-02-21 05:24:51 +08:00
this.startNote = apiParams.startNote;
/** @property {Note} note where script is currently executing. Don't mix this up with concept of active note */
2018-08-30 02:44:35 +08:00
this.currentNote = currentNote;
/** @property {Entity} entity whose event triggered this executions */
2019-02-21 05:24:51 +08:00
this.originEntity = apiParams.originEntity;
for (const key in apiParams) {
this[key] = apiParams[key];
}
2018-08-30 02:44:35 +08:00
this.axios = axios;
this.dayjs = dayjs;
2018-08-30 02:44:35 +08:00
this.utils = {
unescapeHtml: utils.unescapeHtml
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.
*
* @returns {string|null}
*/
this.getInstanceName = () => config.General ? config.General.instanceName : null;
/**
* @method
* @param {string} noteId
* @returns {Promise&lt;Note|null>}
*/
this.getNote = repository.getNote;
/**
* @method
* @param {string} branchId
* @returns {Promise&lt;Branch|null>}
*/
this.getBranch = repository.getBranch;
/**
* @method
* @param {string} attributeId
* @returns {Promise&lt;Attribute|null>}
*/
this.getAttribute = repository.getAttribute;
/**
* @method
* @param {string} imageId
* @returns {Promise&lt;Image|null>}
*/
this.getImage = repository.getImage;
/**
* Retrieves first entity from the SQL's result set.
*
* @method
* @param {string} SQL query
* @param {Array.&lt;?>} array of params
* @returns {Promise&lt;Entity|null>}
*/
this.getEntity = repository.getEntity;
/**
* @method
* @param {string} SQL query
* @param {Array.&lt;?>} array of params
* @returns {Promise&lt;Entity[]>}
*/
this.getEntities = repository.getEntities;
/**
* 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
2019-04-23 00:08:33 +08:00
* @returns {Promise&lt;Note[]>}
*/
this.searchForNotes = searchService.searchForNotes;
2019-04-23 00:08:33 +08:00
/**
* 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;Note|null>}
*/
this.searchForNote = async searchString => {
const notes = await searchService.searchForNotes(searchString);
return notes.length > 0 ? notes[0] : null;
};
2018-08-30 02:44:35 +08:00
/**
* Retrieves notes with given label name &amp; value
*
* @method
* @param {string} name - attribute name
* @param {string} [value] - attribute value
* @returns {Promise&lt;Note[]>}
*/
this.getNotesWithLabel = attributeService.getNotesWithLabel;
/**
* Retrieves first note with given label name &amp; value
*
* @method
* @param {string} name - attribute name
* @param {string} [value] - attribute value
* @returns {Promise&lt;Note|null>}
*/
this.getNoteWithLabel = attributeService.getNoteWithLabel;
/**
* If there's no branch between note and parent note, create one. Otherwise do nothing.
*
* @method
* @param {string} noteId
* @param {string} parentNoteId
* @param {string} prefix - if branch will be create between note and parent note, set this prefix
* @returns {Promise&lt;void>}
*/
this.ensureNoteIsPresentInParent = cloningService.ensureNoteIsPresentInParent;
/**
* If there's a branch between note and parent note, remove it. Otherwise do nothing.
*
* @method
* @param {string} noteId
* @param {string} parentNoteId
* @returns {Promise&lt;void>}
*/
this.ensureNoteIsAbsentFromParent = cloningService.ensureNoteIsAbsentFromParent;
/**
* Based on the value, either create or remove branch between note and parent note.
*
* @method
* @param {boolean} present - true if we want the branch to exist, false if we want it gone
* @param {string} noteId
* @param {string} parentNoteId
* @param {string} prefix - if branch will be create between note and parent note, set this prefix
* @returns {Promise&lt;void>}
*/
this.toggleNoteInParent = cloningService.toggleNoteInParent;
/**
* @typedef {object} CreateNoteAttribute
* @property {string} type - attribute type - label, relation etc.
* @property {string} name - attribute name
* @property {string} [value] - attribute value
*/
2019-11-26 05:45:09 +08:00
/**
* Create text note. See also createNewNote() for more options.
2019-11-26 05:45:09 +08:00
*
* @param {string} parentNoteId
* @param {string} title
* @param {string} content
* @return {Promise&lt;{note: Note, branch: Branch}>}
*/
this.createTextNote = async (parentNoteId, title, content = '') => await noteService.createNewNote({
parentNoteId,
title,
content,
type: 'text'
});
/**
* Create data note - data in this context means object serializable to JSON. Created note will be of type 'code' and
* JSON MIME type. See also createNewNote() for more options.
2019-11-26 05:45:09 +08:00
*
* @param {string} parentNoteId
* @param {string} title
* @param {object} content
* @return {Promise&lt;{note: Note, branch: Branch}>}
*/
this.createDataNote = async (parentNoteId, title, content = {}) => await noteService.createNewNote({
parentNoteId,
title,
content: JSON.stringify(content, null, '\t'),
2019-11-26 05:45:09 +08:00
type: 'code',
mime: 'application/json'
});
2018-08-30 02:44:35 +08:00
/**
* @typedef {object} CreateNewNoteParams
2019-11-26 05:45:09 +08:00
* @property {string} parentNoteId - MANDATORY
* @property {string} title - MANDATORY
* @property {string|buffer} content - MANDATORY
* @property {string} type - text, code, file, image, search, book, relation-map - MANDATORY
* @property {string} mime - value is derived from default mimes for type
* @property {boolean} isProtected - default is false
* @property {boolean} isExpanded - default is false
* @property {string} prefix - default is empty string
* @property {int} notePosition - default is last existing notePosition in a parent + 10
2018-08-30 02:44:35 +08:00
*/
/**
* @method
*
* @param {CreateNewNoteParams} [params]
2018-08-30 02:44:35 +08:00
* @returns {Promise&lt;{note: Note, branch: Branch}>} object contains newly created entities note and branch
*/
this.createNewNote = noteService.createNewNote;
2019-02-21 05:24:51 +08:00
2019-12-04 05:53:17 +08:00
/**
* @typedef {object} CreateNoteAttribute
* @property {string} type - attribute type - label, relation etc.
* @property {string} name - attribute name
* @property {string} [value] - attribute value
*/
/**
* @typedef {object} CreateNoteExtraOptions
* @property {boolean} [json=false] - should the note be JSON
* @property {boolean} [isProtected=false] - should the note be protected
* @property {string} [type='text'] - note type
* @property {string} [mime='text/html'] - MIME type of the note
* @property {CreateNoteAttribute[]} [attributes=[]] - attributes to be created for this note
*/
/**
* @method
*
* @param {string} parentNoteId - create new note under this parent
* @param {string} title
* @param {string} [content=""]
* @param {CreateNoteExtraOptions} [extraOptions={}]
* @returns {Promise&lt;{note: Note, branch: Branch}>} object contains newly created entities note and branch
*/
this.createNote = async (parentNoteId, title, content = "", extraOptions= {}) => {
extraOptions.parentNoteId = parentNoteId;
extraOptions.title = title;
const parentNote = await repository.getNote(parentNoteId);
// code note type can be inherited, otherwise text is default
extraOptions.type = parentNote.type === 'code' ? 'code' : 'text';
extraOptions.mime = parentNote.type === 'code' ? parentNote.mime : 'text/html';
if (extraOptions.json) {
extraOptions.content = JSON.stringify(content || {}, null, '\t');
extraOptions.type = 'code';
extraOptions.mime = 'application/json';
}
else {
extraOptions.content = content;
}
const {note, branch} = await noteService.createNewNote(extraOptions);
for (const attr of extraOptions.attributes || []) {
await attributeService.createAttribute({
noteId: note.noteId,
type: attr.type,
name: attr.name,
value: attr.value,
isInheritable: !!attr.isInheritable
});
}
return {note, branch};
};
2018-08-30 02:44:35 +08:00
/**
* Log given message to trilium logs.
*
* @param message
*/
this.log = message => log.info(`Script "${currentNote.title}" (${currentNote.noteId}): ${message}`);
/**
* Returns root note of the calendar.
*
* @method
* @returns {Promise&lt;Note|null>}
*/
this.getRootCalendarNote = dateNoteService.getRootCalendarNote;
/**
2019-02-21 05:24:51 +08:00
* Returns day note for given date. If such note doesn't exist, it is created.
2018-08-30 02:44:35 +08:00
*
* @method
2019-02-21 05:24:51 +08:00
* @param {string} date in YYYY-MM-DD format
2018-08-30 02:44:35 +08:00
* @returns {Promise&lt;Note|null>}
*/
this.getDateNote = dateNoteService.getDateNote;
2019-11-28 06:07:10 +08:00
/**
* Returns today's day note. If such note doesn't exist, it is created.
*
* @method
* @returns {Promise&lt;Note|null>}
*/
this.getTodayNote = dateNoteService.getTodayNote;
2019-02-21 05:24:51 +08:00
/**
* Returns note for the first date of the week of the given date.
*
* @method
* @param {string} date in YYYY-MM-DD format
* @param {object} options - "startOfTheWeek" - either "monday" (default) or "sunday"
* @returns {Promise&lt;Note|null>}
*/
this.getWeekNote = dateNoteService.getWeekNote;
/**
* Returns month note for given date. If such note doesn't exist, it is created.
*
* @method
* @param {string} date in YYYY-MM format
* @returns {Promise&lt;Note|null>}
*/
this.getMonthNote = dateNoteService.getMonthNote;
/**
* Returns year note for given year. If such note doesn't exist, it is created.
*
* @method
* @param {string} year in YYYY format
* @returns {Promise&lt;Note|null>}
*/
this.getYearNote = dateNoteService.getYearNote;
2018-08-30 02:44:35 +08:00
/**
* @method
* @param {string} parentNoteId - this note's child notes will be sorted
* @returns Promise&lt;void>
*/
this.sortNotesAlphabetically = treeService.sortNotesAlphabetically;
/**
* This method finds note by its noteId and prefix and either sets it to the given parentNoteId
* or removes the branch (if parentNoteId is not given).
*
* This method looks similar to toggleNoteInParent() but differs because we're looking up branch by prefix.
*
* @method
* @deprecated - this method is pretty confusing and serves specialized purpose only
2018-08-30 02:44:35 +08:00
* @param {string} noteId
* @param {string} prefix
* @param {string|null} parentNoteId
2018-08-30 02:44:35 +08:00
*/
this.setNoteToParent = treeService.setNoteToParent;
/**
* This functions wraps code which is supposed to be running in transaction. If transaction already
* exists, then we'll use that transaction.
*
* This method is required only when script has label manualTransactionHandling, all other scripts are
* transactional by default.
*
* @method
* @param {function} func
* @returns {Promise&lt;?>} result of func callback
*/
this.transactional = sql.transactional;
2018-12-23 05:28:49 +08:00
this.sql = sql;
2018-08-30 02:44:35 +08:00
/**
* Trigger tree refresh in all connected clients. This is required when some tree change happens in
* the backend.
*
* @returns {Promise&lt;void>}
*/
2019-08-28 03:24:31 +08:00
this.refreshTree = ws.refreshTree;
2019-02-21 05:24:51 +08:00
/**
* @return {{syncVersion, appVersion, buildRevision, dbVersion, dataDirectory, buildDate}|*} - object representing basic info about running Trilium version
*/
this.getAppInfo = () => appInfo
2018-08-30 02:44:35 +08:00
}
module.exports = BackendScriptApi;
</code></pre>
2018-08-30 02:44:35 +08:00
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="ApiToken.html">ApiToken</a></li><li><a href="Attribute.html">Attribute</a></li><li><a href="BackendScriptApi.html">BackendScriptApi</a></li><li><a href="Branch.html">Branch</a></li><li><a href="Entity.html">Entity</a></li><li><a href="Note.html">Note</a></li><li><a href="NoteRevision.html">NoteRevision</a></li><li><a href="Option.html">Option</a></li><li><a href="RecentNote.html">RecentNote</a></li></ul><h3><a href="global.html">Global</a></h3>
2018-08-30 02:44:35 +08:00
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a>
2018-08-30 02:44:35 +08:00
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>