Class: BackendScriptApi

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:

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:

axios :axios

Axios library for HTTP requests. See https://axios-http.com for documentation
Type:
  • axios
Deprecated:
  • use native (browser compatible) fetch() instead
Source:

currentNote :BNote

Note where the script is currently executing. Don't mix this up with the concept of active note
Type:
Source:

dayjs :dayjs

day.js library for date manipulation. See https://day.js.org for documentation
Type:
  • dayjs
Source:

originEntity :AbstractBeccaEntity

Entity whose event triggered this execution
Type:
Source:

sql :module:sql

sql
Type:
Source:

startNote :BNote

Note where the script started executing
Type:
Source:

xml2js :xml2js

xml2js library for XML parsing. See https://github.com/Leonidas-from-XIV/node-xml2js for documentation
Type:
  • xml2js
Source:

Methods

backupNow(backupName) → {Promise}

Parameters:
Name Type Description
backupName string If the backupName is e.g. "now", then the backup will be written to "backup-now.db" file
Source:
Returns:
- resolves once the backup is finished
Type
Promise

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:
Returns:
object having "note" and "branch" keys representing respective objects
Type
Object

createNewNote(params) → {Object}

Parameters:
Name Type Description
params object
Properties
Name Type Attributes Default Description
parentNoteId string
title string
content string | Buffer
type NoteType 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:
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
json boolean <optional>
 false should the note be JSON
isProtected boolean <optional>
 false should the note be protected
type string <optional>
 'text' note type
mime string <optional>
 'text/html' MIME type of the note
attributes Array.<object> <optional>
 [] attributes to be created for this note
Properties
Name Type Attributes Description
type AttributeType 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:
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
id string id of the launcher, only alphanumeric at least 6 characters long
type "note" | "script" | "customWidget" 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)
title string
isVisible boolean <optional>
 false if true, will be created in the "Visible launchers", otherwise in "Available launchers"
icon string <optional>
 name of the boxicon to be used (e.g. "bx-time")
keyboardShortcut string <optional>
 will activate the target note/script upon pressing, e.g. "ctrl+e"
targetNoteId string <optional>
 for type "note"
scriptNoteId string <optional>
 for type "script"
widgetNoteId string <optional>
 for type "customWidget"
Source:
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:
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:
Returns:
Type
void

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

If there's no branch between note and parent note, create one. Otherwise, do nothing. Returns the new or existing branch.
Parameters:
Name Type Description
noteId string
parentNoteId string
prefix string if branch is created between note and parent note, set this prefix
Source:
Returns:
Type
Object

escapeHtml(string) → {string}

Parameters:
Name Type Description
string string to escape
Source:
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:
Returns:
Type
Promise.<void>

getAppInfo() → {Object|*}

Source:
Returns:
- object representing basic info about running Trilium version
Type
Object | *

getAttachment(attachmentId) → {BAttachment|null}

Parameters:
Name Type Description
attachmentId string
Source:
Returns:
Type
BAttachment | null

getAttribute(attributeId) → {BAttribute|null}

Parameters:
Name Type Description
attributeId string
Source:
Returns:
Type
BAttribute | null

getAttribute(attributeId) → {BAttribute|null}

Parameters:
Name Type Description
attributeId string
Source:
Returns:
Type
BAttribute | null

getBranch(branchId) → {BBranch|null}

Parameters:
Name Type Description
branchId string
Source:
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:
Returns:
Type
BNote | null

getEtapiToken(etapiTokenId) → {BEtapiToken|null}

Parameters:
Name Type Description
etapiTokenId string
Source:
Returns:
Type
BEtapiToken | null

getEtapiTokens() → {Array.<BEtapiToken>}

Source:
Returns:
Type
Array.<BEtapiToken>

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:
Returns:
Type
string | null

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

Returns month note for given date. If such a 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:
Returns:
Type
BNote | null

getNote(noteId) → {BNote|null}

Parameters:
Name Type Description
noteId string
Source:
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:
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:
Returns:
Type
Array.<BNote>

getOption(optionName) → {BOption|null}

Parameters:
Name Type Description
optionName string
Source:
Returns:
Type
BOption | null

getOptions() → {Array.<BOption>}

Source:
Returns:
Type
Array.<BOption>

getRevision(revisionId) → {BRevision|null}

Parameters:
Name Type Description
revisionId string
Source:
Returns:
Type
BRevision | null

getRootCalendarNote() → {BNote|null}

Returns root note of the calendar.
Source:
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:
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 <optional>
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:
Returns:
Type
BNote | null

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

Returns year note for given year. If such a 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:
Returns:
Type
BNote | null

log(message) → {void}

Log given message to trilium logs and log pane in UI
Parameters:
Name Type Description
message
Source:
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 int of the string
Source:
Returns:
random string
Type
string

runOnFrontend(script, params) → {undefined}

Executes given anonymous function on the frontend(s). Internally, this serializes the anonymous function into string and sends it to frontend(s) via WebSocket. Note that there can be multiple connected frontend instances (e.g. in different tabs). In such case, all instances execute the given function.
Parameters:
Name Type Description
script string script to be executed on the frontend
params Array.<?> list of parameters to the anonymous function to be sent to frontend
Source:
Returns:
- no return value is provided.
Type
undefined

runOutsideOfSync(callback) → {Promise}

Sync process can make data intermittently inconsistent. Scripts which require strong data consistency can use this function to wait for a possible sync process to finish and prevent new sync process from starting while it is running. Because this is an async process, the inner callback doesn't have automatic transaction handling, so in case you need to make some DB changes, you need to surround your call with api.transactional(...)
Parameters:
Name Type Description
callback function function to be executed while sync process is not running
Source:
Returns:
- resolves once the callback is finished (callback is awaited)
Type
Promise

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:
Returns:
Type
BNote | null

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

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:
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:
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
sortBy string <optional>
 title 'title', 'dateCreated', 'dateModified' or a label name See https://github.com/zadam/trilium/wiki/Sorting for details.
reverse boolean <optional>
 false
foldersFirst boolean <optional>
 false
Source:
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 is created between note and parent note, set this prefix
Source:
Returns:
Type
void

transactional(func) → {any}

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:
Returns:
result of func callback
Type
any

unescapeHtml(string) → {string}

Parameters:
Name Type Description
string string to unescape
Source:
Returns:
unescaped string
Type
string