JSDoc: Class: BackendScriptApi

new BackendScriptApi()

This is the main backend API interface for scripts. All the properties and methods are published in the "api" object available in the JS backend notes. You can use e.g. api.log(api.startNote.title);

Source:

services/backend_script_api.js, line 29

Members

__private

This object contains "at your risk" and "no BC guarantees" objects for advanced use cases.

Properties:

Name	Type	Description
`becca`	Becca	provides access to the backend in-memory object graph, see https://github.com/zadam/trilium/blob/master/src/becca/becca.js

Source:

services/backend_script_api.js, line 537

axios

Properties:

Name	Type	Description
`Axios`	axios	library for HTTP requests. See https://axios-http.com for documentation

Deprecated:

use native (browser compatible) fetch() instead

Source:

services/backend_script_api.js, line 45

currentNote

Properties:

Name	Type	Description
`note`	BNote	where script is currently executing. Don't mix this up with concept of active note

Source:

services/backend_script_api.js, line 33

dayjs

Properties:

Name	Type	Description
`day.js`	dayjs	library for date manipulation. See https://day.js.org for documentation

Source:

services/backend_script_api.js, line 47

originEntity

Properties:

Name	Type	Description
`entity`	AbstractBeccaEntity	whose event triggered this executions

Source:

services/backend_script_api.js, line 35

sql

Properties:

Name	Type	Description
`sql`	module:sql

Source:

services/backend_script_api.js, line 437

startNote

Properties:

Name	Type	Description
`note`	BNote	where script started executing

Source:

services/backend_script_api.js, line 31

xml2js

Properties:

Name	Type	Description
`xml2js`	axios	library for XML parsing. See https://github.com/Leonidas-from-XIV/node-xml2js for documentation

Source:

services/backend_script_api.js, line 49

Methods

createDataNote(parentNoteId, title, content) → {Object}

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.

Parameters:

Name	Type	Description
`parentNoteId`	string
`title`	string
`content`	object

Source:

services/backend_script_api.js, line 198

Returns:

object having "note" and "branch" keys representing respective objects

Type: Object

createNewNote() → {Object}

Properties:

Name Type Description

params

object

Properties

Name	Type	Attributes	Default	Description
`parentNoteId`	string
`title`	string
`content`	string \| buffer
`type`	string			text, code, file, image, search, book, relationMap, canvas
`mime`	string	<optional>		value is derived from default mimes for type
`isProtected`	boolean	<optional>	false
`isExpanded`	boolean	<optional>	false
`prefix`	string	<optional>	''
`notePosition`	int	<optional>		default is last existing notePosition in a parent + 10

Source:

services/backend_script_api.js, line 221

Returns:

object contains newly created entities note and branch

Type: Object

createNote(parentNoteId, title, contentopt, extraOptionsopt) → {Object}

Parameters:

Name	Type	Attributes	Default	Description
`parentNoteId`	string			create new note under this parent
`title`	string
`content`	string	<optional>	""
`extraOptions`	object	<optional>	{}

Properties:

Name Type Attributes Default Description

extraOptions.json boolean <optional> false should the note be JSON

extraOptions.isProtected boolean <optional> false should the note be protected

extraOptions.type string <optional> 'text' note type

extraOptions.mime string <optional> 'text/html' MIME type of the note

extraOptions.attributes

Array.<object>

[]

attributes to be created for this note

Properties

Name	Type	Attributes	Description
`type`	string		attribute type - label, relation etc.
`name`	string		attribute name
`value`	string	<optional>	attribute value

Deprecated:

please use createTextNote() with similar API for simpler use cases or createNewNote() for more complex needs

Source:

services/backend_script_api.js, line 241

Returns:

object contains newly created entities note and branch

Type: Object

createOrUpdateLauncher(opts) → {Object}

Creates a new launcher to the launchbar. If the launcher (id) already exists, it will be updated.

Parameters:

Name	Type	Description
`opts`	object

Properties:

Name	Type	Attributes	Default	Description
`opts.id`	string			id of the launcher, only alphanumeric at least 6 characters long
`opts.type`	string			one of * "note" - activating the launcher will navigate to the target note (specified in targetNoteId param) * "script" - activating the launcher will execute the script (specified in scriptNoteId param) * "customWidget" - the launcher will be rendered with a custom widget (specified in widgetNoteId param)
`opts.title`	string
`opts.isVisible`	boolean	<optional>	false	if true, will be created in the "Visible launchers", otherwise in "Available launchers"
`opts.icon`	string	<optional>		name of the boxicon to be used (e.g. "bx-time")
`opts.keyboardShortcut`	string	<optional>		will activate the target note/script upon pressing, e.g. "ctrl+e"
`opts.targetNoteId`	string	<optional>		for type "note"
`opts.scriptNoteId`	string	<optional>		for type "script"
`opts.widgetNoteId`	string	<optional>		for type "customWidget"

Source:

services/backend_script_api.js, line 464

Returns:

Type: Object

createTextNote(parentNoteId, title, content) → {Object}

Create text note. See also createNewNote() for more options.

Parameters:

Name	Type	Description
`parentNoteId`	string
`title`	string
`content`	string

Source:

services/backend_script_api.js, line 181

Returns:

- object having "note" and "branch" keys representing respective objects

Type: Object

ensureNoteIsAbsentFromParent(noteId, parentNoteId) → {void}

If there's a branch between note and parent note, remove it. Otherwise, do nothing.

Parameters:

Name	Type	Description
`noteId`	string
`parentNoteId`	string

Source:

services/backend_script_api.js, line 158

Returns:

Type: void

ensureNoteIsPresentInParent(noteId, parentNoteId, prefix) → {void}

If there's no branch between note and parent note, create one. Otherwise, do nothing.

Parameters:

Name	Type	Description
`noteId`	string
`parentNoteId`	string
`prefix`	string	if branch will be created between note and parent note, set this prefix

Source:

services/backend_script_api.js, line 148

Returns:

Type: void

escapeHtml(string) → {string}

Parameters:

Name	Type	Description
`string`	string	to escape

Source:

services/backend_script_api.js, line 425

Returns:

escaped string

Type: string

exportSubtreeToZipFile(noteId, format, zipFilePath) → {Promise.<void>}

Parameters:

Name	Type	Description
`noteId`	string
`format`	string	either 'html' or 'markdown'
`zipFilePath`	string

Source:

services/backend_script_api.js, line 530

Returns:

Type: Promise.<void>

getAppInfo() → {Object|*}

Source:

services/backend_script_api.js, line 443

Returns:

- object representing basic info about running Trilium version

Type: Object | *

getAttribute(attributeId) → {BAttribute|null}

Parameters:

Name	Type	Description
`attributeId`	string

Source:

services/backend_script_api.js, line 78

Returns:

Type: BAttribute | null

getBranch(branchId) → {BBranch|null}

Parameters:

Name	Type	Description
`branchId`	string

Source:

services/backend_script_api.js, line 71

Returns:

Type: BBranch | null

getDayNote(date, rootNoteopt) → {BNote|null}

Returns day note for given date. If such note doesn't exist, it is created.

Parameters:

Name	Type	Attributes	Description
`date`	string		in YYYY-MM-DD format
`rootNote`	BNote	<optional>	specify calendar root note, normally leave empty to use the default calendar

Source:

services/backend_script_api.js, line 324

Returns:

Type: BNote | null

getInstanceName() → {string|null}

Instance name identifies particular Trilium instance. It can be useful for scripts if some action needs to happen on only one specific instance.

Source:

services/backend_script_api.js, line 57

Returns:

Type: string | null

getMonthNote(date, rootNoteopt) → {BNote|null}

Returns month note for given date. If such note doesn't exist, it is created.

Parameters:

Name	Type	Attributes	Description
`date`	string		in YYYY-MM format
`rootNote`	BNote	<optional>	specify calendar root note, normally leave empty to use the default calendar

Source:

services/backend_script_api.js, line 355

Returns:

Type: BNote | null

getNote(noteId) → {BNote|null}

Parameters:

Name	Type	Description
`noteId`	string

Source:

services/backend_script_api.js, line 64

Returns:

Type: BNote | null

getNoteWithLabel(name, valueopt) → {BNote|null}

Retrieves first note with given label name & value

Parameters:

Name	Type	Attributes	Description
`name`	string		attribute name
`value`	string	<optional>	attribute value

Source:

services/backend_script_api.js, line 137

Returns:

Type: BNote | null

getNotesWithLabel(name, valueopt) → {Array.<BNote>}

Retrieves notes with given label name & value

Parameters:

Name	Type	Attributes	Description
`name`	string		attribute name
`value`	string	<optional>	attribute value

Source:

services/backend_script_api.js, line 127

Returns:

Type: Array.<BNote>

getRootCalendarNote() → {BNote|null}

Returns root note of the calendar.

Source:

services/backend_script_api.js, line 314

Returns:

Type: BNote | null

getTodayNote(rootNoteopt) → {BNote|null}

Returns today's day note. If such note doesn't exist, it is created.

Parameters:

Name	Type	Attributes	Description
`rootNote`	BNote	<optional>	specify calendar root note, normally leave empty to use the default calendar

Source:

services/backend_script_api.js, line 333

Returns:

Type: BNote | null

getWeekNote(date, optionsopt, rootNoteopt) → {BNote|null}

Returns note for the first date of the week of the given date.

Parameters:

Name Type Attributes Description

date string in YYYY-MM-DD format

options

object

Properties

Name	Type	Attributes	Default	Description
`startOfTheWeek`	string	<optional>	monday	either "monday" (default) or "sunday"

rootNote BNote <optional> specify calendar root note, normally leave empty to use the default calendar

Source:

services/backend_script_api.js, line 345

Returns:

Type: BNote | null

getYearNote(year, rootNoteopt) → {BNote|null}

Returns year note for given year. If such note doesn't exist, it is created.

Parameters:

Name	Type	Attributes	Description
`year`	string		in YYYY format
`rootNote`	BNote	<optional>	specify calendar root note, normally leave empty to use the default calendar

Source:

services/backend_script_api.js, line 365

Returns:

Type: BNote | null

log(message) → {void}

Log given message to trilium logs and log pane in UI

Parameters:

Name	Type	Description
`message`

Source:

services/backend_script_api.js, line 287

Returns:

Type: void

randomString(length) → {string}

Return randomly generated string of given length. This random string generation is NOT cryptographically secure.

Parameters:

Name	Type	Description
`length`	number	of the string

Source:

services/backend_script_api.js, line 418

Returns:

random string

Type: string

searchForNote(query, searchParamsopt) → {BNote|null}

This is a powerful search method - you can search by attributes and their values, e.g.: "#dateModified =* MONTH AND #log". See https://github.com/zadam/trilium/wiki/Search for full documentation for all options

Parameters:

Name	Type	Attributes	Description
`query`	string
`searchParams`	Object	<optional>

Source:

services/backend_script_api.js, line 113

Returns:

Type: BNote | null

searchForNotes(query, searchParamsopt) → {Array.<BNote>}

Parameters:

Name	Type	Attributes	Description
`query`	string
`searchParams`	Object	<optional>

Source:

services/backend_script_api.js, line 89

Returns:

Type: Array.<BNote>

setNoteToParent(noteId, prefix, parentNoteId) → {void}

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.

Parameters:

Name	Type	Description
`noteId`	string
`prefix`	string
`parentNoteId`	string \| null

Deprecated:

this method is pretty confusing and serves specialized purpose only

Source:

services/backend_script_api.js, line 399

Returns:

Type: void

sortNotes(parentNoteId, sortConfigopt) → {void}

Sort child notes of a given note.

Parameters:

Name	Type	Attributes	Description
`parentNoteId`	string		this note's child notes will be sorted
`sortConfig`	object	<optional>

Properties:

Name	Type	Attributes	Default	Description
`sortConfig.sortBy`	string	<optional>	title	'title', 'dateCreated', 'dateModified' or a label name See https://github.com/zadam/trilium/wiki/Sorting for details.
`sortConfig.reverse`	boolean	<optional>	false
`sortConfig.foldersFirst`	boolean	<optional>	false

Source:

services/backend_script_api.js, line 379

Returns:

Type: void

toggleNoteInParent(present, noteId, parentNoteId, prefix) → {void}

Based on the value, either create or remove branch between note and parent note.

Parameters:

Name	Type	Description
`present`	boolean	true if we want the branch to exist, false if we want it gone
`noteId`	string
`parentNoteId`	string
`prefix`	string	if branch will be created between note and parent note, set this prefix

Source:

services/backend_script_api.js, line 170

Returns:

Type: void

transactional(func) → {?}

This functions wraps code which is supposed to be running in transaction. If transaction already exists, then we'll use that transaction.

Parameters:

Name	Type	Description
`func`	function

Source:

services/backend_script_api.js, line 409

Returns:

result of func callback

Type: ?

unescapeHtml(string) → {string}

Parameters:

Name	Type	Description
`string`	string	to unescape

Source:

services/backend_script_api.js, line 432

Returns:

unescaped string

Type: string